GRFSpecs - User contributions [en-gb]

NML:Stations

2012-09-18T15:05:33Z

Hirundo: /* Station variables */ Some additions / corrections

{{NMLNavPropVarCB}}
Stations in NML are currently a work-in-progress. Therefore, things may be added, changed or removed without notice. At the moment, it is not yet possible to write your own station NewGRF in NML.

==Station properties==
There are no properties defined yet

==Station variables==

===Base station variables===
The following variables are shared between stations and [[NML:Airports|airports]]:

{| class="t"
! name
! value range
! comment
|-
| had_vehicle_of_type
| bitmask(HAD_VEHICLE_OF_TYPE_XXX, ...)
| Bitmask of vehicle types that have visited the station. XXX = <nowiki>[TRAIN | BUS | TRUCK | AIRCRAFT | SHIP]</nowiki>.
|-
| is_waypoint
| [0 <nowiki>|</nowiki> 1]
| Whether the station is a waypoint
|-
| facilities
| bitmask(FACILITY_XXX, ...)
| Bitmask of facilities associated with the station. XXX = <nowiki>[TRAIN | TRUCK_STOP | BUS_STOP | AIRPORT | DOCK]</nowiki>.
|-
| airport_type
| AIRPORTTYPE_XXX
| Type of airport, contains a bogus value if the station has no airport. XXX = <nowiki>[SMALL | LARGE | HELIPORT | OILRIG]</nowiki>.
|-
| build_date
| <code style="color:green">date</code>(yyyy,mm,dd)
| Date when the station was built. Is clamped to the 1920-2099 range.
|}

The following variables are also shared with [[NML:Airports|airports]]. They all require a single argument: a cargo type from your [[NML:Cargotable|cargo translation table]].

{| class="t"
! name
! value range
! comment
|-
| cargo_amount_waiting
| 0..32767
| Units of cargo of waiting
|-
| cargo_rating
| 0..100
| Rating for this cargo type (in %)

|-
| cargo_time_since_pickup
| 0..255
| Time since the cargo was last picked up. 1 unit equals 185 ticks, or about 2.5 game days.
|-
| cargo_time_en_route
| 0..255
| Time this cargo has spent en-route. 1 unit equals 185 ticks, or about 2.5 game days.
|-
| cargo_last_vehicle_speed
| 0..255
| Speed of the last vehicle picking up this cargo type. The unit depends on the type of vehicle. For trains and road vehicles, one unit is 1 km/h; for ships, it's 0.5 km/h; for aircraft, it's 8 mph. If the max. speed is above 255 speed units, 255 is used instead. 0 if no vehicle as picked up the cargo type yet.
|-
| cargo_last_vehicle_age
| 0..255
| Age of the last vehicle picking up this cargo type, in years. 255 if no vehicle has picked up the cargo type yet.
|-
| cargo_accepted
| [0 <nowiki>|</nowiki> 1]
| 1 if this cargo type is currently being accepted at the station, 0 otherwise.
|-
| cargo_accepted_ever
| [0 <nowiki>|</nowiki> 1]
| 1 if this cargo type has ever been accepted at the station, 0 otherwise.
|-
| cargo_accepted_last_month
| [0 <nowiki>|</nowiki> 1]
| 1 if this cargo type was accepted last month at the station, 0 otherwise.
|-
| cargo_accepted_this_month
| [0 <nowiki>|</nowiki> 1]
| 1 if this cargo type was accepted this month at the station, 0 otherwise.
|-
| cargo_accepted_bigtick
| [0 <nowiki>|</nowiki> 1]
| 1 if this cargo type was accepted at the station since the last periodic processing, which happens every 250 ticks. 0 otherwise.
|}

===Variables without a parameter===

{| class="t"
! name
! value range
! comment
|-
| tile_type
| 0..7
| The type of tile, as defined in your station layout
|-
| terrain_type
| TILETYPE_XX
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|-
| track_type
| Entry from [[NML:Railtypetable|railtype translation table]]
|
|-
| company_num
| 0 ... 14
| company number of the vehicle owner. TTDPatch only supports up to 8 companies (0 ... 7)
|-
| company_type
| PLAYERTYPE_XX
|
;PLAYERTYPE_HUMAN
:human player
;PLAYERTYPE_AI
:AI player
;PLAYERTYPE_HUMAN_IN_AI
:human managing AI company
;PLAYERTYPE_AI_IN_HUMAN
:AI managing human company

OpenTTD only uses PLAYERTYPE_HUMAN and PLAYERTYPE_AI. If you cheat yourself to be part of an AI company OpenTTD will still report PLAYERTYPE_AI for the company with yourself and the AI and it'll report PLAYERTYPE_HUMAN for the now uncontrolled company.
|-
| company_colour1
| COLOUR_XXX
|
Refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for possible values.
|-
| company_colour2
| COLOUR_XXX
|
Same as company_colour1, if no 2nd company colour is chosen. Refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for possible values.
|-
| pbs_reserved
| [0 <nowiki>|</nowiki> 1]
| 1 if the tile has been reserved by a train for PBS (Path-based signalling) purposes, 0 otherwise.
|-
| pbs_reserved_or_disabled
| [0 <nowiki>|</nowiki> 1]
| 1 if the tile has been reserved by a train for PBS (Path-based signalling) purposes, or if PBS is not enabled. Currently PBS is always considered enabled if the game version used supports it, but in the future, this may change to check if the current signal block actually uses PBS-signals.
|-
| pbs_enabled
| [0 <nowiki>|</nowiki> 1]
| 1 if PBS is enabled. Currently PBS is always considered enabled if the game version used supports it, but in the future, this may change to check if the current signal block actually uses PBS-signals.
|-
| rail_continuation
| bitmask(0, ... 7)
| [[#Rail continuation|see below]]
|-
| rail_present
| bitmask(0, ... 7)
| [[#Rail continuation|see below]]
|-
| animation_frame
| 0..255
| Animation frame of the current tile.
|}

====Rail continuation====
Variables <code>rail_continuation</code> and <code>rail_present</code> both contain a bitmask, with 8 possible bits set. Each bit corresponds to one of the adjacent tiles, refer to the table or picture below. The bit in <code>rail_present</code> is set if the tile contains any rail track. Bits 0..3 in <code>rail_continuation</code> are only set if there is rail track on the tile and if that track connects to the current tile (note that this tile has no connection to the tiles corresponding to bits 2 and 3, but that doesn't matter). Bits 4..7 in <code>rail_continuation</code> are set if there is track on the tile and if that track connects to tile 2 or 3, whichever is applicable.
{| |-
!Bit!!Set if rail continues in direction of...
|-
|0||+Length
|-
|1||-Length
|-
|2||+Platforms
|-
|3||-Platforms
|-
|4||+Length, +Platforms
|-
|5||-Length, +Platforms
|-
|6||+Length, -Platforms
|-
|7||-Length, -Platforms
|}

The following picture illustrates which bits represent which tile for the two possible station orientations:

[[File:station_var45.png]]

===Variables that require one or more arguments===

{| class="t"
! name
! arguments
! value range
! comment
|-
| nearby_tile_slope
| tile- and platform-offset <ref name="offset">The first parameter is the distance to move along the platform, the second parameter is the distance to move sideways (between platforms). Both parameters are signed numbers with range -8..7, negative numbers go northwards.</ref>
| SLOPE_XXX
| See [[NML:List of tile slopes|tile slopes]] for an overview of possible values. Note that the slope is 'mirrored' in the NW-SE orientation, i.e. the bits for CORNER_W and CORNER_E are swapped.
|-
| nearby_tile_is_water
| tile- and platform-offset <ref name="offset"/>
| [0 <nowiki>|</nowiki> 1]
| 1 if the tile is water, 0 otherwise
|-
| nearby_tile_terrain_type
| tile- and platform-offset <ref name="offset"/>
| TILETYPE_XX
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|-
| nearby_tile_water_class
| tile- and platform-offset <ref name="offset"/>
| WATER_CLASS_XXX
| XXX = [NONE <nowiki>|</nowiki> SEA <nowiki>|</nowiki> CANAL <nowiki>|</nowiki> RIVER] Note that tiles for which <code style="color:darkgreen">nearby_tile_is_water</code> is 0 may still have a water class, e.g. industry tiles with water beneath them.
|-
| nearby_tile_height
| tile- and platform-offset <ref name="offset"/>
| 0..255 (currently limited to 0..15)
| Height of the lowest corner of the tile. 1 unit is one height level of 8 pixels.
|-
| nearby_tile_class
| tile- and platform-offset <ref name="offset"/>
|
[[NML:List of tile classes|Tile class]]
|
|-
| nearby_tile_animation_frame
| tile- and platform-offset <ref name="offset"/>
| 0..255
| Animation frame of the given tile
|-
| nearby_tile_is_station
| tile- and platform-offset <ref name="offset"/>
| [0 <nowiki>|</nowiki> 1]
| 1 if the given tile is a station tile, 0 otherwise
|-
| nearby_tile_station_id
| tile- and platform-offset <ref name="offset"/>
| 0..255
| If the given tile is a station tile defined by this NewGRF, the item ID. Else, the content is undefined.
|-
| nearby_tile_same_grf
| tile- and platform-offset <ref name="offset"/>
| [0 <nowiki>|</nowiki> 1]
| 1 if the given tile is a station tile defined by this NewGRF, 0 otherwise.
|-
| nearby_tile_other_grf
| tile- and platform-offset <ref name="offset"/>
| [0 <nowiki>|</nowiki> 1]
| 1 if the given tile is a station tile defined by a different NewGRF, 0 otherwise.
|-
| nearby_tile_original_gfx
| tile- and platform-offset <ref name="offset"/>
| [0 <nowiki>|</nowiki> 1]
| 1 if the given tile is a station tile with original graphics, 0 otherwise.
|-
| nearby_tile_same_station
| tile- and platform-offset <ref name="offset"/>
| [0 <nowiki>|</nowiki> 1]
| 1 if the given tile is part of the same station, 0 otherwise. Undefined if the tile is not a station tile.
|-
| nearby_tile_perpendicular
| tile- and platform-offset <ref name="offset"/>
| [0 <nowiki>|</nowiki> 1]
| 1 if the given tile a station tile aligned perpendicular to this tile, 0 if it is aligned parallel. Undefined if the tile is not a station tile.
|-
| nearby_tile_platform_type
| tile- and platform-offset <ref name="offset"/>
| 0..3
| Platform type of the given tile. Value is undefined if the tile is not a station tile, else possible values are:
;0:plain platform
;1:platform with building
;2:platform with roof, left side
;3:platform with roof, right side
|-
| platform_length
| PLATFROM_SAME_XXX<ref name="platform">Possible values are:
;PLATFORM_SAME_STATION:Consider all tiles that are part of the same station
;PLATFORM_SAME_SECTION:Consider all tiles that are part of the same individually built section
;PLATFORM_SAME_DIRECTION:Consdier all tiles that are part of the same station and have the same platform direction.</ref>
| 0..15
| Length of the platform (along the platform direction) in tiles
|-
| platform_count
| PLATFORM_SAME_XXX<ref name="platform"/>
| 0..15
| Number of platforms (counted perpendicular to the platform direction)
|-
| platform_position_from_start
| PLATFORM_SAME_XXX<ref name="platform"/>
| 0..15
| Position along the platform, 0 for the first (northernmost) tile.
|-
| platform_position_from_end
| PLATFORM_SAME_XXX<ref name="platform"/>
| 0..15
| Position along the platform, 0 for the last (southernmost) tile.
|-
| platform_position_from_middle
| PLATFORM_SAME_XXX<ref name="platform"/>
| -8..7
| Position along the platform, 0 for the middle tile. When the number of tiles is even, the southernmost of the two middle tiles is assigned number 0, so there is one more negative than positive number. Using PLATFORM_SAME_DIRECTION is not possible here.
|-
| platform_number_from_start
| PLATFORM_SAME_XXX<ref name="platform"/>
| 0..15
| Platform number, counting from top to bottom, so 0 for the northernmost platform.
|-
| platform_number_from_end
| PLATFORM_SAME_XXX<ref name="platform"/>
| 0..15
| Platform number, counting from bottom to top, so 0 for the southernmost platform.
|-
| platform_number_from_middle
| PLATFORM_SAME_XXX<ref name="platform"/>
| -8..7
| Platform number, counting top to bottom, using 0 for the middle platform. When the number of platforms is even, the southernmost of the two middle platformsis assigned number 0, so there is one more negative than positive number. Using PLATFORM_SAME_DIRECTION is not possible here.
|}
<references/>

==Station callbacks==
There are no callbacks defined yet

NML:Stations

2012-09-17T18:34:53Z

Hirundo: /* Station variables */ Add 60+X variables

{{NMLNavPropVarCB}}
Stations in NML are currently a work-in-progress. Therefore, things may be added, changed or removed without notice. At the moment, it is not yet possible to write your own station NewGRF in NML.

==Station properties==
There are no properties defined yet

==Station variables==

===Base station variables===
The following variables are shared between stations and [[NML:Airports|airports]]:

{| class="t"
! name
! value range
! comment
|-
| had_vehicle_of_type
| bitmask(HAD_VEHICLE_OF_TYPE_XXX, ...)
| Bitmask of vehicle types that have visited the station. XXX = <nowiki>[TRAIN | BUS | TRUCK | AIRCRAFT | SHIP]</nowiki>.
|-
| is_waypoint
| [0 <nowiki>|</nowiki> 1]
| Whether the station is a waypoint
|-
| facilities
| bitmask(FACILITY_XXX, ...)
| Bitmask of facilities associated with the station. XXX = <nowiki>[TRAIN | TRUCK_STOP | BUS_STOP | AIRPORT | DOCK]</nowiki>.
|-
| airport_type
| AIRPORTTYPE_XXX
| Type of airport, contains a bogus value if the station has no airport. XXX = <nowiki>[SMALL | LARGE | HELIPORT | OILRIG]</nowiki>.
|-
| build_date
| <code style="color:green">date</code>(yyyy,mm,dd)
| Date when the station was built. Is clamped to the 1920-2099 range.
|}

The following variables are also shared with [[NML:Airports|airports]]. They all require a single argument: a cargo type from your [[NML:Cargotable|cargo translation table]].

{| class="t"
! name
! value range
! comment
|-
| cargo_amount_waiting
| 0..32767
| Units of cargo of waiting
|-
| cargo_rating
| 0..100
| Rating for this cargo type (in %)

|-
| cargo_time_since_pickup
| 0..255
| Time since the cargo was last picked up. 1 unit equals 185 ticks, or about 2.5 game days.
|-
| cargo_time_en_route
| 0..255
| Time this cargo has spent en-route. 1 unit equals 185 ticks, or about 2.5 game days.
|-
| cargo_last_vehicle_speed
| 0..255
| Speed of the last vehicle picking up this cargo type. The unit depends on the type of vehicle. For trains and road vehicles, one unit is 1 km/h; for ships, it's 0.5 km/h; for aircraft, it's 8 mph. If the max. speed is above 255 speed units, 255 is used instead
|-
| cargo_last_vehicle_age
| 0..255
| Age of the last vehicle picking up this cargo type, in years.
|-
| cargo_accepted
| [0 <nowiki>|</nowiki> 1]
| 1 if this cargo type is currently being accepted at the station, 0 otherwise.
|-
| cargo_accepted_ever
| [0 <nowiki>|</nowiki> 1]
| 1 if this cargo type has ever been accepted at the station, 0 otherwise.
|-
| cargo_accepted_last_month
| [0 <nowiki>|</nowiki> 1]
| 1 if this cargo type was accepted last month at the station, 0 otherwise.
|-
| cargo_accepted_this_month
| [0 <nowiki>|</nowiki> 1]
| 1 if this cargo type was accepted this month at the station, 0 otherwise.
|-
| cargo_accepted_bigtick
| [0 <nowiki>|</nowiki> 1]
| 1 if this cargo type was accepted at the station since the last periodic processing, which happens every 250 ticks. 0 otherwise.
|}

===Variables without a parameter===

{| class="t"
! name
! value range
! comment
|-
| tile_type
| 0..7
| The type of tile, as defined in your station layout
|-
| terrain_type
| TILETYPE_XX
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|-
| track_type
| Entry from [[NML:Railtypetable|railtype translation table]]
|
|-
| company_num
| 0 ... 14
| company number of the vehicle owner. TTDPatch only supports up to 8 companies (0 ... 7)
|-
| company_type
| PLAYERTYPE_XX
|
;PLAYERTYPE_HUMAN
:human player
;PLAYERTYPE_AI
:AI player
;PLAYERTYPE_HUMAN_IN_AI
:human managing AI company
;PLAYERTYPE_AI_IN_HUMAN
:AI managing human company

OpenTTD only uses PLAYERTYPE_HUMAN and PLAYERTYPE_AI. If you cheat yourself to be part of an AI company OpenTTD will still report PLAYERTYPE_AI for the company with yourself and the AI and it'll report PLAYERTYPE_HUMAN for the now uncontrolled company.
|-
| company_colour1
| COLOUR_XXX
|
Refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for possible values.
|-
| company_colour2
| COLOUR_XXX
|
Same as company_colour1, if no 2nd company colour is chosen. Refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for possible values.
|-
| pbs_reserved
| [0 <nowiki>|</nowiki> 1]
| 1 if the tile has been reserved by a train for PBS (Path-based signalling) purposes, 0 otherwise.
|-
| pbs_reserved_or_disabled
| [0 <nowiki>|</nowiki> 1]
| 1 if the tile has been reserved by a train for PBS (Path-based signalling) purposes, or if PBS is not enabled. Currently PBS is always considered enabled if the game version used supports it, but in the future, this may change to check if the current signal block actually uses PBS-signals.
|-
| pbs_enabled
| [0 <nowiki>|</nowiki> 1]
| 1 if PBS is enabled. Currently PBS is always considered enabled if the game version used supports it, but in the future, this may change to check if the current signal block actually uses PBS-signals.
|-
| rail_continuation
| bitmask(0, ... 7)
| [[#Rail continuation|see below]]
|-
| rail_present
| bitmask(0, ... 7)
| [[#Rail continuation|see below]]
|-
| animation_frame
| 0..255
| Animation frame of the current tile.
|}

====Rail continuation====
Variables <code>rail_continuation</code> and <code>rail_present</code> both contain a bitmask, with 8 possible bits set. Each bit corresponds to one of the adjacent tiles, refer to the table or picture below. The bit in <code>rail_present</code> is set if the tile contains any rail track. Bits 0..3 in <code>rail_continuation</code> are only set if there is rail track on the tile and if that track connects to the current tile (note that this tile has no connection to the tiles corresponding to bits 2 and 3, but that doesn't matter). Bits 4..7 in <code>rail_continuation</code> are set if there is track on the tile and if that track connects to tile 2 or 3, whichever is applicable.
{| |-
!Bit!!Set if rail continues in direction of...
|-
|0||+Length
|-
|1||-Length
|-
|2||+Platforms
|-
|3||-Platforms
|-
|4||+Length, +Platforms
|-
|5||-Length, +Platforms
|-
|6||+Length, -Platforms
|-
|7||-Length, -Platforms
|}

The following picture illustrates which bits represent which tile for the two possible station orientations:

[[File:station_var45.png]]

===Variables that require one or more arguments===

{| class="t"
! name
! arguments
! value range
! comment
|-
| nearby_tile_slope
| x- and y-offset (both signed, range -8..7)
| SLOPE_XXX
| See [[NML:List of tile slopes|tile slopes]] for an overview of possible values
|-
| nearby_tile_is_water
| x- and y-offset (both signed, range -8..7)
| [0 <nowiki>|</nowiki> 1]
| 1 if the tile is water, 0 otherwise
|-
| nearby_tile_terrain_type
| x- and y-offset (both signed, range -8..7)
| TILETYPE_XX
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|-
| nearby_tile_water_class
| x- and y-offset (both signed, range -8..7)
| WATER_CLASS_XXX
| XXX = [NONE <nowiki>|</nowiki> SEA <nowiki>|</nowiki> CANAL <nowiki>|</nowiki> RIVER] Note that tiles for which <code style="color:darkgreen">nearby_tile_is_water</code> is 0 may still have a water class, e.g. industry tiles with water beneath them.
|-
| nearby_tile_height
| x- and y-offset (both signed, range -8..7)
| 0..255 (currently limited to 0..15)
| Height of the lowest corner of the tile. 1 unit is one height level of 8 pixels.
|-
| nearby_tile_class
| x- and y-offset (both signed, range -8..7)
|
[[NML:List of tile classes|Tile class]]
|
|-
| nearby_tile_animation_frame
| x- and y-offset (both signed, range -8..7)
| 0..255
| Animation frame of the given tile
|-
| nearby_tile_is_station
| x- and y-offset (both signed, range -8..7)
| [0 <nowiki>|</nowiki> 1]
| 1 if the given tile is a station tile, 0 otherwise
|-
| nearby_tile_station_id
| x- and y-offset (both signed, range -8..7)
| 0..255
| If the given tile is a station tile defined by this NewGRF, the item ID. Else, the content is undefined.
|-
| nearby_tile_same_grf
| x- and y-offset (both signed, range -8..7)
| [0 <nowiki>|</nowiki> 1]
| 1 if the given tile is a station tile defined by this NewGRF, 0 otherwise.
|-
| nearby_tile_other_grf
| x- and y-offset (both signed, range -8..7)
| [0 <nowiki>|</nowiki> 1]
| 1 if the given tile is a station tile defined by a different NewGRF, 0 otherwise.
|-
| nearby_tile_original_gfx
| x- and y-offset (both signed, range -8..7)
| [0 <nowiki>|</nowiki> 1]
| 1 if the given tile is a station tile with original graphics, 0 otherwise.
|-
| nearby_tile_same_station
| x- and y-offset (both signed, range -8..7)
| [0 <nowiki>|</nowiki> 1]
| 1 if the given tile is part of the same station, 0 otherwise. Undefined if the tile is not a station tile.
|-
| nearby_tile_perpendicular
| x- and y-offset (both signed, range -8..7)
| [0 <nowiki>|</nowiki> 1]
| 1 if the given tile a station tile aligned perpendicular to this tile, 0 if it is aligned parallel. Undefined if the tile is not a station tile.
|-
| nearby_tile_platform_type
| x- and y-offset (both signed, range -8..7)
| 0..3
| Platform type of the given tile. Value is undefined if the tile is not a station tile, else possible values are:
;0:plain platform
;1:platform with building
;2:platform with roof, left side
;3:platform with roof, right side
|-
| platform_length
| PLATFROM_SAME_XXX<ref name="platform">Possible values are:
;PLATFORM_SAME_STATION:Consider all tiles that are part of the same station
;PLATFORM_SAME_SECTION:Consider all tiles that are part of the same individually built section
;PLATFORM_SAME_DIRECTION:Consdier all tiles that are part of the same station and have the same platform direction.</ref>
| 0..15
| Length of the platform (along the platform direction) in tiles
|-
| platform_count
| PLATFORM_SAME_XXX<ref name="platform"/>
| 0..15
| Number of platforms (counted perpendicular to the platform direction)
|-
| platform_position_from_start
| PLATFORM_SAME_XXX<ref name="platform"/>
| 0..15
| Position along the platform, 0 for the first (northernmost) tile.
|-
| platform_position_from_end
| PLATFORM_SAME_XXX<ref name="platform"/>
| 0..15
| Position along the platform, 0 for the last (southernmost) tile.
|-
| platform_position_from_middle
| PLATFORM_SAME_XXX<ref name="platform"/>
| -8..7
| Position along the platform, 0 for the middle tile. When the number of tiles is even, the southernmost of the two middle tiles is assigned number 0, so there is one more negative than positive number. Using PLATFORM_SAME_DIRECTION is not possible here.
|-
| platform_number_from_start
| PLATFORM_SAME_XXX<ref name="platform"/>
| 0..15
| Platform number, counting from top to bottom, so 0 for the northernmost platform.
|-
| platform_number_from_end
| PLATFORM_SAME_XXX<ref name="platform"/>
| 0..15
| Platform number, counting from bottom to top, so 0 for the southernmost platform.
|-
| platform_number_from_middle
| PLATFORM_SAME_XXX<ref name="platform"/>
| -8..7
| Platform number, counting top to bottom, using 0 for the middle platform. When the number of platforms is even, the southernmost of the two middle platformsis assigned number 0, so there is one more negative than positive number. Using PLATFORM_SAME_DIRECTION is not possible here.
|}
<references/>

==Station callbacks==
There are no callbacks defined yet

NML:Stations

2012-09-17T16:40:54Z

Hirundo: /* Station variables */ Add 40+x variables

NML:Airports

2012-09-16T20:40:24Z

Hirundo: /* Airport variables */ Add link to base station vars

{{NMLNavPropVarCB}}

Airports and airport tiles can only be defined in OpenTTD {{ottd|1.1|r19459}} or later.

==Airport (tile) IDs==
Airport and airport tile IDs are local to the NewGRF, you are free to choose any ID in the 0..255-range. For airport tiles, you should start your item definition with the 'substitute'-property, which allocates a new airport tile. The value of this property should be the ID of a [[AirportTileDefaultProps|default airport 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 airport tile to be replaced with your item. For airports, there only is an 'override'-property, which acts as a combined substitute and override.

==Airport properties==

{| class="t"
! name
! value range
! comment
|-
| name
| string
|
{{ottd|1.1|r19459}} Name of the airport
|-
| override
|
|
{{ottd|1.1|r19459}} The id of airport to replace / override, see [[AirportTypes]].
|-
| layouts
| list of layouts
|
{{ottd|1.1|r20377}}
|-
| years_available
| [start year, last year]
|
{{ottd|1.1|r19459}} List of the availablility years: first and last year it can be built
|-
| ttd_airport-type
| 0 ... 3
|
{{ottd|1.1|r19459}} Substitute TTDPatch airport type
|-
| catchment_area
|
|
{{ottd|1.1|r19459}} Catchment area of the airport in tiles around its perimeter
|-
| noise_level
|
|
{{ottd|1.1|r19459}} Noise generation of this airport
|-
| maintenance_cost
|
|
{{ottd|1.2|r23415}} Maintenance cost factor for this airport
|}

==Airport tile properties==

{| class="t"
! name
! value range
! comment
|-
| override
|
|
{{ottd|1.1|r19204}} The id of airport tile to override, see [[AirportTypes]].
|-
| substitute
|
|
{{ottd|1.1|r19204}} The id of airport tile to replace
|-
| callback_flags
| bitmask
|
{{ottd|1.1|r19204}} Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| animation_info
|
|
{{ottd|1.1|r19204}}
|-
| animation_speed
|
|
{{ottd|1.1|r19204}} See [[NML:Animation speed|speed settings]]
|-
| animation_triggers
| bitmask(ANIM_TRIGGER_APT_XXX, ... )
|
{{ottd|1.1|r19204}} Bitmask of triggers that will trigger the <code style="color:darkgreen">anim_control</code> callback, see the [[#Animation triggers|table]] below.
|}

==Airport variables==

A number of variables are shared between airports and stations. These are listed on the [[NML:Stations#Base station variables|stations]] page.

{| class="t"
! name
! value range
! comment
|-
| layout
| 0 .. (number of layouts - 1)
|
{{ottd|1.1|r20364}} Layout number of the airport (index in the layouts array)
|}

==Airport tile variables==

{| class="t"
! name
! value range
! comment
|-
| terrain_type
|
|
|-
| town_radius_group
|
|
|-
| 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 [[NML:Builtin functions|builtin function]] relative_coord(x, y) may be useful when making comparisons.
|-
| animation_frame
|
|
|}

The following variables require a signed x,y offset as parameters. The offset is relative to the current tile. Offset 0,0 means the current tile.

{| class="t"
! name
! value range
! comment
|-
| nearby_tile_slope
| SLOPE_XXX
|
See [[NML:List of tile slopes|tile slopes]] for an overview of possible values
|-
| nearby_tile_is_same_airport
| 1 if the tile is part of the same airport, 0 otherwise
|
|-
| 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 <nowiki>|</nowiki> SEA <nowiki>|</nowiki> CANAL <nowiki>|</nowiki> RIVER] Note that tiles for which <code style="color:darkgreen">nearby_tile_is_water</code> 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
|
[[NML:List of tile classes|Tile class]]
|
|-
| nearby_tile_animation_frame
| 0..255
| Animation frame of the given tile
|-
| nearby_tile_airporttile_id
| 0x00aa, 0xFFbb, 0xFFFE or 0xFFFF
| 0x00aa: The tile is an airport tile that is part of this GRF, the tile id is aa. 0xFFbb: The tile is an original airport tile with id bb. 0xFFFE: The tile is an airport tile defined in another GRF. 0xFFFF: The tile is not an airport tile or it belongs to another GRF.
|}

==Airport callbacks==

{| class="t"
! callback
! return value
! comment
|-
| default
| Sprite set (with 1 sprite)
| Preview graphics to use in the build menu. One sprite per layout may be given, use the <code style="color:darkgreen">layout</code> to distinguish between layouts.
|-
| additional_text
| String
| Additional text to show in the buy menu. String may differ per layout, use the <code style="color:darkgreen">layout</code> variable for this.
|-
| layout_name
| String
| Name of the airport layout in the variable <code style="color:darkgreen">layout</code>
|}

Note that, although the airport isn't built yet, the <code style="color:darkgreen">layout</code> variable is always available and set to the layout the user has selected in the GUI.

==Airport tile callbacks==

{| class="t"
! callback
! return value
! comment
|-
| default
| Sprite layout
| Graphics for an airport tile
|-
| 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. <code style="color:darkgreen">extra_callback_info1</code> contains random bits. Returning a sound effect in the high byte will cause that sound effect to be played.
|-
| 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 <nowiki>|</nowiki> STOP_ANIMATION <nowiki>|</nowiki> DO_NOTHING] to respectively start the animation in its current frame, stop the animation or do nothing. <code style="color:darkgreen">extra_callback_info1</code> contains random bits. Returning a sound effect in the high byte will cause that sound effect to be played. <code style="color:darkgreen">extra_callback_info2</code> contains the reason to trigger the animation, see the [[#Animation triggers|table]] below. Note that you need to enable the wanted triggers in the <code style="color:darkgreen">animation_triggers</code> property.
|-
| 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.
|-
| foundations
| CB_RESULT[_NO]_FOUNDATIONS
| Return CB_RESULT_FOUNDATIONS to draw standard foundations (default) or CB_RESULT_NO_FOUNDATIONS to not draw them.
|}

===Animation triggers===

{| class="t"
! Animation trigger
! Description
|-
| ANIM_TRIGGER_APT_BUILT
| Airport is built (all tiles at the same time)
|-
| ANIM_TRIGGER_APT_TILELOOP
| Airport tile is processed in the tileloop (at different times for different tiles)
|-
| ANIM_TRIGGER_APT_NEW_CARGO
| New cargo arrives at the airport (all tiles at the same time)
|-
| ANIM_TRIGGER_APT_CARGO_TAKEN
| All cargo of a cargo type is removed from the airport (all tiles at the same time)
|-
| ANIM_TRIGGER_APT_250_TICKS
| Every 250 ticks (all tiles at the same time)
|}

NML:Stations

2012-09-16T20:39:17Z

Hirundo: /* Base station variables */ Make clear that 2nd table is shared also

NML:Stations

2012-09-16T20:38:07Z

Hirundo: Add base station variables

NML:Stations

2012-09-16T19:55:54Z

Hirundo: Add stub page

NML:Switch

2012-09-11T22:01:46Z

Hirundo: Add note about new possibilities for defaults

{{NMLNavBlocksyntax}}

switch (<expression>, (SELF|PARENT), <ID>, <expression>) {
(<range>: <return_value>;)*
<return_value>;
}

The four parameters have the following meaning:

* <code style="color:darkgreen"><expression></code>: The feature for which this switch is used (see [[NML:Features|Features]]).
* <code style="color:darkgreen">(SELF|PARENT)</code>Which variables to use. SELF uses the variables of the item itself, while PARENT uses the variables of a related object. This related object differs per feature, refer to the table below.
* <code style="color:darkgreen"><ID></code>Name of this switch block. This (unique) name can be used to refer to the block from other switch- or graphics-blocks.
* <code style="color:darkgreen"><expression></code>The expression that will be evaluated to make a decision. This expression may contain variables. Instead of a single expression this may also be an array of expressions. In that case all of the array elements are evaluated in order and the last one is used to make a decision.

{| class="t"
! Feature
! SELF
! PARENT
! permanent storage
|-
| FEAT_TRAINS
| Engine / wagon / articulated part itself
| Front engine
| no
|-
| FEAT_ROADVEHS
| Road vehicle part
| First road vehicle part
| no
|-
| FEAT_SHIPS
| Ship
| Ship
| no
|-
| FEAT_AIRCRAFT
| Aircraft (a)
| Aircraft
| no
|-
| FEAT_STATIONS
| Station tile
| Town
| no
|-
| FEAT_CANALS
| Canal tile
| N/A
| no
|-
| FEAT_BRIDGES
| Bridge
| Town
| no
|-
| FEAT_HOUSES
| House tile
| Town
| no
|-
| FEAT_GLOBALVARS
| N/A
| N/A
| no
|-
| FEAT_INDUSTRYTILES
| Industry tile
| Industry to which the tile belongs
| no
|-
| FEAT_INDUSTRIES
| Industry
| Town
| yes
|-
| FEAT_CARGOS
| Cargo type
| N/A
| no
|-
| FEAT_SOUNDEFFECTS
| N/A
| N/A
| no
|-
| FEAT_AIRPORTS
| Airport
| N/A
| yes
|-
| FEAT_SIGNALS
| N/A
| N/A
| no
|-
| FEAT_OBJECTS
| Object tile
| Town
| no
|-
| FEAT_RAILTYPES
| Rail tile
| N/A
| no
|-
| FEAT_AIRPORTTILES
| Airport tile
| Airport
| no
|}

(a) Except for mail capacity callbacks, where it refers to the mail compartment. To refer to the aircraft itself, use PARENT scope there.

<code style="color:darkgreen"><range></code> can either be a single number or two numbers separated by two dots. In the first case, the range matches if the result of the computation is equal to the supplied value. If a range (<code style="color:darkgreen">a .. b</code>) is supplied, it matches if the computed result is within that range. If several lines of the switch block match the expression being tested the first applicable result will be returned.

Possible values for <code style="color:darkgreen"><return_value></code> are the following:

* <code style="color:darkgreen"><ID>;</code> chains to the (random-)switch or spritegroup with the given ID.
* <code style="color:darkgreen">return (<expression>|<string>);</code> returns the given expression or string as a result of the callback. A returned expression may contain variables (with the same scope as the switch block itself), parameter accesses and everything else that a normal switch-expression may contain.
* <code style="color:darkgreen">return;</code> returns the computed value directly as a callback result. Note that the maximum value for callback results is 32511 (0x7EFF).
* <code style="color:darkgreen">CB_FAILED;</code> stops processing and returns an explicit failure code.

Some example code is given below. Note that the code does not have an actual meaning, it is merely meant to demonstrate all the various options available.

<pre style="color:blue">
switch (FEAT_TRAINS, PARENT, some_vehicle_switch, (position_in_consist + param[1]) % 4) {
0..2: return string(STRING_FOO_BAR); //return a text message
3: return; //return the computed value
5..300: return 42; //42 is always a good answer
400: other_switch; //chain to some other switch block
401: return num_vehs_in_consist + 1; //return a value with a variable access
CB_FAILED; //return a failure result as default
}
</pre>

You can also use temporary variables and with some features also pemanent variables to store and retrieve some values by means of <code style="color:darkgreen">STORE_TEMP(value, register)</code>, <code style="color:darkgreen">LOAD_TEMP(register)</code> and <code style="color:darkgreen">STORE_PERM(value, register)</code> and <code style="color:darkgreen">LOAD_PERM(register[, grfid])</code> respectively. Using temporary storage is useful when you want to use the result of an expensive calculation in various decisions (switches) within the chain (like for example the number of a certain wagon type within a train). Permanent storage might be useful to control the long-term behaviour of an object. Note that it is only available for industries, airports and towns. For towns, you can optionally specify a grfid to load registers belonging to a different grf. Note that accessing (both reading and writing) permanent town registers thrashes the contents of temporary register 0x100.

{{nml|0.3}} As of NML 0.3 it is possible to specify the default value using <code>default: <value>;</code> as one of the 'ranges'. Specifying multiple default values (either this way or by the classical method) is of course not possible, but omitting a default value is allowed. In that case, if none of the ranges matches, the callback fails.

NML:Industries

2012-09-11T19:50:34Z

Hirundo: /* Industry variables */ Fix: add missing NML version tags

{{NMLNavPropVarCB}}

This page contains information on both industry and industry tile properties, variables and callbacks.

== Industry (tile) ID allocation ==
Industry and 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 [[IndustryDefaultProps|default industry]] or [[IndustryTileDefaultProps|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 properties==

Industry properties. Default industry type numbers can be found at [[NML:Default industries|default industries]].

{| class="t"
! property
! value range
! comment
|-
| substitute
| industry type
| Number of the original industry type that replaces this one, should it not be available for some reason (e.g. missing NewGRF). This ''must'' be the first property to be set, before any other properties or graphics. All properties of the old type are copied to your new industry.
|-
| override
| industry type
| Number of the original industry type overridden. This will cause other grfs / industries to consider your industry type the same as the old type. Only set this property if your type is (more or less) the same as the old type.
|-
| layouts
| Array of tilelayouts
|
See [[NML:Tilelayout|Tilelayout]] syntax.
|-
| life_type
| One of IND_LIFE_TYPE_XXX, XXX = BLACK_HOLE <nowiki>|</nowiki> EXTRACTIVE <nowiki>|</nowiki> ORGANIC <nowiki>|</nowiki> PROCESSING
| The generic type of industry. This determines the production changes that occur by default (when not using the callback). Examples are respectively power plants, coal mines, forests en steel mills.
|-
| closure_msg
| string
|
Message displayed when the industry announces closure. Use a custom string or one of the [[NML:Default TTD strings|default TTD strings]].
|-
| prod_increase_msg
| string
|
Message displayed when industry increases production. Use a custom string or one of the [[NML:Default TTD strings|default TTD strings]].
|-
| prod_decrease_msg
| string
|
Message displayed when industry decreases production. Use a custom string or one of the [[NML:Default TTD strings|default TTD strings]].
|-
| fund_cost_multiplier
| 0..255
| Fund cost multiplier. Note that in OpenTTD the unmodified base cost is 8x higher for building (not prospecting) raw (=extractive / organic, see life_type) industries.
|-
| prod_cargo_types
| array of up to 2 ints
| Types of cargo produced. Use the cargotype(<label>) built-in function to specify a label from the cargotable.
|-
| accept_cargo_types
| array of up to 3 ints
| Types of cargo accepted. Use the cargotype(<label>) built-in function to specify a label from the cargotable
|-
| prod_multiplier
| array of up to 2 ints (0..255)
| Amount of each output cargo to produce every 256 ticks (8 or 9 times a month)
|-
| min_cargo_distr
| 0..255
| Minimal amount of cargo before transporting to stations.
|-
| random_sound_effects
| array of ints
| Sound effect numbers that are played some times.
|-
| conflicting_ind_types
| array of up to 3x industry_type(IND_TYPE_OLD <nowiki>|</nowiki> IND_TYPE_NEW, id)
|
Three industry types that should not be nearby. Use the [[NML:Builtin functions|builtin function]] <code style="color:darkgreen">industry_type(..)</code> to define either an old industry (using the global ID) or a new industry from your grf (using the grf-local ID).
|-
| prob_random
| 0..255
| Probability of occurring while generating initial industries.
|-
| prob_in_game
| 0..255
| Probability of occurring while creating industries during the game.
|-
| map_colour
| 0..255
|
Colour index from the [[NML:Graphic files|DOS palette]] to use on the minimap for this industry.
|-
| spec_flags
| bitmask(flags)
|
for flag values see [[#industry_special_flags|Industry special flags]]
|-
| new_ind_msg
| string
| Message displayed when industry gets built during game play.
|-
| input_multiplier_1
| array of up to 2 floats (0..255)
| Output cargo multiplication factors for getting a unit of the first accepted cargo.
|-
| input_multiplier_2
| array of up to 2 floats (0..255)
| Output cargo multiplication factors for getting a unit of the second accepted cargo.
|-
| input_multiplier_3
| array of up to 2 floats (0..255)
| Output cargo multiplication factors for getting a unit of the third accepted cargo.
|-
| name
| string
|
Name of the industry, use a custom string or one of the [[NML:Default TTD strings|default TTD strings]].
|-
| prospect_chance
| 0 .. 1 (float)
| Chance of successful prospecting.
|-
| callback_flags
| bitmask(flags)
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| remove_cost_multiplier
| int
| Cost multiplier for removing the industry (currently only possible with magic bulldozer).
|-
| nearby_station_name
| string
| Default additional name for a nearby station
|}

===Industry special flags===

{| class="t"
! flag
! meaning
|-
| IND_FLAG_PLANT_FIELDS_PERIODICALLY
| The industry periodically plants fields around itself (temperate and arctic farms)
|-
| IND_FLAG_CUT_TREES
| The industry cuts trees around itself and produces its first output cargo from them (lumber mill)
|-
| IND_FLAG_BUILT_ON_WATER
| The industry is built on water (oil rig)
|-
| IND_FLAG_ONLY_IN_LARGE_TOWNS
| The industry can only be built in towns (i.e. it has to replace houses) with population larger than 1200 (temperate bank)
|-
| IND_FLAG_ONLY_IN_TOWNS
| The industry can only be built in towns (i.e. it has to replace houses) (arctic and tropic banks, water tower)
|-
| IND_FLAG_BUILT_NEAR_TOWN
| The industry is always built near towns (i.e. near town sign; additionally the industry is allowed to replace houses) (toy shop)
|-
| IND_FLAG_PLANT_FIELDS_WHEN_BUILT
| Fields are planted around the industry when it's built (all farms)
|-
| IND_FLAG_NO_PRODUCTION_INCREASE
| The industry cannot increase its production on the temperate climate (oil wells)
|-
| IND_FLAG_BUILT_ONLY_BEFORE_1950
| The industry is built only before 1950 (oil wells)
|-
| IND_FLAG_BUILT_ONLY_AFTER_1960
| The industry is built only after 1960 (oil rig)
|-
| IND_FLAG_AI_CREATES_AIR_AND_SHIP_ROUTES
| AI players will attempt to establish air and ship routes going to this industry (oil rig)
|-
| IND_FLAG_MILITARY_AIRPLANE_CAN_EXPLODE
| The industry can be exploded by a military airplane (oil refinery)
|-
| IND_FLAG_MILITARY_HELICOPTER_CAN_EXPLODE
| The industry can be exploded by a military helicopter (factory)
|-
| IND_FLAG_CAN_CAUSE_SUBSIDENCE
| The industry can cause a subsidence (coal mine)
|-
| IND_FLAG_AUTOMATIC_PRODUCTION_MULTIPLIER
| Automatic production multiplier handing (No industry has this bit set by default.).
|-
| IND_FLAG_RANDOM_BITS_IN_PRODUCTION_CALLBACK
| The production callback needs random bits in var. 10 (No industry has this bit set by default.)
|-
| IND_FLAG_DO_NOT_FORCE_INSTANCE_AT_MAP_GENERATION
| Do not force one instance of this type to appear during initial map generation (No industry has this bit set by default.)
|-
| IND_FLAG_ALLOW_CLOSING_LAST_INSTANCE
| Allow closing down the last instance of this type (No industry has this bit set by default.)
|}

==Industry tile properties==

{| class="t"
! property
! value range
! comment
|-
| substitute
|
[[NML:Default industry tiles|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
|
[[NML:Default industry tiles|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.
| 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: <code style="color:darkgreen"><nowiki>accepted_cargos: [[COAL, 8], [IORE, 8]];</nowiki></code> Example: for a tile that doesn't any cargos at all you'd use: <code style="color:darkgreen">accepted_cargos: [];</code>
|-
| land_shape_flags
|
bitmask([[#Land shape flags|Land shape flags]])
|
|-
| callback_flags
| bitmask(INDTILE_CBF_XXX, INDTILE_CBF_YYY)
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| animation_info
| Array [ANIMATION_XXX, frame-count]
| XXX = [LOOPING <nowiki>|</nowiki> NON_LOOPING], 1..253 frames
|-
| animation_speed
| 0..16
|
Speed of animation, see [[NML:Animation speed|animation speed table]] for the meaning of the values.
|-
| animation_triggers
| bitmask(ANIM_TRIGGER_INDTILE_XXX, ... )
|
Bitmask of triggers that will trigger the <code style="color:darkgreen">anim_control</code> callback, see the [[#Animation triggers|table]] below.
|-
| special_flags
| bitmask(INDTILE_FLAG_XXX)
| XXX is a special flag description. Currently there's only one flag defined: set INDTILE_FLAG_RANDOM_ANIMATION if the decision in anim_control callback needs random bits via extra_callback_info1
|}

===Land shape flags===

{| class="t"
! 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 0x2F.
|}

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

{| class="t"
! name
! value range
! comment
|-
| nearby_tile_slope
| SLOPE_XXX
|
See [[NML:List of tile slopes|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 <nowiki>|</nowiki> SEA <nowiki>|</nowiki> CANAL <nowiki>|</nowiki> RIVER] Note that tiles for which <code style="color:darkgreen">nearby_tile_is_water</code> 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
|
[[NML:List of tile classes|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 that is part of this GRF, the tile id is 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 GRF.
|}

==Industry variables==

{| class="t"
! name
! value range
! comment
|-
| production_level
| 0, or 4 .. 128
| Current production level of the industry. Usually in range 4 .. 128, default starting level is 16. A level of 0 indicates imminent closure.
|-
| waiting_cargo_1
| 0..65535
| If any of the production callbacks is enabled, this variable will contain the amount of the first cargo type awaiting to be processed.
|-
| waiting_cargo_2
| 0..65535
| If any of the production callbacks is enabled, this variable will contain the amount of the second cargo type awaiting to be processed.
|-
| waiting_cargo_3
| 0..65535
| If any of the production callbacks is enabled, this variable will contain the amount of the third cargo type awaiting to be processed.
|-
| produced_cargo_waiting_1
| 0..65535
| The amount of produced 'output cargo type 1' that this waiting to be transported.
|-
| produced_cargo_waiting_2
| 0..65535
| The amount of produced 'output cargo type 2' that this waiting to be transported.
|-
| produced_this_month_1
| 0..65535
| The amount of 'output cargo type 1' that was produced this month.
|-
| produced_this_month_2
| 0..65535
| The amount of 'output cargo type 2' that was produced this month.
|-
| produced_last_month_1
| 0..65535
| The amount of 'output cargo type 1' that was produced last month.
|-
| produced_last_month_2
| 0..65535
| The amount of 'output cargo type 2' that was produced last month.
|-
| transported_this_month_1
| 0..65535
| The amount of 'output cargo type 1' that was transported this month.
|-
| transported_this_month_2
| 0..65535
| The amount of 'output cargo type 2' that was transported this month.
|-
| transported_last_month_1
| 0..65535
| The amount of 'output cargo type 1' that was produced last month.
|-
| transported_last_month_2
| 0..65535
| The amount of 'output cargo type 2' that was produced last month.
|-
| transported_last_month_pct_1
| 0..100
| Percentage of produced 'output cargo type 1' that was transported last month.
|-
| transported_last_month_pct_2
| 0..100
| Percentage of produced 'output cargo type 2' that was transported last month.
|-
| production_rate_1
| 0..255
| {{nml|0.3}} Amount of 'output cargo type 1' that is produced every 256 ticks. Initial value from the <code>prod_multiplier</code>-property, but it will change accordingly when the production level changes.
|-
| production_rate_2
| 0..255
| {{nml|0.3}} Amount of 'output cargo type 2' that is produced every 256 ticks. Initial value from the <code>prod_multiplier</code>-property, but it will change accordingly when the production level changes.
|-
| water_distance
| Distance to the tile
| If the industry is built on water, this variable gives the distance of the closest dry land tile, otherwise it gives the distance of the closest water tile.
|-
| layout_num
| 1..255
| Number of the layout being used by the industry.
|-
| founder
| 0..16
| Company number of the industry founder. It will be FOUNDER_GAME (=16) if the industry was generated randomly. TTDPatch only supports up to 8 companies (0..7).
|-
| founder_type
| PLAYERTYPE_XX
| PLAYERTYPE_HUMAN, PLAYERTYPE_AI, PLAYERTYPE_HUMAN_IN_AI (human managing AI company) or PLAYERTYPE_AI_IN_HUMAN (AI managing human company). OpenTTD only uses PLAYERTYPE_HUMAN and PLAYERTYPE_AI. If you cheat yourself to be part of an AI company OpenTTD will still report PLAYERTYPE_AI for the company with yourself and the AI and it'll report PLAYERTYPE_HUMAN for the now uncontrolled company.
|-
| founder_colour1
| COLOUR_XXX
|
Index of founding company's first colour. 0 if not founded by a company. Refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for possible values.
|-
| founder_colour2
| COLOUR_XXX
|
Index of founding company's second colour. It's the same as company_colour1, if no second company colour is chosen. 0 if not founded by a company. Refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for possible values.
|-
| colour
| COLOUR_XXX
|
Random colour for this industry. Refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for possible values.
|-
| build_date
| 0..1826212865
| Date of the industry foundation in days since year 0.
|-
| build_type
| BUILDTYPE_XX
| BUILDTYPE_UNKNOWN (if created in an old version or with newindustries disabled), BUILDTYPE_GAMEPLAY (if founded or created by the in-game random industry generator), BUILDTYPE_GENERATION (if created during random map generation) or BUILDTYPE_EDITOR (if created with the scenario editor).
|-
| counter
| 0..65535
| Decremented every tick, used to time primary industry production in TTD.
|-
| last_accept_date
| date(year, month, day)
| Date when cargo was accepted for the last time. Not valid before 1920 and after 2090.
|-
| random_bits
| 0 ... 65535
| Random data that can be used to randomize certain descisions. (see [[NML:Random_switch|Random switch]]) (NML r1666)
|}

 Variables that require some parameters.

{| class="t"
! name
! arguments
! comment
|-
| industry_count
| industry_type, grfid = -1
|
The value of this variable is the number of industries of a given type that are currently on the map. industry_type is either the ID of an industry. GRFid is the grf in which the industry was defined. The default value is -1, which means current newgrf. A grfid of 0 lets you check the number of default industries of a given type. Use the [[NML:Builtin functions|builtin function]] <code style="color:darkgreen">str2number()</code> to convert a grfid to its numeric representation. ''Warning: using this variable trashes the contents of temporary storage register 0x100''
|-
| industry_distance
| industry_type, grfid = -1
| The value of this variable is the manhattan distance the closest instance of the given industry or 0xFFFF if not applicable. See industry_count for a description of the parameters. ''Warning: using this variable trashes the contents of temporary storage register 0x100.''
|-
| industry_layout_count / industry_layout_distance
| industry_type, layout, grfid = -1.
| See industry_count / industry_distance for description of industry_type, grfid and return value. The results are filtered to industries that have the given layout number. ''Warning: using this variable trashes the contents of temporary storage registers 0x100 and 0x101.''
|-
| industry_town_count
| industry_type, grfid = -1.
| See industry_count / industry_distance for description of industry_type, grfid and return value. The results are filtered to industries that have the same town than the current industry. ''Warning: using this variable trashes the contents of temporary storage registers 0x100 and 0x101.''
|-
| town_manhattan_dist
| x, y
| Parameters indicate a signed offset relative to the northern tile. Returns the Manhattan distance (dx + dy) from the selected tile to the closest town
|-
| town_euclidean_dist
| x, y
| Parameters indicate a signed offset relative to the northern tile. Returns the squared Eucleidean distance (dx^2 + dy^2) from the selected tile to the closest town.
|-
| town_zone
| x, y
|
Parameters indicate a signed offset relative to the northern tile. Returns the [[NML:List of town zones|town zone]] that the selected tile is in.
|-
| nearby_tile_random_bits
| x, y
| Parameters indicate an unsigned offset relative to the northern tile. Returns the random bits of the selected industry tile, or 0 if it is not an industry tile that's part of this industry.
|}

==Industry tile variables==

{| class="t"
! 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
|
[[NML:List of town zones|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 [[NML:Builtin functions|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|common variables]] described above. Additionally, they have access to the following:

{| class="t"
! 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 callbacks==

{| class="t"
! callback
! return value
! comment
|-
| default
| varies
| Any unhandled callbacks. Generally this doesn't need to be used, except for old-style callbacks.
|-
| produce_cargo_arrival
| Produce-block
| Called to produce cargo when it arrives.
|-
| produce_256_ticks
| Produce-block
| Called to produce cargo every 256 ticks.
|-
| availability
| CB_RESULT_IND_ALLOW or CB_RESULT_IND_DISALLOW
|
{{nml|0.2}} Only available in NML 0.2 or earlier. Called when the game needs to know if the industry type is available. It is limited to the type as a whole, so you can't access industry-specific variables. <code style="color:darkgreen">extra_callback_info2</code> contains the [[#Industry creation types|creation type]].
|-
| construction_probability
| CB_RESULT_IND_NO_CONSTRUCTION, CB_RESULT_IND_PROBABILITY_FROM_PROPERTY or a relative probability 0..255
|
{{nml|0.3}}. Called when the game needs to know if the industry type is available. It is limited to the type as a whole, so you can't access industry-specific variables. <code style="color:darkgreen">extra_callback_info2</code> contains the [[#Industry creation types|creation type]]. If you return CB_RESULT_IND_NO_CONSTRUCTION or 0 the industry won't be build. If you return CB_RESULT_IND_PROBABILITY_FROM_PROPERTY it'll be build according to the relative probability as defined in the <code style="color:darkgreen">prob_random</code> or <code style="color:darkgreen">prob_in_game</code> properties, otherwise it'll use the value as returned as relative probability.
|-
| location_check
|
See the [[#Location check results|table]] below.
|
Called to check if a location is suitable. <code style="color:darkgreen">extra_callback_info2</code> contains the [[#Industry creation types|creation type]]. Since the industry isn't built yet, industry variables aren't available. If this callback is not implemented or fails, constructing the industry will be allowed. Construction might also be prevented via the <code style="color:darkgreen">tile_check</code> industry tile callback, though.
|-
| monthly_prod_change
|
See [[#Production change callback results|below]]
| Called each month to (possibly) change the industry production. <code style="color:darkgreen">extra_callback_info2</code> contains random bits.
|-
| random_prod_change
|
See [[#Production change callback results|below]]
| Works exactly the same as <code style="color:darkgreen">monthly_prod_change</code>, except that it's only called when TTD selects this industry for a random production change.
|-
| build_prod_change
| Value in range 4-128
| Called when an industry is constructed. Return value is production level (default 16). Can also be used to initialise permanent storage when an industry is constructed. Requires OpenTTD > r24186 and nml > 1886.
|-
| cargo_subtype_display
| String or CB_RESULT_NO_TEXT
| This callback allows displaying some text after a cargo name. Returning CB_RESULT_NO_TEXT displays nothing. The lowest byte of <code style="color:darkgreen">extra_callback_info2</code> contains 0 .. 2 to get texts for the first .. third accepted cargo type, and 3 .. 4 for the first ... second produced cargo type. The second byte contains 0 when getting a string for the buy menu (no industry variables available!), 1 when for the industry window and 2 for the industry directory window.
|-
| extra_text_industry
| String
| Show extra text in the industry window.
|-
| extra_text_fund
| String
| Show extra text in the fund window. Since the industry isn't built, no industry variables are available.
|-
| control_special
| 0 or 1
| Called to control various effects from the <code style="color:darkgreen">spec_flags</code> property. Currently only works for the first two (plant fields / cut trees). Return 1 to execute the action or 0 to not do so. The relevant flag is given in <code style="color:darkgreen">extra_callback_info2</code>. The default (if the flag is enabled, of course) is to plant fields with 1/8th chance every 256 ticks, and to cut trees every 512 ticks. Random bits are supplied in <code style="color:darkgreen">extra_callback_info1</code>.
|-
| stop_accept_cargo
| 0 or 1
| With this callback, you can temporarily refuse accepting a certain cargo, for example because the stockpile is full. Return 1 to accept or 0 to refuse. Make sure to synchronize this callback with the <code style="color:darkgreen">cargo_amount_accept</code> callback for industry tiles. <code style="color:darkgreen">extra_callback_info2</code> contains the cargo type to accept or not.
|-
| colour
| COLOUR_XXX
| Called after constructing the industry. The <code style="color:darkgreen">colour</code> variable is set to a random value at this point, you can use this callback to change this.
|-
| cargo_input
| Cargo type, or 0xFF
| Decide the input cargo types. Called repeatedly until 0xFF is returned, although currently not more than three times. Do not rely on this limitation, though. <code style="color:darkgreen">extra_callback_info1</code> starts at 0 and is incremented for every iteration. Return a cargo type (from the table) or 0xFF to stop.
|-
| cargo_output
| Cargo type, or 0xFF
| Same as <code style="color:darkgreen">cargo_input</code> above, except that it is applied to the output cargo types and currently not called more than twice.
|}

===Location check results===

The following values can be used as return values for the <code style="color:darkgreen">location_check</code> callback for industries
and the <code style="color:darkgreen">tile_check</code> callback for industry tiles and objects.

{| class="t"
! 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.
|}

===Production change callback results===

{| class="t"
! value
! meaning
|-
| CB_RESULT_IND_PROD_NO_CHANGE
| Do not change industry production
|-
| CB_RESULT_IND_PROD_HALF
| Half industry production. If production goes below a quarter of default, the industry closes.
|-
| CB_RESULT_IND_PROD_DOUBLE
| Double production if it's not 8x default yet.
|-
| CB_RESULT_IND_PROD_CLOSE
| Announce closure and remove the industry next month.
|-
| CB_RESULT_IND_PROD_RANDOM
| Do a random production change, as if the industry is a primary one.
|-
| CB_RESULT_IND_PROD_DIVIDE_BY_4
| Divide production by 4
|-
| CB_RESULT_IND_PROD_DIVIDE_BY_8
| Divide production by 8
|-
| CB_RESULT_IND_PROD_DIVIDE_BY_16
| Divide production by 16
|-
| CB_RESULT_IND_PROD_DIVIDE_BY_32
| Divide production by 32
|-
| CB_RESULT_IND_PROD_MULTIPLY_BY_4
| Multiply production by 4
|-
| CB_RESULT_IND_PROD_MULTIPLY_BY_8
| Multiply production by 8
|-
| CB_RESULT_IND_PROD_MULTIPLY_BY_16
| Multiply production by 16
|-
| CB_RESULT_IND_PROD_MULTIPLY_BY_32
| Multiply production by 32
|-
| CB_RESULT_IND_PROD_DECREMENT_BY_1
| Decrement production by 1
|-
| CB_RESULT_IND_PROD_INCREMENT_BY_1
| Increment production by 1
|-
| CB_RESULT_IND_PROD_SET_BY_0x100
| Set the production level to the value in bits 16 .. 23 of register 0x100.
|}

Setting bit 7 of the result disables the associated news message. Setting bit 8 replaces the news message with a custom message, read from register 0x100 bits 0 .. 15.

===Industry creation types===

{| class="t"
! value
! meaning
|-
| IND_CREATION_GENERATION
| Industry is created during map generation, or when building 'many random industries' in the scenario editor.
|-
| IND_CREATION_RANDOM
| Industry is randomly generated during gameplay
|-
| IND_CREATION_FUND
| Industry is funded by the player (in game or scenario editor)
|-
| IND_CREATION_PROSPECT
| Industry is prospected by the player
|}

==Industry tile callbacks==

{| class="t"
! callback
! return value
! comment
|-
| default
| Sprite layout
| Graphics for the industry tile
|-
| random_trigger
| N/A
|
See [[NML:Random switch|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. <code style="color:darkgreen">extra_callback_info1</code> contains random bits, if enabled in the <code style="color:darkgreen">special_flags</code> property. Returning a sound effect in the high byte will cause that sound effect to be played.
|-
| 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 <nowiki>|</nowiki> STOP_ANIMATION <nowiki>|</nowiki> DO_NOTHING] to respectively start the animation in its current frame, stop the animation or do nothing. <code style="color:darkgreen">extra_callback_info1</code> contains random bits, if enabled in the <code style="color:darkgreen">special_flags</code> property. Returning a sound effect in the high byte will cause that sound effect to be played. <code style="color:darkgreen">extra_callback_info2</code> contains the reason to trigger the animation, see the [[#Animation triggers|table]] below. Note that you need to enable the wanted triggers in the <code style="color:darkgreen">animation_triggers</code> property.
|-
| 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 <code style="color:darkgreen">accepted_cargos</code> 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 <code style="color:darkgreen">accepted_cargos</code> are used instead. Cargo types are from the <code style="color:darkgreen">cargo_type_accept</code> callback, or the <code style="color:darkgreen">accepted_cargos</code> 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 results|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. <code style="color:darkgreen">extra_callback_info2</code> contains the industry layout number in the lowest (first) byte and the [[#Industry creation types|creation type]] in the second byte. If this callback is not implemented or fails, the <code style="color:darkgreen">land_shape_flags</code> 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.
|}

===Animation triggers===

{| class="t"
! 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)
|}

NML:Industries

2012-09-11T19:49:18Z

Hirundo: /* Industry variables */ Add production_rate_1/2

{{NMLNavPropVarCB}}

This page contains information on both industry and industry tile properties, variables and callbacks.

== Industry (tile) ID allocation ==
Industry and 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 [[IndustryDefaultProps|default industry]] or [[IndustryTileDefaultProps|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 properties==

Industry properties. Default industry type numbers can be found at [[NML:Default industries|default industries]].

{| class="t"
! property
! value range
! comment
|-
| substitute
| industry type
| Number of the original industry type that replaces this one, should it not be available for some reason (e.g. missing NewGRF). This ''must'' be the first property to be set, before any other properties or graphics. All properties of the old type are copied to your new industry.
|-
| override
| industry type
| Number of the original industry type overridden. This will cause other grfs / industries to consider your industry type the same as the old type. Only set this property if your type is (more or less) the same as the old type.
|-
| layouts
| Array of tilelayouts
|
See [[NML:Tilelayout|Tilelayout]] syntax.
|-
| life_type
| One of IND_LIFE_TYPE_XXX, XXX = BLACK_HOLE <nowiki>|</nowiki> EXTRACTIVE <nowiki>|</nowiki> ORGANIC <nowiki>|</nowiki> PROCESSING
| The generic type of industry. This determines the production changes that occur by default (when not using the callback). Examples are respectively power plants, coal mines, forests en steel mills.
|-
| closure_msg
| string
|
Message displayed when the industry announces closure. Use a custom string or one of the [[NML:Default TTD strings|default TTD strings]].
|-
| prod_increase_msg
| string
|
Message displayed when industry increases production. Use a custom string or one of the [[NML:Default TTD strings|default TTD strings]].
|-
| prod_decrease_msg
| string
|
Message displayed when industry decreases production. Use a custom string or one of the [[NML:Default TTD strings|default TTD strings]].
|-
| fund_cost_multiplier
| 0..255
| Fund cost multiplier. Note that in OpenTTD the unmodified base cost is 8x higher for building (not prospecting) raw (=extractive / organic, see life_type) industries.
|-
| prod_cargo_types
| array of up to 2 ints
| Types of cargo produced. Use the cargotype(<label>) built-in function to specify a label from the cargotable.
|-
| accept_cargo_types
| array of up to 3 ints
| Types of cargo accepted. Use the cargotype(<label>) built-in function to specify a label from the cargotable
|-
| prod_multiplier
| array of up to 2 ints (0..255)
| Amount of each output cargo to produce every 256 ticks (8 or 9 times a month)
|-
| min_cargo_distr
| 0..255
| Minimal amount of cargo before transporting to stations.
|-
| random_sound_effects
| array of ints
| Sound effect numbers that are played some times.
|-
| conflicting_ind_types
| array of up to 3x industry_type(IND_TYPE_OLD <nowiki>|</nowiki> IND_TYPE_NEW, id)
|
Three industry types that should not be nearby. Use the [[NML:Builtin functions|builtin function]] <code style="color:darkgreen">industry_type(..)</code> to define either an old industry (using the global ID) or a new industry from your grf (using the grf-local ID).
|-
| prob_random
| 0..255
| Probability of occurring while generating initial industries.
|-
| prob_in_game
| 0..255
| Probability of occurring while creating industries during the game.
|-
| map_colour
| 0..255
|
Colour index from the [[NML:Graphic files|DOS palette]] to use on the minimap for this industry.
|-
| spec_flags
| bitmask(flags)
|
for flag values see [[#industry_special_flags|Industry special flags]]
|-
| new_ind_msg
| string
| Message displayed when industry gets built during game play.
|-
| input_multiplier_1
| array of up to 2 floats (0..255)
| Output cargo multiplication factors for getting a unit of the first accepted cargo.
|-
| input_multiplier_2
| array of up to 2 floats (0..255)
| Output cargo multiplication factors for getting a unit of the second accepted cargo.
|-
| input_multiplier_3
| array of up to 2 floats (0..255)
| Output cargo multiplication factors for getting a unit of the third accepted cargo.
|-
| name
| string
|
Name of the industry, use a custom string or one of the [[NML:Default TTD strings|default TTD strings]].
|-
| prospect_chance
| 0 .. 1 (float)
| Chance of successful prospecting.
|-
| callback_flags
| bitmask(flags)
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| remove_cost_multiplier
| int
| Cost multiplier for removing the industry (currently only possible with magic bulldozer).
|-
| nearby_station_name
| string
| Default additional name for a nearby station
|}

===Industry special flags===

{| class="t"
! flag
! meaning
|-
| IND_FLAG_PLANT_FIELDS_PERIODICALLY
| The industry periodically plants fields around itself (temperate and arctic farms)
|-
| IND_FLAG_CUT_TREES
| The industry cuts trees around itself and produces its first output cargo from them (lumber mill)
|-
| IND_FLAG_BUILT_ON_WATER
| The industry is built on water (oil rig)
|-
| IND_FLAG_ONLY_IN_LARGE_TOWNS
| The industry can only be built in towns (i.e. it has to replace houses) with population larger than 1200 (temperate bank)
|-
| IND_FLAG_ONLY_IN_TOWNS
| The industry can only be built in towns (i.e. it has to replace houses) (arctic and tropic banks, water tower)
|-
| IND_FLAG_BUILT_NEAR_TOWN
| The industry is always built near towns (i.e. near town sign; additionally the industry is allowed to replace houses) (toy shop)
|-
| IND_FLAG_PLANT_FIELDS_WHEN_BUILT
| Fields are planted around the industry when it's built (all farms)
|-
| IND_FLAG_NO_PRODUCTION_INCREASE
| The industry cannot increase its production on the temperate climate (oil wells)
|-
| IND_FLAG_BUILT_ONLY_BEFORE_1950
| The industry is built only before 1950 (oil wells)
|-
| IND_FLAG_BUILT_ONLY_AFTER_1960
| The industry is built only after 1960 (oil rig)
|-
| IND_FLAG_AI_CREATES_AIR_AND_SHIP_ROUTES
| AI players will attempt to establish air and ship routes going to this industry (oil rig)
|-
| IND_FLAG_MILITARY_AIRPLANE_CAN_EXPLODE
| The industry can be exploded by a military airplane (oil refinery)
|-
| IND_FLAG_MILITARY_HELICOPTER_CAN_EXPLODE
| The industry can be exploded by a military helicopter (factory)
|-
| IND_FLAG_CAN_CAUSE_SUBSIDENCE
| The industry can cause a subsidence (coal mine)
|-
| IND_FLAG_AUTOMATIC_PRODUCTION_MULTIPLIER
| Automatic production multiplier handing (No industry has this bit set by default.).
|-
| IND_FLAG_RANDOM_BITS_IN_PRODUCTION_CALLBACK
| The production callback needs random bits in var. 10 (No industry has this bit set by default.)
|-
| IND_FLAG_DO_NOT_FORCE_INSTANCE_AT_MAP_GENERATION
| Do not force one instance of this type to appear during initial map generation (No industry has this bit set by default.)
|-
| IND_FLAG_ALLOW_CLOSING_LAST_INSTANCE
| Allow closing down the last instance of this type (No industry has this bit set by default.)
|}

==Industry tile properties==

{| class="t"
! property
! value range
! comment
|-
| substitute
|
[[NML:Default industry tiles|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
|
[[NML:Default industry tiles|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.
| 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: <code style="color:darkgreen"><nowiki>accepted_cargos: [[COAL, 8], [IORE, 8]];</nowiki></code> Example: for a tile that doesn't any cargos at all you'd use: <code style="color:darkgreen">accepted_cargos: [];</code>
|-
| land_shape_flags
|
bitmask([[#Land shape flags|Land shape flags]])
|
|-
| callback_flags
| bitmask(INDTILE_CBF_XXX, INDTILE_CBF_YYY)
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| animation_info
| Array [ANIMATION_XXX, frame-count]
| XXX = [LOOPING <nowiki>|</nowiki> NON_LOOPING], 1..253 frames
|-
| animation_speed
| 0..16
|
Speed of animation, see [[NML:Animation speed|animation speed table]] for the meaning of the values.
|-
| animation_triggers
| bitmask(ANIM_TRIGGER_INDTILE_XXX, ... )
|
Bitmask of triggers that will trigger the <code style="color:darkgreen">anim_control</code> callback, see the [[#Animation triggers|table]] below.
|-
| special_flags
| bitmask(INDTILE_FLAG_XXX)
| XXX is a special flag description. Currently there's only one flag defined: set INDTILE_FLAG_RANDOM_ANIMATION if the decision in anim_control callback needs random bits via extra_callback_info1
|}

===Land shape flags===

{| class="t"
! 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 0x2F.
|}

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

{| class="t"
! name
! value range
! comment
|-
| nearby_tile_slope
| SLOPE_XXX
|
See [[NML:List of tile slopes|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 <nowiki>|</nowiki> SEA <nowiki>|</nowiki> CANAL <nowiki>|</nowiki> RIVER] Note that tiles for which <code style="color:darkgreen">nearby_tile_is_water</code> 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
|
[[NML:List of tile classes|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 that is part of this GRF, the tile id is 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 GRF.
|}

==Industry variables==

{| class="t"
! name
! value range
! comment
|-
| production_level
| 0, or 4 .. 128
| Current production level of the industry. Usually in range 4 .. 128, default starting level is 16. A level of 0 indicates imminent closure.
|-
| waiting_cargo_1
| 0..65535
| If any of the production callbacks is enabled, this variable will contain the amount of the first cargo type awaiting to be processed.
|-
| waiting_cargo_2
| 0..65535
| If any of the production callbacks is enabled, this variable will contain the amount of the second cargo type awaiting to be processed.
|-
| waiting_cargo_3
| 0..65535
| If any of the production callbacks is enabled, this variable will contain the amount of the third cargo type awaiting to be processed.
|-
| produced_cargo_waiting_1
| 0..65535
| The amount of produced 'output cargo type 1' that this waiting to be transported.
|-
| produced_cargo_waiting_2
| 0..65535
| The amount of produced 'output cargo type 2' that this waiting to be transported.
|-
| produced_this_month_1
| 0..65535
| The amount of 'output cargo type 1' that was produced this month.
|-
| produced_this_month_2
| 0..65535
| The amount of 'output cargo type 2' that was produced this month.
|-
| produced_last_month_1
| 0..65535
| The amount of 'output cargo type 1' that was produced last month.
|-
| produced_last_month_2
| 0..65535
| The amount of 'output cargo type 2' that was produced last month.
|-
| transported_this_month_1
| 0..65535
| The amount of 'output cargo type 1' that was transported this month.
|-
| transported_this_month_2
| 0..65535
| The amount of 'output cargo type 2' that was transported this month.
|-
| transported_last_month_1
| 0..65535
| The amount of 'output cargo type 1' that was produced last month.
|-
| transported_last_month_2
| 0..65535
| The amount of 'output cargo type 2' that was produced last month.
|-
| transported_last_month_pct_1
| 0..100
| Percentage of produced 'output cargo type 1' that was transported last month.
|-
| transported_last_month_pct_2
| 0..100
| Percentage of produced 'output cargo type 2' that was transported last month.
|-
| production_rate_1
| 0..255
| Amount of 'output cargo type 1' that is produced every 256 ticks. Initial value from the <code>prod_multiplier</code>-property, but it will change accordingly when the production level changes.
|-
| production_rate_2
| 0..255
| Amount of 'output cargo type 2' that is produced every 256 ticks. Initial value from the <code>prod_multiplier</code>-property, but it will change accordingly when the production level changes.
|-
| water_distance
| Distance to the tile
| If the industry is built on water, this variable gives the distance of the closest dry land tile, otherwise it gives the distance of the closest water tile.
|-
| layout_num
| 1..255
| Number of the layout being used by the industry.
|-
| founder
| 0..16
| Company number of the industry founder. It will be FOUNDER_GAME (=16) if the industry was generated randomly. TTDPatch only supports up to 8 companies (0..7).
|-
| founder_type
| PLAYERTYPE_XX
| PLAYERTYPE_HUMAN, PLAYERTYPE_AI, PLAYERTYPE_HUMAN_IN_AI (human managing AI company) or PLAYERTYPE_AI_IN_HUMAN (AI managing human company). OpenTTD only uses PLAYERTYPE_HUMAN and PLAYERTYPE_AI. If you cheat yourself to be part of an AI company OpenTTD will still report PLAYERTYPE_AI for the company with yourself and the AI and it'll report PLAYERTYPE_HUMAN for the now uncontrolled company.
|-
| founder_colour1
| COLOUR_XXX
|
Index of founding company's first colour. 0 if not founded by a company. Refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for possible values.
|-
| founder_colour2
| COLOUR_XXX
|
Index of founding company's second colour. It's the same as company_colour1, if no second company colour is chosen. 0 if not founded by a company. Refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for possible values.
|-
| colour
| COLOUR_XXX
|
Random colour for this industry. Refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for possible values.
|-
| build_date
| 0..1826212865
| Date of the industry foundation in days since year 0.
|-
| build_type
| BUILDTYPE_XX
| BUILDTYPE_UNKNOWN (if created in an old version or with newindustries disabled), BUILDTYPE_GAMEPLAY (if founded or created by the in-game random industry generator), BUILDTYPE_GENERATION (if created during random map generation) or BUILDTYPE_EDITOR (if created with the scenario editor).
|-
| counter
| 0..65535
| Decremented every tick, used to time primary industry production in TTD.
|-
| last_accept_date
| date(year, month, day)
| Date when cargo was accepted for the last time. Not valid before 1920 and after 2090.
|-
| random_bits
| 0 ... 65535
| Random data that can be used to randomize certain descisions. (see [[NML:Random_switch|Random switch]]) (NML r1666)
|}

 Variables that require some parameters.

{| class="t"
! name
! arguments
! comment
|-
| industry_count
| industry_type, grfid = -1
|
The value of this variable is the number of industries of a given type that are currently on the map. industry_type is either the ID of an industry. GRFid is the grf in which the industry was defined. The default value is -1, which means current newgrf. A grfid of 0 lets you check the number of default industries of a given type. Use the [[NML:Builtin functions|builtin function]] <code style="color:darkgreen">str2number()</code> to convert a grfid to its numeric representation. ''Warning: using this variable trashes the contents of temporary storage register 0x100''
|-
| industry_distance
| industry_type, grfid = -1
| The value of this variable is the manhattan distance the closest instance of the given industry or 0xFFFF if not applicable. See industry_count for a description of the parameters. ''Warning: using this variable trashes the contents of temporary storage register 0x100.''
|-
| industry_layout_count / industry_layout_distance
| industry_type, layout, grfid = -1.
| See industry_count / industry_distance for description of industry_type, grfid and return value. The results are filtered to industries that have the given layout number. ''Warning: using this variable trashes the contents of temporary storage registers 0x100 and 0x101.''
|-
| industry_town_count
| industry_type, grfid = -1.
| See industry_count / industry_distance for description of industry_type, grfid and return value. The results are filtered to industries that have the same town than the current industry. ''Warning: using this variable trashes the contents of temporary storage registers 0x100 and 0x101.''
|-
| town_manhattan_dist
| x, y
| Parameters indicate a signed offset relative to the northern tile. Returns the Manhattan distance (dx + dy) from the selected tile to the closest town
|-
| town_euclidean_dist
| x, y
| Parameters indicate a signed offset relative to the northern tile. Returns the squared Eucleidean distance (dx^2 + dy^2) from the selected tile to the closest town.
|-
| town_zone
| x, y
|
Parameters indicate a signed offset relative to the northern tile. Returns the [[NML:List of town zones|town zone]] that the selected tile is in.
|-
| nearby_tile_random_bits
| x, y
| Parameters indicate an unsigned offset relative to the northern tile. Returns the random bits of the selected industry tile, or 0 if it is not an industry tile that's part of this industry.
|}

==Industry tile variables==

{| class="t"
! 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
|
[[NML:List of town zones|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 [[NML:Builtin functions|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|common variables]] described above. Additionally, they have access to the following:

{| class="t"
! 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 callbacks==

{| class="t"
! callback
! return value
! comment
|-
| default
| varies
| Any unhandled callbacks. Generally this doesn't need to be used, except for old-style callbacks.
|-
| produce_cargo_arrival
| Produce-block
| Called to produce cargo when it arrives.
|-
| produce_256_ticks
| Produce-block
| Called to produce cargo every 256 ticks.
|-
| availability
| CB_RESULT_IND_ALLOW or CB_RESULT_IND_DISALLOW
|
{{nml|0.2}} Only available in NML 0.2 or earlier. Called when the game needs to know if the industry type is available. It is limited to the type as a whole, so you can't access industry-specific variables. <code style="color:darkgreen">extra_callback_info2</code> contains the [[#Industry creation types|creation type]].
|-
| construction_probability
| CB_RESULT_IND_NO_CONSTRUCTION, CB_RESULT_IND_PROBABILITY_FROM_PROPERTY or a relative probability 0..255
|
{{nml|0.3}}. Called when the game needs to know if the industry type is available. It is limited to the type as a whole, so you can't access industry-specific variables. <code style="color:darkgreen">extra_callback_info2</code> contains the [[#Industry creation types|creation type]]. If you return CB_RESULT_IND_NO_CONSTRUCTION or 0 the industry won't be build. If you return CB_RESULT_IND_PROBABILITY_FROM_PROPERTY it'll be build according to the relative probability as defined in the <code style="color:darkgreen">prob_random</code> or <code style="color:darkgreen">prob_in_game</code> properties, otherwise it'll use the value as returned as relative probability.
|-
| location_check
|
See the [[#Location check results|table]] below.
|
Called to check if a location is suitable. <code style="color:darkgreen">extra_callback_info2</code> contains the [[#Industry creation types|creation type]]. Since the industry isn't built yet, industry variables aren't available. If this callback is not implemented or fails, constructing the industry will be allowed. Construction might also be prevented via the <code style="color:darkgreen">tile_check</code> industry tile callback, though.
|-
| monthly_prod_change
|
See [[#Production change callback results|below]]
| Called each month to (possibly) change the industry production. <code style="color:darkgreen">extra_callback_info2</code> contains random bits.
|-
| random_prod_change
|
See [[#Production change callback results|below]]
| Works exactly the same as <code style="color:darkgreen">monthly_prod_change</code>, except that it's only called when TTD selects this industry for a random production change.
|-
| build_prod_change
| Value in range 4-128
| Called when an industry is constructed. Return value is production level (default 16). Can also be used to initialise permanent storage when an industry is constructed. Requires OpenTTD > r24186 and nml > 1886.
|-
| cargo_subtype_display
| String or CB_RESULT_NO_TEXT
| This callback allows displaying some text after a cargo name. Returning CB_RESULT_NO_TEXT displays nothing. The lowest byte of <code style="color:darkgreen">extra_callback_info2</code> contains 0 .. 2 to get texts for the first .. third accepted cargo type, and 3 .. 4 for the first ... second produced cargo type. The second byte contains 0 when getting a string for the buy menu (no industry variables available!), 1 when for the industry window and 2 for the industry directory window.
|-
| extra_text_industry
| String
| Show extra text in the industry window.
|-
| extra_text_fund
| String
| Show extra text in the fund window. Since the industry isn't built, no industry variables are available.
|-
| control_special
| 0 or 1
| Called to control various effects from the <code style="color:darkgreen">spec_flags</code> property. Currently only works for the first two (plant fields / cut trees). Return 1 to execute the action or 0 to not do so. The relevant flag is given in <code style="color:darkgreen">extra_callback_info2</code>. The default (if the flag is enabled, of course) is to plant fields with 1/8th chance every 256 ticks, and to cut trees every 512 ticks. Random bits are supplied in <code style="color:darkgreen">extra_callback_info1</code>.
|-
| stop_accept_cargo
| 0 or 1
| With this callback, you can temporarily refuse accepting a certain cargo, for example because the stockpile is full. Return 1 to accept or 0 to refuse. Make sure to synchronize this callback with the <code style="color:darkgreen">cargo_amount_accept</code> callback for industry tiles. <code style="color:darkgreen">extra_callback_info2</code> contains the cargo type to accept or not.
|-
| colour
| COLOUR_XXX
| Called after constructing the industry. The <code style="color:darkgreen">colour</code> variable is set to a random value at this point, you can use this callback to change this.
|-
| cargo_input
| Cargo type, or 0xFF
| Decide the input cargo types. Called repeatedly until 0xFF is returned, although currently not more than three times. Do not rely on this limitation, though. <code style="color:darkgreen">extra_callback_info1</code> starts at 0 and is incremented for every iteration. Return a cargo type (from the table) or 0xFF to stop.
|-
| cargo_output
| Cargo type, or 0xFF
| Same as <code style="color:darkgreen">cargo_input</code> above, except that it is applied to the output cargo types and currently not called more than twice.
|}

===Location check results===

The following values can be used as return values for the <code style="color:darkgreen">location_check</code> callback for industries
and the <code style="color:darkgreen">tile_check</code> callback for industry tiles and objects.

{| class="t"
! 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.
|}

===Production change callback results===

{| class="t"
! value
! meaning
|-
| CB_RESULT_IND_PROD_NO_CHANGE
| Do not change industry production
|-
| CB_RESULT_IND_PROD_HALF
| Half industry production. If production goes below a quarter of default, the industry closes.
|-
| CB_RESULT_IND_PROD_DOUBLE
| Double production if it's not 8x default yet.
|-
| CB_RESULT_IND_PROD_CLOSE
| Announce closure and remove the industry next month.
|-
| CB_RESULT_IND_PROD_RANDOM
| Do a random production change, as if the industry is a primary one.
|-
| CB_RESULT_IND_PROD_DIVIDE_BY_4
| Divide production by 4
|-
| CB_RESULT_IND_PROD_DIVIDE_BY_8
| Divide production by 8
|-
| CB_RESULT_IND_PROD_DIVIDE_BY_16
| Divide production by 16
|-
| CB_RESULT_IND_PROD_DIVIDE_BY_32
| Divide production by 32
|-
| CB_RESULT_IND_PROD_MULTIPLY_BY_4
| Multiply production by 4
|-
| CB_RESULT_IND_PROD_MULTIPLY_BY_8
| Multiply production by 8
|-
| CB_RESULT_IND_PROD_MULTIPLY_BY_16
| Multiply production by 16
|-
| CB_RESULT_IND_PROD_MULTIPLY_BY_32
| Multiply production by 32
|-
| CB_RESULT_IND_PROD_DECREMENT_BY_1
| Decrement production by 1
|-
| CB_RESULT_IND_PROD_INCREMENT_BY_1
| Increment production by 1
|-
| CB_RESULT_IND_PROD_SET_BY_0x100
| Set the production level to the value in bits 16 .. 23 of register 0x100.
|}

Setting bit 7 of the result disables the associated news message. Setting bit 8 replaces the news message with a custom message, read from register 0x100 bits 0 .. 15.

===Industry creation types===

{| class="t"
! value
! meaning
|-
| IND_CREATION_GENERATION
| Industry is created during map generation, or when building 'many random industries' in the scenario editor.
|-
| IND_CREATION_RANDOM
| Industry is randomly generated during gameplay
|-
| IND_CREATION_FUND
| Industry is funded by the player (in game or scenario editor)
|-
| IND_CREATION_PROSPECT
| Industry is prospected by the player
|}

==Industry tile callbacks==

{| class="t"
! callback
! return value
! comment
|-
| default
| Sprite layout
| Graphics for the industry tile
|-
| random_trigger
| N/A
|
See [[NML:Random switch|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. <code style="color:darkgreen">extra_callback_info1</code> contains random bits, if enabled in the <code style="color:darkgreen">special_flags</code> property. Returning a sound effect in the high byte will cause that sound effect to be played.
|-
| 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 <nowiki>|</nowiki> STOP_ANIMATION <nowiki>|</nowiki> DO_NOTHING] to respectively start the animation in its current frame, stop the animation or do nothing. <code style="color:darkgreen">extra_callback_info1</code> contains random bits, if enabled in the <code style="color:darkgreen">special_flags</code> property. Returning a sound effect in the high byte will cause that sound effect to be played. <code style="color:darkgreen">extra_callback_info2</code> contains the reason to trigger the animation, see the [[#Animation triggers|table]] below. Note that you need to enable the wanted triggers in the <code style="color:darkgreen">animation_triggers</code> property.
|-
| 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 <code style="color:darkgreen">accepted_cargos</code> 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 <code style="color:darkgreen">accepted_cargos</code> are used instead. Cargo types are from the <code style="color:darkgreen">cargo_type_accept</code> callback, or the <code style="color:darkgreen">accepted_cargos</code> 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 results|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. <code style="color:darkgreen">extra_callback_info2</code> contains the industry layout number in the lowest (first) byte and the [[#Industry creation types|creation type]] in the second byte. If this callback is not implemented or fails, the <code style="color:darkgreen">land_shape_flags</code> 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.
|}

===Animation triggers===

{| class="t"
! 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)
|}

NML:Houses

2012-09-05T12:34:38Z

Hirundo: /* House properties */ Max probability is 15, not 16

{{NMLNavPropVarCB}}
==House IDs==
House 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 house. The value of this property should be the ID of a [[NML:List_of_default_house_properties|default house type]], which will be used instead of your item if it is not available for whatever reason (for example, missing NewGRF).

Although the majority of all original houses occupy a single tile, it is possible to define a larger house of up to 2x2 tiles. For this, you should set the fourth 'size' parameter in the item-block. Valid values are HOUSE_SIZE_XXX, XXX = <nowiki>[1X1 | 1X2 | 2X1 | 2X2]</nowiki>. This size should match the size of the substitute house type.

===Multi-tile houses===
Internally, due to the way NewGRF houses work, a multi-tile house will occupy more than one item ID. If you assign item ID X to a house, item IDs X+1 (for a 2-tile house) and (X+1) .. (X+3) (for a 4-tile house) will also be used. Normally you don't have to care about this, but there are two exceptions:
* If you manually assign numeric ids to your houses. You are recommended to just set all ids to -1 and let NML figure it out for you.
* When working with several variables that work with house type IDs. Keep in mind that tiles of a multi-tile house may have IDs X .. X + N - 1, with X being the assigned id and N the number of house tiles.

==House properties==

{| class="t"
! property
! value range
! comment
|-
| name
| string
| for example string(STR_NAME_EIFFEL_TOWER)
|-
| substitute
| 0 ... 109
| Number of the default house that replaces this one, if this house 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, except for the church / stadium flags (see below). The old house must have the same size as the new house, see the list of [[NML:List_of_default_house_properties|default house types]] for a list of possible substitute IDs.
|-
| override
| 0 ... 109
| id of the default house which this house replaces. This will cause your house to be placed instead of the default house. This is ignored, if the default house has already been overridden. You can define this property multiple times. Your house and the overridden house must have the same size, see the list of [[NML:List_of_default_house_properties|default house types]].
|-
| building_flags.
| bitmask(HOUSE_FLAG_XXX,...)
|
;HOUSE_FLAG_NOT_SLOPED
:Can only be built on flat terrain. Note that 2x2 buildings will always only be built on flat land, even if this bit isn't set.
;HOUSE_FLAG_ANIMATE
:Enable animation
;HOUSE_FLAG_CHURCH
:House is a church (only 1 will be built per town)
;HOUSE_FLAG_STADIUM
:House is a stadium (only 1 will be built per town)
;HOUSE_FLAG_ONLY_SE
:Can only be built in the scenario editor
;HOUSE_FLAG_PROTECTED
:Will not be removed by the game
;HOUSE_FLAG_SYNC_CALLBACK
:Animation callback <code style="color:darkgreen">anim_control</code> is called at the same time for all tiles.
;HOUSE_FLAG_RANDOM_ANIMATION
:Enable random bits in the <code style="color:darkgreen">anim_next_frame</code>-callback.
|-
| population
| 0 ... 255
| number of inhabitants the building adds to the town, if present
|-
| mail_multiplier
| 0 ... 255
|
|-
| accepted_cargos
| Array with up to 3 [cargo_id, amount]-pairs.
| The cargos that are accepted by each tile of the house. 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 fully accept both PASS and MAIL you could use this: <code style="color:darkgreen"><nowiki>accepted_cargos: [[PASS, 8], [MAIL, 8]];</nowiki></code> Example: for a house tile that doesn't accept any cargos at all you'd use: <code style="color:darkgreen">accepted_cargos: [];</code>
|-
| local_authority_impact
| 0 ... 65525
| amount of happiness decrease of the city council, if the building is destroyed. Town ratings can vary between -1000 (appalling) and +1000 (outstanding).
|-
| removal_cost_multiplier
| 0 ... 255
|
|-
| probability
| 0 ... 15 (float)
| Probability with respect to the default houses (=1). Mind that these are relative probabilities with respect to all houses defined. If all probabilities are defined as 16, they'll all have the same probability as if they had all a probability of 1.
|-
| years_available
| array of two int
| [xx, yy] where xx and yy indicate the introduction year and the last year the building can be built
|-
| minimum_lifetime
| 0 ... 255
| number of years the building will remain at least
|-
| availability_mask
|
[bitmask([[NML:List of town zones|town zones]]), bitmask(CLIMATE_XXX, ...)]
|
An array with two bitmasks, the first bitmask is a mask of town zones where this house is available. The second bitmask is a mask of climates combined with the special value ABOVE_SNOWLINE which you need to set for houses available in the arctic climate above the snowline. Examples:

* Available in the centre town zone in toyland only: <code>[bitmask(TOWNZONE_CENTRE), bitmask(CLIMATE_TOYLAND)]</code>
* Available in all town zones in the arctic climate both above and below the snowline: <code>[ALL_TOWNZONES, bitmask(CLIMATE_ARCTIC, ABOVE_SNOWLINE)]</code>
* Available everywhere except on the town edge: <code>[ALL_TOWNZONES & ~bitmask(TOWNZONE_EDGE), ALL_CLIMATES | bitmask(ABOVE_SNOWLINE)</code>
|-
| callback_flags
| bitmask(HOUSE_CBF_XX)
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| random_colours
| array of 4, each COLOUR_XXX
|
colour values in an array, refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for a list of possible values.
|-
| refresh_multiplier
| 0 ... 63
| Defines the frequency with which the tile will be re-randomized which has an impact for random animation. The tile will be processed by the periodic tile processing loop every (X + 1)*256 ticks, with X being the value of this property.
|-
| animation_info
| Array [ANIMATION_XXX, frame-count]
|
Type of animation and its length (1...128 frames):

;ANIMATION_LOOPING
;ANIMATION_NON_LOOPING
|-
| animation_speed
| 2 ... 16
|
Speed of animation, see [[NML:Animation speed|animation speed table]] for the meaning of the values.
|-
| building_class
| 0 .. 254
| An arbitrary number. You can check for the presence of buildings of the same class when building new buildings or using animation. Only the north tile of a multi-tile building is assigned a class.
|
|-
| watched_cargo_types
| array of values from your [[NML:Cargotable|cargo table]]
| {{ottdp|1.2|2.6|ottdrev=r23072|ttdprev=r1677}}List of cargo types to watch, to be used with the <code style:darkgreen>watched_cargo_accepted</code> callback.
|}

==House variables==

{| class="t"
! name
! value range
! comment
|-
| construction_state
| 0..3
| Current construction state of the house tile. 0..2 = under construction, 3 = finished.
|-
| pseudo_random_bits
| 0..3
| Some pseudo-random bits, based on the tile position. TTD houses use this to randomize their appearance.
|-
| random_bits
| 0..255
| 8 random bits, also used for [[NML:Random_switch|random switch]]-blocks. Initially these are the same for all tiles of a multi-tile house.
|-
| age
| 0..255
| Age of the house in years, limited to 255
|-
| town_zone
| [[NML:List of town zones|town zone]]
| The town zone of the current tile
|-
| terrain_type
| TILETYPE_XX
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|-
| same_house_count_town
| 0..255
| Number of the houses with the same ID in the same town as this house
|-
| same_house_count_map
| 0..255
| Number of the houses with the same ID on the entire map
|-
| same_class_count_town
| 0..255
| Number of the houses with the same <code style="color:darkgreen">building_class</code> in the same town as this house. The class of the north tile of the use is used for this purpose, as other tiles don't normally have a class.
|-
| same_class_count_map
| 0..255
| Number of the houses with the same <code style="color:darkgreen">building_class</code> on the entire map. The class of the north tile of the use is used for this purpose, as other tiles don't normally have a class.
|-
| generating_town
| [0 <nowiki>|</nowiki> 1]
| 1 a random town is currently being created, 0 otherwise. Note that while generating a random town, [[NML:Towns#Town variables|town variables]] <code style="color:darkgreen">population</code> and <code style="color:darkgreen">building_count</code> are incorrect. The population variable contains the population of buildings generated ''yet'', the final value may be larger. The building_count is surely higher than the final value will be.
|-
| animation_frame
| 0..255
| Current animation frame
|-
| x_coordinate
| 0..2047
| X-coordinate (top right -> bottom left) of the tile on the map
|-
| y_coordinate
| 0..2047
| Y-coordinate (top left -> bottom right) of the tile on the map
|-
| relative_x
| 0..1
| X-coordinate (top right -> bottom left) of the tile relative to the northernmost tile.
|-
| relative_y
| 0..1
| 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 [[NML:Builtin functions|builtin function]] relative_coord(x, y) may be useful when making comparisons.
|-
| house_tile
| HOUSE_TILE_XXX, XXX = <nowiki>[NORTH | EAST | WEST | SOUTH]</nowiki>
| What tile of a multi-tile house this is.
|-
| house_type_id
| 0..255
| Item ID of this house type, that was assigned to the item. See the note above about [[#Multi-tile houses|multi-tile houses]].
|}

The following variables require one or more arguments
{| class="t"
! name
! arguments
! value range
! comment
|-
| old_house_count_town
| ID of old house type (0..109)
| 0..255
| Number of old houses with a given ID in the same town as the current house
|-
| old_house_count_town
| ID of old house type (0..109)
| 0..255
| Number of old houses with a given ID on the whole map
|-
| other_house_count_town
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses with a given ID in the same town as the current house.
|-
| other_house_count_map
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses with a given ID on the whole map
|-
| other_class_count_town
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses, with the same class as the house with the given ID, in the same town as the current house
|-
| other_class_count_map
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses, with the same class as the house with the given ID, on the whole map
|-
| nearby_tile_slope
| x- and y-offset (both signed, range -8..7)
| SLOPE_XXX
| See [[NML:List of tile slopes|tile slopes]] for an overview of possible values
|-
| nearby_tile_is_water
| x- and y-offset (both signed, range -8..7)
| [0 <nowiki>|</nowiki> 1]
| 1 if the tile is water, 0 otherwise
|-
| nearby_tile_terrain_type
| x- and y-offset (both signed, range -8..7)
| TILETYPE_XX
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|-
| nearby_tile_water_class
| x- and y-offset (both signed, range -8..7)
| WATER_CLASS_XXX
| XXX = [NONE <nowiki>|</nowiki> SEA <nowiki>|</nowiki> CANAL <nowiki>|</nowiki> RIVER] Note that tiles for which <code style="color:darkgreen">nearby_tile_is_water</code> is 0 may still have a water class, e.g. industry tiles with water beneath them.
|-
| nearby_tile_height
| x- and y-offset (both signed, range -8..7)
| 0..255 (currently limited to 0..15)
| Height of the lowest corner of the tile. 1 unit is one height level of 8 pixels.
|-
| nearby_tile_class
| x- and y-offset (both signed, range -8..7)
|
[[NML:List of tile classes|Tile class]]
|
|-
| nearby_tile_animation_frame
| x- and y-offset (both signed, range -8..7)
| 0..255
| Animation frame of the given tile
|-
| cargo_accepted_nearby_ever
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby">Cargo type should be from your cargo translation table. X- and y-offset are optional, if provided both must be in range -128..127. A station is considered nearby if the tile is in the station's acceptance area. This is the purpose of the x- and y-offset, as other tiles may have other stations nearby.</ref>
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was ever accepted at a nearby station, 0 otherwise
|-
| cargo_accepted_nearby_last_month
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was accepted at a nearby station in the last month, 0 otherwise
|-
| cargo_accepted_nearby_this_month
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was ever accepted at a nearby station in this month, 0 otherwise
|-
| cargo_accepted_nearby_last_bigtick
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was ever accepted at a nearby station since the last periodic processing, which happens every 250 ticks. 0 otherwise
|-
| cargo_accepted_nearby_watched
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was one of the cargo types that triggered the <code style="color:darkgreen">watched_cargo_accepted</code>-callback (only during this callback), 0 otherwise
|-
| nearest_house_matching_criterion
| radius (1..63) and criterion (SEARCH_HOUSE_BY_XXX, XXX = [<nowiki>ID | CLASS | GRFID</nowiki>])
| 1..63, or 0 if not found
| Perform a circular search for a house matching either the id, <code style="color:darkgreen">building_class</code> or GRFID of this house, depending on the second parameter. The first parameter specifies the maximum search radius. Return value is the Manhattan distance of the closest matching house tile, or 0 if no match was found. Note that tiles of the originating house never match. See also the note above about [[#Multi-tile houses|multi-tile houses]].
|-
| nearby_tile_house_id
| x- and y-offset (both signed, range -8..7)
| -1, or 0 .. 767
| Return value is -1 if the tile is not a house tile, X (0..255) if the tile contains old house type X, 256+X if the tile contains a house from this NewGRF with ID X, 512+X if the tile contains a house from a different NewGRF with ID X. See the note above about [[#Multi-tile houses|multi-tile houses]].
|-
| nearby_tile_house_class
| x- and y-offset (both signed, range -8..7)
| -1, 0, or 256 .. 767
| Return value is -1 if the tile is not a house tile, 0 if the house tile does not have a class (this includes all old house types), 256+X (X = 0..255) if the house has been defined by this NewGRF with <code style="color:darkgreen">building_class</code> X or 512+X if the house has been defined by a different NewGRF with <code style="color:darkgreen">building_class</code> X. Note that for a multi-tile house, generally only the north tile has a sensible class value.
|-
| nearby_tile_house_grfid
| x- and y-offset (both signed, range -8..7)
| -1, 0 or a GRFID
| Return value is -1 if the tile is not a house tile, 0 if the house tile contains an old house type, or else the GRFID of the NewGRF defining the house.
|}
<references/>

==House callbacks==
Unless noted otherwise, callbacks may be called for any of the tiles of a multi-tile house.

{| class="t"
! callback
! return value
! comment
|-
| default
| Sprite layout
| Graphics for the house tile
|-
| graphics_xxx, xxx = <nowiki>[north | east | south | west]</nowiki>
| Sprite layout
| Tile-specific graphics for one of the tiles of a multi-tile house. Of course, this is callback is called for that tile only.
|-
| random_trigger
| N/A
|
See [[NML:Random switch|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. <code>extra_callback_info1</code> contains 32 random bits, if enabled in the <code>building_flags</code> property. Returning a sound effect in the high byte will cause that sound effect to be played.
|-
| anim_control
| Next animation frame or CB_RESULT_XXX
| Called every 256 ticks. Return the animation frame to show, or CB_RESULT_XXX with XXX = <nowiki>[CB_RESULT_START_ANIMATION | STOP_ANIMATION | DO_NOTHING]</nowiki> to respectively start the animation in its current frame, stop the animation or do nothing. <code>extra_callback_info1</code> contains 32 random bits. The low 16 bits are always different for each house tile, but the high 16 bits are the same for each tile if synchronized animation is enabled in the <code>building_flags</code>-property. Returning a sound effect in the high byte will cause that sound effect to be played.
|-
| construction_anim
| Same as <code>anim_control</code>
| Works the same as the <code>anim_control</code> callback, except that it's called when the construction state changes.
|-
| watched_cargo_accepted
| Same as <code>anim_control</code>
| Works the same as the <code>anim_control</code> callback, except that it's called when one of the watched cargo types is accepted.
|-
| 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 <code>accepted_cargo</code> 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 the acceptance properties are used instead. Cargo types are from the <code>cargo_type_accept</code> callback, or the <code>accepted_cargo</code> 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.
|-
| cargo_production
| (cargo_type * 256) + amount
| Called every 256 ticks. Called multiple times until 0x20FF is returned. The high byte of the result contains a cargo type, the low byte contains the amount of that cargo to produce. <code>extra_callback_info1</code> contains the number of iterations so far, <code>extra_callback_info2</code> contains random bits.
|-
| 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.
|-
| name
| String
| Name of the building (when using tile query tool)
|-
| colour
| Palette number
|
Used to recolour the building. See here [[NML:List of default colour translation palettes|here]] for an overview of default palettes.
|-
| construction_check
| 0 or 1
| Return 1 to allow building the house or 0 to disallow. Called only for the north tile.
|-
| destruction
| 0 or 1
| Called periodically. Return 0 to keep the building or 1 to destroy it. Called only for the north tile.
|-
| protection
| 0 or 1
| Return 0 to allow destruction, or 1 to disallow
|}

NML:Houses

2012-09-05T12:04:48Z

Hirundo: /* House callbacks */ Fix missing nowiki tag

{{NMLNavPropVarCB}}
==House IDs==
House 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 house. The value of this property should be the ID of a [[NML:List_of_default_house_properties|default house type]], which will be used instead of your item if it is not available for whatever reason (for example, missing NewGRF).

Although the majority of all original houses occupy a single tile, it is possible to define a larger house of up to 2x2 tiles. For this, you should set the fourth 'size' parameter in the item-block. Valid values are HOUSE_SIZE_XXX, XXX = <nowiki>[1X1 | 1X2 | 2X1 | 2X2]</nowiki>. This size should match the size of the substitute house type.

===Multi-tile houses===
Internally, due to the way NewGRF houses work, a multi-tile house will occupy more than one item ID. If you assign item ID X to a house, item IDs X+1 (for a 2-tile house) and (X+1) .. (X+3) (for a 4-tile house) will also be used. Normally you don't have to care about this, but there are two exceptions:
* If you manually assign numeric ids to your houses. You are recommended to just set all ids to -1 and let NML figure it out for you.
* When working with several variables that work with house type IDs. Keep in mind that tiles of a multi-tile house may have IDs X .. X + N - 1, with X being the assigned id and N the number of house tiles.

==House properties==

{| class="t"
! property
! value range
! comment
|-
| name
| string
| for example string(STR_NAME_EIFFEL_TOWER)
|-
| substitute
| 0 ... 109
| Number of the default house that replaces this one, if this house 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, except for the church / stadium flags (see below). The old house must have the same size as the new house, see the list of [[NML:List_of_default_house_properties|default house types]] for a list of possible substitute IDs.
|-
| override
| 0 ... 109
| id of the default house which this house replaces. This will cause your house to be placed instead of the default house. This is ignored, if the default house has already been overridden. You can define this property multiple times. Your house and the overridden house must have the same size, see the list of [[NML:List_of_default_house_properties|default house types]].
|-
| building_flags.
| bitmask(HOUSE_FLAG_XXX,...)
|
;HOUSE_FLAG_NOT_SLOPED
:Can only be built on flat terrain. Note that 2x2 buildings will always only be built on flat land, even if this bit isn't set.
;HOUSE_FLAG_ANIMATE
:Enable animation
;HOUSE_FLAG_CHURCH
:House is a church (only 1 will be built per town)
;HOUSE_FLAG_STADIUM
:House is a stadium (only 1 will be built per town)
;HOUSE_FLAG_ONLY_SE
:Can only be built in the scenario editor
;HOUSE_FLAG_PROTECTED
:Will not be removed by the game
;HOUSE_FLAG_SYNC_CALLBACK
:Animation callback <code style="color:darkgreen">anim_control</code> is called at the same time for all tiles.
;HOUSE_FLAG_RANDOM_ANIMATION
:Enable random bits in the <code style="color:darkgreen">anim_next_frame</code>-callback.
|-
| population
| 0 ... 255
| number of inhabitants the building adds to the town, if present
|-
| mail_multiplier
| 0 ... 255
|
|-
| accepted_cargos
| Array with up to 3 [cargo_id, amount]-pairs.
| The cargos that are accepted by each tile of the house. 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 fully accept both PASS and MAIL you could use this: <code style="color:darkgreen"><nowiki>accepted_cargos: [[PASS, 8], [MAIL, 8]];</nowiki></code> Example: for a house tile that doesn't accept any cargos at all you'd use: <code style="color:darkgreen">accepted_cargos: [];</code>
|-
| local_authority_impact
| 0 ... 65525
| amount of happiness decrease of the city council, if the building is destroyed. Town ratings can vary between -1000 (appalling) and +1000 (outstanding).
|-
| removal_cost_multiplier
| 0 ... 255
|
|-
| probability
| 0 ... 16 (float)
| Probability with respect to the default houses (=1). Mind that these are relative probabilities with respect to all houses defined. If all probabilities are defined as 16, they'll all have the same probability as if they had all a probability of 1.
|-
| years_available
| array of two int
| [xx, yy] where xx and yy indicate the introduction year and the last year the building can be built
|-
| minimum_lifetime
| 0 ... 255
| number of years the building will remain at least
|-
| availability_mask
|
[bitmask([[NML:List of town zones|town zones]]), bitmask(CLIMATE_XXX, ...)]
|
An array with two bitmasks, the first bitmask is a mask of town zones where this house is available. The second bitmask is a mask of climates combined with the special value ABOVE_SNOWLINE which you need to set for houses available in the arctic climate above the snowline. Examples:

* Available in the centre town zone in toyland only: <code>[bitmask(TOWNZONE_CENTRE), bitmask(CLIMATE_TOYLAND)]</code>
* Available in all town zones in the arctic climate both above and below the snowline: <code>[ALL_TOWNZONES, bitmask(CLIMATE_ARCTIC, ABOVE_SNOWLINE)]</code>
* Available everywhere except on the town edge: <code>[ALL_TOWNZONES & ~bitmask(TOWNZONE_EDGE), ALL_CLIMATES | bitmask(ABOVE_SNOWLINE)</code>
|-
| callback_flags
| bitmask(HOUSE_CBF_XX)
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| random_colours
| array of 4, each COLOUR_XXX
|
colour values in an array, refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for a list of possible values.
|-
| refresh_multiplier
| 0 ... 63
| Defines the frequency with which the tile will be re-randomized which has an impact for random animation. The tile will be processed by the periodic tile processing loop every (X + 1)*256 ticks, with X being the value of this property.
|-
| animation_info
| Array [ANIMATION_XXX, frame-count]
|
Type of animation and its length (1...128 frames):

;ANIMATION_LOOPING
;ANIMATION_NON_LOOPING
|-
| animation_speed
| 2 ... 16
|
Speed of animation, see [[NML:Animation speed|animation speed table]] for the meaning of the values.
|-
| building_class
| 0 .. 254
| An arbitrary number. You can check for the presence of buildings of the same class when building new buildings or using animation. Only the north tile of a multi-tile building is assigned a class.
|
|-
| watched_cargo_types
| array of values from your [[NML:Cargotable|cargo table]]
| {{ottdp|1.2|2.6|ottdrev=r23072|ttdprev=r1677}}List of cargo types to watch, to be used with the <code style:darkgreen>watched_cargo_accepted</code> callback.
|}

==House variables==

{| class="t"
! name
! value range
! comment
|-
| construction_state
| 0..3
| Current construction state of the house tile. 0..2 = under construction, 3 = finished.
|-
| pseudo_random_bits
| 0..3
| Some pseudo-random bits, based on the tile position. TTD houses use this to randomize their appearance.
|-
| random_bits
| 0..255
| 8 random bits, also used for [[NML:Random_switch|random switch]]-blocks. Initially these are the same for all tiles of a multi-tile house.
|-
| age
| 0..255
| Age of the house in years, limited to 255
|-
| town_zone
| [[NML:List of town zones|town zone]]
| The town zone of the current tile
|-
| terrain_type
| TILETYPE_XX
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|-
| same_house_count_town
| 0..255
| Number of the houses with the same ID in the same town as this house
|-
| same_house_count_map
| 0..255
| Number of the houses with the same ID on the entire map
|-
| same_class_count_town
| 0..255
| Number of the houses with the same <code style="color:darkgreen">building_class</code> in the same town as this house. The class of the north tile of the use is used for this purpose, as other tiles don't normally have a class.
|-
| same_class_count_map
| 0..255
| Number of the houses with the same <code style="color:darkgreen">building_class</code> on the entire map. The class of the north tile of the use is used for this purpose, as other tiles don't normally have a class.
|-
| generating_town
| [0 <nowiki>|</nowiki> 1]
| 1 a random town is currently being created, 0 otherwise. Note that while generating a random town, [[NML:Towns#Town variables|town variables]] <code style="color:darkgreen">population</code> and <code style="color:darkgreen">building_count</code> are incorrect. The population variable contains the population of buildings generated ''yet'', the final value may be larger. The building_count is surely higher than the final value will be.
|-
| animation_frame
| 0..255
| Current animation frame
|-
| x_coordinate
| 0..2047
| X-coordinate (top right -> bottom left) of the tile on the map
|-
| y_coordinate
| 0..2047
| Y-coordinate (top left -> bottom right) of the tile on the map
|-
| relative_x
| 0..1
| X-coordinate (top right -> bottom left) of the tile relative to the northernmost tile.
|-
| relative_y
| 0..1
| 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 [[NML:Builtin functions|builtin function]] relative_coord(x, y) may be useful when making comparisons.
|-
| house_tile
| HOUSE_TILE_XXX, XXX = <nowiki>[NORTH | EAST | WEST | SOUTH]</nowiki>
| What tile of a multi-tile house this is.
|-
| house_type_id
| 0..255
| Item ID of this house type, that was assigned to the item. See the note above about [[#Multi-tile houses|multi-tile houses]].
|}

The following variables require one or more arguments
{| class="t"
! name
! arguments
! value range
! comment
|-
| old_house_count_town
| ID of old house type (0..109)
| 0..255
| Number of old houses with a given ID in the same town as the current house
|-
| old_house_count_town
| ID of old house type (0..109)
| 0..255
| Number of old houses with a given ID on the whole map
|-
| other_house_count_town
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses with a given ID in the same town as the current house.
|-
| other_house_count_map
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses with a given ID on the whole map
|-
| other_class_count_town
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses, with the same class as the house with the given ID, in the same town as the current house
|-
| other_class_count_map
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses, with the same class as the house with the given ID, on the whole map
|-
| nearby_tile_slope
| x- and y-offset (both signed, range -8..7)
| SLOPE_XXX
| See [[NML:List of tile slopes|tile slopes]] for an overview of possible values
|-
| nearby_tile_is_water
| x- and y-offset (both signed, range -8..7)
| [0 <nowiki>|</nowiki> 1]
| 1 if the tile is water, 0 otherwise
|-
| nearby_tile_terrain_type
| x- and y-offset (both signed, range -8..7)
| TILETYPE_XX
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|-
| nearby_tile_water_class
| x- and y-offset (both signed, range -8..7)
| WATER_CLASS_XXX
| XXX = [NONE <nowiki>|</nowiki> SEA <nowiki>|</nowiki> CANAL <nowiki>|</nowiki> RIVER] Note that tiles for which <code style="color:darkgreen">nearby_tile_is_water</code> is 0 may still have a water class, e.g. industry tiles with water beneath them.
|-
| nearby_tile_height
| x- and y-offset (both signed, range -8..7)
| 0..255 (currently limited to 0..15)
| Height of the lowest corner of the tile. 1 unit is one height level of 8 pixels.
|-
| nearby_tile_class
| x- and y-offset (both signed, range -8..7)
|
[[NML:List of tile classes|Tile class]]
|
|-
| nearby_tile_animation_frame
| x- and y-offset (both signed, range -8..7)
| 0..255
| Animation frame of the given tile
|-
| cargo_accepted_nearby_ever
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby">Cargo type should be from your cargo translation table. X- and y-offset are optional, if provided both must be in range -128..127. A station is considered nearby if the tile is in the station's acceptance area. This is the purpose of the x- and y-offset, as other tiles may have other stations nearby.</ref>
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was ever accepted at a nearby station, 0 otherwise
|-
| cargo_accepted_nearby_last_month
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was accepted at a nearby station in the last month, 0 otherwise
|-
| cargo_accepted_nearby_this_month
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was ever accepted at a nearby station in this month, 0 otherwise
|-
| cargo_accepted_nearby_last_bigtick
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was ever accepted at a nearby station since the last periodic processing, which happens every 250 ticks. 0 otherwise
|-
| cargo_accepted_nearby_watched
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was one of the cargo types that triggered the <code style="color:darkgreen">watched_cargo_accepted</code>-callback (only during this callback), 0 otherwise
|-
| nearest_house_matching_criterion
| radius (1..63) and criterion (SEARCH_HOUSE_BY_XXX, XXX = [<nowiki>ID | CLASS | GRFID</nowiki>])
| 1..63, or 0 if not found
| Perform a circular search for a house matching either the id, <code style="color:darkgreen">building_class</code> or GRFID of this house, depending on the second parameter. The first parameter specifies the maximum search radius. Return value is the Manhattan distance of the closest matching house tile, or 0 if no match was found. Note that tiles of the originating house never match. See also the note above about [[#Multi-tile houses|multi-tile houses]].
|-
| nearby_tile_house_id
| x- and y-offset (both signed, range -8..7)
| -1, or 0 .. 767
| Return value is -1 if the tile is not a house tile, X (0..255) if the tile contains old house type X, 256+X if the tile contains a house from this NewGRF with ID X, 512+X if the tile contains a house from a different NewGRF with ID X. See the note above about [[#Multi-tile houses|multi-tile houses]].
|-
| nearby_tile_house_class
| x- and y-offset (both signed, range -8..7)
| -1, 0, or 256 .. 767
| Return value is -1 if the tile is not a house tile, 0 if the house tile does not have a class (this includes all old house types), 256+X (X = 0..255) if the house has been defined by this NewGRF with <code style="color:darkgreen">building_class</code> X or 512+X if the house has been defined by a different NewGRF with <code style="color:darkgreen">building_class</code> X. Note that for a multi-tile house, generally only the north tile has a sensible class value.
|-
| nearby_tile_house_grfid
| x- and y-offset (both signed, range -8..7)
| -1, 0 or a GRFID
| Return value is -1 if the tile is not a house tile, 0 if the house tile contains an old house type, or else the GRFID of the NewGRF defining the house.
|}
<references/>

==House callbacks==
Unless noted otherwise, callbacks may be called for any of the tiles of a multi-tile house.

{| class="t"
! callback
! return value
! comment
|-
| default
| Sprite layout
| Graphics for the house tile
|-
| graphics_xxx, xxx = <nowiki>[north | east | south | west]</nowiki>
| Sprite layout
| Tile-specific graphics for one of the tiles of a multi-tile house. Of course, this is callback is called for that tile only.
|-
| random_trigger
| N/A
|
See [[NML:Random switch|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. <code>extra_callback_info1</code> contains 32 random bits, if enabled in the <code>building_flags</code> property. Returning a sound effect in the high byte will cause that sound effect to be played.
|-
| anim_control
| Next animation frame or CB_RESULT_XXX
| Called every 256 ticks. Return the animation frame to show, or CB_RESULT_XXX with XXX = <nowiki>[CB_RESULT_START_ANIMATION | STOP_ANIMATION | DO_NOTHING]</nowiki> to respectively start the animation in its current frame, stop the animation or do nothing. <code>extra_callback_info1</code> contains 32 random bits. The low 16 bits are always different for each house tile, but the high 16 bits are the same for each tile if synchronized animation is enabled in the <code>building_flags</code>-property. Returning a sound effect in the high byte will cause that sound effect to be played.
|-
| construction_anim
| Same as <code>anim_control</code>
| Works the same as the <code>anim_control</code> callback, except that it's called when the construction state changes.
|-
| watched_cargo_accepted
| Same as <code>anim_control</code>
| Works the same as the <code>anim_control</code> callback, except that it's called when one of the watched cargo types is accepted.
|-
| 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 <code>accepted_cargo</code> 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 the acceptance properties are used instead. Cargo types are from the <code>cargo_type_accept</code> callback, or the <code>accepted_cargo</code> 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.
|-
| cargo_production
| (cargo_type * 256) + amount
| Called every 256 ticks. Called multiple times until 0x20FF is returned. The high byte of the result contains a cargo type, the low byte contains the amount of that cargo to produce. <code>extra_callback_info1</code> contains the number of iterations so far, <code>extra_callback_info2</code> contains random bits.
|-
| 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.
|-
| name
| String
| Name of the building (when using tile query tool)
|-
| colour
| Palette number
|
Used to recolour the building. See here [[NML:List of default colour translation palettes|here]] for an overview of default palettes.
|-
| construction_check
| 0 or 1
| Return 1 to allow building the house or 0 to disallow. Called only for the north tile.
|-
| destruction
| 0 or 1
| Called periodically. Return 0 to keep the building or 1 to destroy it. Called only for the north tile.
|-
| protection
| 0 or 1
| Return 0 to allow destruction, or 1 to disallow
|}

NML:Houses

2012-09-05T11:59:35Z

Hirundo: Clarify refresh_multiplier

{{NMLNavPropVarCB}}
==House IDs==
House 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 house. The value of this property should be the ID of a [[NML:List_of_default_house_properties|default house type]], which will be used instead of your item if it is not available for whatever reason (for example, missing NewGRF).

Although the majority of all original houses occupy a single tile, it is possible to define a larger house of up to 2x2 tiles. For this, you should set the fourth 'size' parameter in the item-block. Valid values are HOUSE_SIZE_XXX, XXX = <nowiki>[1X1 | 1X2 | 2X1 | 2X2]</nowiki>. This size should match the size of the substitute house type.

===Multi-tile houses===
Internally, due to the way NewGRF houses work, a multi-tile house will occupy more than one item ID. If you assign item ID X to a house, item IDs X+1 (for a 2-tile house) and (X+1) .. (X+3) (for a 4-tile house) will also be used. Normally you don't have to care about this, but there are two exceptions:
* If you manually assign numeric ids to your houses. You are recommended to just set all ids to -1 and let NML figure it out for you.
* When working with several variables that work with house type IDs. Keep in mind that tiles of a multi-tile house may have IDs X .. X + N - 1, with X being the assigned id and N the number of house tiles.

==House properties==

{| class="t"
! property
! value range
! comment
|-
| name
| string
| for example string(STR_NAME_EIFFEL_TOWER)
|-
| substitute
| 0 ... 109
| Number of the default house that replaces this one, if this house 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, except for the church / stadium flags (see below). The old house must have the same size as the new house, see the list of [[NML:List_of_default_house_properties|default house types]] for a list of possible substitute IDs.
|-
| override
| 0 ... 109
| id of the default house which this house replaces. This will cause your house to be placed instead of the default house. This is ignored, if the default house has already been overridden. You can define this property multiple times. Your house and the overridden house must have the same size, see the list of [[NML:List_of_default_house_properties|default house types]].
|-
| building_flags.
| bitmask(HOUSE_FLAG_XXX,...)
|
;HOUSE_FLAG_NOT_SLOPED
:Can only be built on flat terrain. Note that 2x2 buildings will always only be built on flat land, even if this bit isn't set.
;HOUSE_FLAG_ANIMATE
:Enable animation
;HOUSE_FLAG_CHURCH
:House is a church (only 1 will be built per town)
;HOUSE_FLAG_STADIUM
:House is a stadium (only 1 will be built per town)
;HOUSE_FLAG_ONLY_SE
:Can only be built in the scenario editor
;HOUSE_FLAG_PROTECTED
:Will not be removed by the game
;HOUSE_FLAG_SYNC_CALLBACK
:Animation callback <code style="color:darkgreen">anim_control</code> is called at the same time for all tiles.
;HOUSE_FLAG_RANDOM_ANIMATION
:Enable random bits in the <code style="color:darkgreen">anim_next_frame</code>-callback.
|-
| population
| 0 ... 255
| number of inhabitants the building adds to the town, if present
|-
| mail_multiplier
| 0 ... 255
|
|-
| accepted_cargos
| Array with up to 3 [cargo_id, amount]-pairs.
| The cargos that are accepted by each tile of the house. 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 fully accept both PASS and MAIL you could use this: <code style="color:darkgreen"><nowiki>accepted_cargos: [[PASS, 8], [MAIL, 8]];</nowiki></code> Example: for a house tile that doesn't accept any cargos at all you'd use: <code style="color:darkgreen">accepted_cargos: [];</code>
|-
| local_authority_impact
| 0 ... 65525
| amount of happiness decrease of the city council, if the building is destroyed. Town ratings can vary between -1000 (appalling) and +1000 (outstanding).
|-
| removal_cost_multiplier
| 0 ... 255
|
|-
| probability
| 0 ... 16 (float)
| Probability with respect to the default houses (=1). Mind that these are relative probabilities with respect to all houses defined. If all probabilities are defined as 16, they'll all have the same probability as if they had all a probability of 1.
|-
| years_available
| array of two int
| [xx, yy] where xx and yy indicate the introduction year and the last year the building can be built
|-
| minimum_lifetime
| 0 ... 255
| number of years the building will remain at least
|-
| availability_mask
|
[bitmask([[NML:List of town zones|town zones]]), bitmask(CLIMATE_XXX, ...)]
|
An array with two bitmasks, the first bitmask is a mask of town zones where this house is available. The second bitmask is a mask of climates combined with the special value ABOVE_SNOWLINE which you need to set for houses available in the arctic climate above the snowline. Examples:

* Available in the centre town zone in toyland only: <code>[bitmask(TOWNZONE_CENTRE), bitmask(CLIMATE_TOYLAND)]</code>
* Available in all town zones in the arctic climate both above and below the snowline: <code>[ALL_TOWNZONES, bitmask(CLIMATE_ARCTIC, ABOVE_SNOWLINE)]</code>
* Available everywhere except on the town edge: <code>[ALL_TOWNZONES & ~bitmask(TOWNZONE_EDGE), ALL_CLIMATES | bitmask(ABOVE_SNOWLINE)</code>
|-
| callback_flags
| bitmask(HOUSE_CBF_XX)
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| random_colours
| array of 4, each COLOUR_XXX
|
colour values in an array, refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for a list of possible values.
|-
| refresh_multiplier
| 0 ... 63
| Defines the frequency with which the tile will be re-randomized which has an impact for random animation. The tile will be processed by the periodic tile processing loop every (X + 1)*256 ticks, with X being the value of this property.
|-
| animation_info
| Array [ANIMATION_XXX, frame-count]
|
Type of animation and its length (1...128 frames):

;ANIMATION_LOOPING
;ANIMATION_NON_LOOPING
|-
| animation_speed
| 2 ... 16
|
Speed of animation, see [[NML:Animation speed|animation speed table]] for the meaning of the values.
|-
| building_class
| 0 .. 254
| An arbitrary number. You can check for the presence of buildings of the same class when building new buildings or using animation. Only the north tile of a multi-tile building is assigned a class.
|
|-
| watched_cargo_types
| array of values from your [[NML:Cargotable|cargo table]]
| {{ottdp|1.2|2.6|ottdrev=r23072|ttdprev=r1677}}List of cargo types to watch, to be used with the <code style:darkgreen>watched_cargo_accepted</code> callback.
|}

==House variables==

{| class="t"
! name
! value range
! comment
|-
| construction_state
| 0..3
| Current construction state of the house tile. 0..2 = under construction, 3 = finished.
|-
| pseudo_random_bits
| 0..3
| Some pseudo-random bits, based on the tile position. TTD houses use this to randomize their appearance.
|-
| random_bits
| 0..255
| 8 random bits, also used for [[NML:Random_switch|random switch]]-blocks. Initially these are the same for all tiles of a multi-tile house.
|-
| age
| 0..255
| Age of the house in years, limited to 255
|-
| town_zone
| [[NML:List of town zones|town zone]]
| The town zone of the current tile
|-
| terrain_type
| TILETYPE_XX
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|-
| same_house_count_town
| 0..255
| Number of the houses with the same ID in the same town as this house
|-
| same_house_count_map
| 0..255
| Number of the houses with the same ID on the entire map
|-
| same_class_count_town
| 0..255
| Number of the houses with the same <code style="color:darkgreen">building_class</code> in the same town as this house. The class of the north tile of the use is used for this purpose, as other tiles don't normally have a class.
|-
| same_class_count_map
| 0..255
| Number of the houses with the same <code style="color:darkgreen">building_class</code> on the entire map. The class of the north tile of the use is used for this purpose, as other tiles don't normally have a class.
|-
| generating_town
| [0 <nowiki>|</nowiki> 1]
| 1 a random town is currently being created, 0 otherwise. Note that while generating a random town, [[NML:Towns#Town variables|town variables]] <code style="color:darkgreen">population</code> and <code style="color:darkgreen">building_count</code> are incorrect. The population variable contains the population of buildings generated ''yet'', the final value may be larger. The building_count is surely higher than the final value will be.
|-
| animation_frame
| 0..255
| Current animation frame
|-
| x_coordinate
| 0..2047
| X-coordinate (top right -> bottom left) of the tile on the map
|-
| y_coordinate
| 0..2047
| Y-coordinate (top left -> bottom right) of the tile on the map
|-
| relative_x
| 0..1
| X-coordinate (top right -> bottom left) of the tile relative to the northernmost tile.
|-
| relative_y
| 0..1
| 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 [[NML:Builtin functions|builtin function]] relative_coord(x, y) may be useful when making comparisons.
|-
| house_tile
| HOUSE_TILE_XXX, XXX = <nowiki>[NORTH | EAST | WEST | SOUTH]</nowiki>
| What tile of a multi-tile house this is.
|-
| house_type_id
| 0..255
| Item ID of this house type, that was assigned to the item. See the note above about [[#Multi-tile houses|multi-tile houses]].
|}

The following variables require one or more arguments
{| class="t"
! name
! arguments
! value range
! comment
|-
| old_house_count_town
| ID of old house type (0..109)
| 0..255
| Number of old houses with a given ID in the same town as the current house
|-
| old_house_count_town
| ID of old house type (0..109)
| 0..255
| Number of old houses with a given ID on the whole map
|-
| other_house_count_town
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses with a given ID in the same town as the current house.
|-
| other_house_count_map
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses with a given ID on the whole map
|-
| other_class_count_town
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses, with the same class as the house with the given ID, in the same town as the current house
|-
| other_class_count_map
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses, with the same class as the house with the given ID, on the whole map
|-
| nearby_tile_slope
| x- and y-offset (both signed, range -8..7)
| SLOPE_XXX
| See [[NML:List of tile slopes|tile slopes]] for an overview of possible values
|-
| nearby_tile_is_water
| x- and y-offset (both signed, range -8..7)
| [0 <nowiki>|</nowiki> 1]
| 1 if the tile is water, 0 otherwise
|-
| nearby_tile_terrain_type
| x- and y-offset (both signed, range -8..7)
| TILETYPE_XX
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|-
| nearby_tile_water_class
| x- and y-offset (both signed, range -8..7)
| WATER_CLASS_XXX
| XXX = [NONE <nowiki>|</nowiki> SEA <nowiki>|</nowiki> CANAL <nowiki>|</nowiki> RIVER] Note that tiles for which <code style="color:darkgreen">nearby_tile_is_water</code> is 0 may still have a water class, e.g. industry tiles with water beneath them.
|-
| nearby_tile_height
| x- and y-offset (both signed, range -8..7)
| 0..255 (currently limited to 0..15)
| Height of the lowest corner of the tile. 1 unit is one height level of 8 pixels.
|-
| nearby_tile_class
| x- and y-offset (both signed, range -8..7)
|
[[NML:List of tile classes|Tile class]]
|
|-
| nearby_tile_animation_frame
| x- and y-offset (both signed, range -8..7)
| 0..255
| Animation frame of the given tile
|-
| cargo_accepted_nearby_ever
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby">Cargo type should be from your cargo translation table. X- and y-offset are optional, if provided both must be in range -128..127. A station is considered nearby if the tile is in the station's acceptance area. This is the purpose of the x- and y-offset, as other tiles may have other stations nearby.</ref>
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was ever accepted at a nearby station, 0 otherwise
|-
| cargo_accepted_nearby_last_month
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was accepted at a nearby station in the last month, 0 otherwise
|-
| cargo_accepted_nearby_this_month
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was ever accepted at a nearby station in this month, 0 otherwise
|-
| cargo_accepted_nearby_last_bigtick
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was ever accepted at a nearby station since the last periodic processing, which happens every 250 ticks. 0 otherwise
|-
| cargo_accepted_nearby_watched
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was one of the cargo types that triggered the <code style="color:darkgreen">watched_cargo_accepted</code>-callback (only during this callback), 0 otherwise
|-
| nearest_house_matching_criterion
| radius (1..63) and criterion (SEARCH_HOUSE_BY_XXX, XXX = [<nowiki>ID | CLASS | GRFID</nowiki>])
| 1..63, or 0 if not found
| Perform a circular search for a house matching either the id, <code style="color:darkgreen">building_class</code> or GRFID of this house, depending on the second parameter. The first parameter specifies the maximum search radius. Return value is the Manhattan distance of the closest matching house tile, or 0 if no match was found. Note that tiles of the originating house never match. See also the note above about [[#Multi-tile houses|multi-tile houses]].
|-
| nearby_tile_house_id
| x- and y-offset (both signed, range -8..7)
| -1, or 0 .. 767
| Return value is -1 if the tile is not a house tile, X (0..255) if the tile contains old house type X, 256+X if the tile contains a house from this NewGRF with ID X, 512+X if the tile contains a house from a different NewGRF with ID X. See the note above about [[#Multi-tile houses|multi-tile houses]].
|-
| nearby_tile_house_class
| x- and y-offset (both signed, range -8..7)
| -1, 0, or 256 .. 767
| Return value is -1 if the tile is not a house tile, 0 if the house tile does not have a class (this includes all old house types), 256+X (X = 0..255) if the house has been defined by this NewGRF with <code style="color:darkgreen">building_class</code> X or 512+X if the house has been defined by a different NewGRF with <code style="color:darkgreen">building_class</code> X. Note that for a multi-tile house, generally only the north tile has a sensible class value.
|-
| nearby_tile_house_grfid
| x- and y-offset (both signed, range -8..7)
| -1, 0 or a GRFID
| Return value is -1 if the tile is not a house tile, 0 if the house tile contains an old house type, or else the GRFID of the NewGRF defining the house.
|}
<references/>

==House callbacks==
Unless noted otherwise, callbacks may be called for any of the tiles of a multi-tile house.

{| class="t"
! callback
! return value
! comment
|-
| default
| Sprite layout
| Graphics for the house tile
|-
| graphics_xxx, xxx = <nowiki>[north | east | south | west]</nowiki>
| Sprite layout
| Tile-specific graphics for one of the tiles of a multi-tile house. Of course, this is callback is called for that tile only.
|-
| random_trigger
| N/A
|
See [[NML:Random switch|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. <code>extra_callback_info1</code> contains 32 random bits, if enabled in the <code>building_flags</code> property. Returning a sound effect in the high byte will cause that sound effect to be played.
|-
| anim_control
| Next animation frame or CB_RESULT_XXX
| Called every 256 ticks. 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. <code>extra_callback_info1</code> contains 32 random bits. The low 16 bits are always different for each house tile, but the high 16 bits are the same for each tile if synchronized animation is enabled in the <code>building_flags</code>-property. Returning a sound effect in the high byte will cause that sound effect to be played.
|-
| construction_anim
| Same as <code>anim_control</code>
| Works the same as the <code>anim_control</code> callback, except that it's called when the construction state changes.
|-
| watched_cargo_accepted
| Same as <code>anim_control</code>
| Works the same as the <code>anim_control</code> callback, except that it's called when one of the watched cargo types is accepted.
|-
| 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 <code>accepted_cargo</code> 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 the acceptance properties are used instead. Cargo types are from the <code>cargo_type_accept</code> callback, or the <code>accepted_cargo</code> 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.
|-
| cargo_production
| (cargo_type * 256) + amount
| Called every 256 ticks. Called multiple times until 0x20FF is returned. The high byte of the result contains a cargo type, the low byte contains the amount of that cargo to produce. <code>extra_callback_info1</code> contains the number of iterations so far, <code>extra_callback_info2</code> contains random bits.
|-
| 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.
|-
| name
| String
| Name of the building (when using tile query tool)
|-
| colour
| Palette number
|
Used to recolour the building. See here [[NML:List of default colour translation palettes|here]] for an overview of default palettes.
|-
| construction_check
| 0 or 1
| Return 1 to allow building the house or 0 to disallow. Called only for the north tile.
|-
| destruction
| 0 or 1
| Called periodically. Return 0 to keep the building or 1 to destroy it. Called only for the north tile.
|-
| protection
| 0 or 1
| Return 0 to allow destruction, or 1 to disallow
|}

NML:Houses

2012-09-05T11:37:53Z

Hirundo: /* House variables */ Add missing variable random_bits

{{NMLNavPropVarCB}}
==House IDs==
House 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 house. The value of this property should be the ID of a [[NML:List_of_default_house_properties|default house type]], which will be used instead of your item if it is not available for whatever reason (for example, missing NewGRF).

Although the majority of all original houses occupy a single tile, it is possible to define a larger house of up to 2x2 tiles. For this, you should set the fourth 'size' parameter in the item-block. Valid values are HOUSE_SIZE_XXX, XXX = <nowiki>[1X1 | 1X2 | 2X1 | 2X2]</nowiki>. This size should match the size of the substitute house type.

===Multi-tile houses===
Internally, due to the way NewGRF houses work, a multi-tile house will occupy more than one item ID. If you assign item ID X to a house, item IDs X+1 (for a 2-tile house) and (X+1) .. (X+3) (for a 4-tile house) will also be used. Normally you don't have to care about this, but there are two exceptions:
* If you manually assign numeric ids to your houses. You are recommended to just set all ids to -1 and let NML figure it out for you.
* When working with several variables that work with house type IDs. Keep in mind that tiles of a multi-tile house may have IDs X .. X + N - 1, with X being the assigned id and N the number of house tiles.

==House properties==

{| class="t"
! property
! value range
! comment
|-
| name
| string
| for example string(STR_NAME_EIFFEL_TOWER)
|-
| substitute
| 0 ... 109
| Number of the default house that replaces this one, if this house 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, except for the church / stadium flags (see below). The old house must have the same size as the new house, see the list of [[NML:List_of_default_house_properties|default house types]] for a list of possible substitute IDs.
|-
| override
| 0 ... 109
| id of the default house which this house replaces. This will cause your house to be placed instead of the default house. This is ignored, if the default house has already been overridden. You can define this property multiple times. Your house and the overridden house must have the same size, see the list of [[NML:List_of_default_house_properties|default house types]].
|-
| building_flags.
| bitmask(HOUSE_FLAG_XXX,...)
|
;HOUSE_FLAG_NOT_SLOPED
:Can only be built on flat terrain. Note that 2x2 buildings will always only be built on flat land, even if this bit isn't set.
;HOUSE_FLAG_ANIMATE
:Enable animation
;HOUSE_FLAG_CHURCH
:House is a church (only 1 will be built per town)
;HOUSE_FLAG_STADIUM
:House is a stadium (only 1 will be built per town)
;HOUSE_FLAG_ONLY_SE
:Can only be built in the scenario editor
;HOUSE_FLAG_PROTECTED
:Will not be removed by the game
;HOUSE_FLAG_SYNC_CALLBACK
:Animation callback <code style="color:darkgreen">anim_control</code> is called at the same time for all tiles.
;HOUSE_FLAG_RANDOM_ANIMATION
:Enable random bits in the <code style="color:darkgreen">anim_next_frame</code>-callback.
|-
| population
| 0 ... 255
| number of inhabitants the building adds to the town, if present
|-
| mail_multiplier
| 0 ... 255
|
|-
| accepted_cargos
| Array with up to 3 [cargo_id, amount]-pairs.
| The cargos that are accepted by each tile of the house. 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 fully accept both PASS and MAIL you could use this: <code style="color:darkgreen"><nowiki>accepted_cargos: [[PASS, 8], [MAIL, 8]];</nowiki></code> Example: for a house tile that doesn't accept any cargos at all you'd use: <code style="color:darkgreen">accepted_cargos: [];</code>
|-
| local_authority_impact
| 0 ... 65525
| amount of happiness decrease of the city council, if the building is destroyed. Town ratings can vary between -1000 (appalling) and +1000 (outstanding).
|-
| removal_cost_multiplier
| 0 ... 255
|
|-
| probability
| 0 ... 16 (float)
| Probability with respect to the default houses (=1). Mind that these are relative probabilities with respect to all houses defined. If all probabilities are defined as 16, they'll all have the same probability as if they had all a probability of 1.
|-
| years_available
| array of two int
| [xx, yy] where xx and yy indicate the introduction year and the last year the building can be built
|-
| minimum_lifetime
| 0 ... 255
| number of years the building will remain at least
|-
| availability_mask
|
[bitmask([[NML:List of town zones|town zones]]), bitmask(CLIMATE_XXX, ...)]
|
An array with two bitmasks, the first bitmask is a mask of town zones where this house is available. The second bitmask is a mask of climates combined with the special value ABOVE_SNOWLINE which you need to set for houses available in the arctic climate above the snowline. Examples:

* Available in the centre town zone in toyland only: <code>[bitmask(TOWNZONE_CENTRE), bitmask(CLIMATE_TOYLAND)]</code>
* Available in all town zones in the arctic climate both above and below the snowline: <code>[ALL_TOWNZONES, bitmask(CLIMATE_ARCTIC, ABOVE_SNOWLINE)]</code>
* Available everywhere except on the town edge: <code>[ALL_TOWNZONES & ~bitmask(TOWNZONE_EDGE), ALL_CLIMATES | bitmask(ABOVE_SNOWLINE)</code>
|-
| callback_flags
| bitmask(HOUSE_CBF_XX)
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| random_colours
| array of 4, each COLOUR_XXX
|
colour values in an array, refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for a list of possible values.
|-
| refresh_multiplier
| 0 ... 63
| Defines the frequency with which the tile will be re-randomized which has an impact for random animation.
|-
| animation_info
| Array [ANIMATION_XXX, frame-count]
|
Type of animation and its length (1...128 frames):

;ANIMATION_LOOPING
;ANIMATION_NON_LOOPING
|-
| animation_speed
| 2 ... 16
|
Speed of animation, see [[NML:Animation speed|animation speed table]] for the meaning of the values.
|-
| building_class
| 0 .. 254
| An arbitrary number. You can check for the presence of buildings of the same class when building new buildings or using animation. Only the north tile of a multi-tile building is assigned a class.
|
|-
| watched_cargo_types
| array of values from your [[NML:Cargotable|cargo table]]
| {{ottdp|1.2|2.6|ottdrev=r23072|ttdprev=r1677}}List of cargo types to watch, to be used with the <code style:darkgreen>watched_cargo_accepted</code> callback.
|}

==House variables==

{| class="t"
! name
! value range
! comment
|-
| construction_state
| 0..3
| Current construction state of the house tile. 0..2 = under construction, 3 = finished.
|-
| pseudo_random_bits
| 0..3
| Some pseudo-random bits, based on the tile position. TTD houses use this to randomize their appearance.
|-
| random_bits
| 0..255
| 8 random bits, also used for [[NML:Random_switch|random switch]]-blocks. Initially these are the same for all tiles of a multi-tile house.
|-
| age
| 0..255
| Age of the house in years, limited to 255
|-
| town_zone
| [[NML:List of town zones|town zone]]
| The town zone of the current tile
|-
| terrain_type
| TILETYPE_XX
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|-
| same_house_count_town
| 0..255
| Number of the houses with the same ID in the same town as this house
|-
| same_house_count_map
| 0..255
| Number of the houses with the same ID on the entire map
|-
| same_class_count_town
| 0..255
| Number of the houses with the same <code style="color:darkgreen">building_class</code> in the same town as this house. The class of the north tile of the use is used for this purpose, as other tiles don't normally have a class.
|-
| same_class_count_map
| 0..255
| Number of the houses with the same <code style="color:darkgreen">building_class</code> on the entire map. The class of the north tile of the use is used for this purpose, as other tiles don't normally have a class.
|-
| generating_town
| [0 <nowiki>|</nowiki> 1]
| 1 a random town is currently being created, 0 otherwise. Note that while generating a random town, [[NML:Towns#Town variables|town variables]] <code style="color:darkgreen">population</code> and <code style="color:darkgreen">building_count</code> are incorrect. The population variable contains the population of buildings generated ''yet'', the final value may be larger. The building_count is surely higher than the final value will be.
|-
| animation_frame
| 0..255
| Current animation frame
|-
| x_coordinate
| 0..2047
| X-coordinate (top right -> bottom left) of the tile on the map
|-
| y_coordinate
| 0..2047
| Y-coordinate (top left -> bottom right) of the tile on the map
|-
| relative_x
| 0..1
| X-coordinate (top right -> bottom left) of the tile relative to the northernmost tile.
|-
| relative_y
| 0..1
| 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 [[NML:Builtin functions|builtin function]] relative_coord(x, y) may be useful when making comparisons.
|-
| house_tile
| HOUSE_TILE_XXX, XXX = <nowiki>[NORTH | EAST | WEST | SOUTH]</nowiki>
| What tile of a multi-tile house this is.
|-
| house_type_id
| 0..255
| Item ID of this house type, that was assigned to the item. See the note above about [[#Multi-tile houses|multi-tile houses]].
|}

The following variables require one or more arguments
{| class="t"
! name
! arguments
! value range
! comment
|-
| old_house_count_town
| ID of old house type (0..109)
| 0..255
| Number of old houses with a given ID in the same town as the current house
|-
| old_house_count_town
| ID of old house type (0..109)
| 0..255
| Number of old houses with a given ID on the whole map
|-
| other_house_count_town
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses with a given ID in the same town as the current house.
|-
| other_house_count_map
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses with a given ID on the whole map
|-
| other_class_count_town
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses, with the same class as the house with the given ID, in the same town as the current house
|-
| other_class_count_map
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses, with the same class as the house with the given ID, on the whole map
|-
| nearby_tile_slope
| x- and y-offset (both signed, range -8..7)
| SLOPE_XXX
| See [[NML:List of tile slopes|tile slopes]] for an overview of possible values
|-
| nearby_tile_is_water
| x- and y-offset (both signed, range -8..7)
| [0 <nowiki>|</nowiki> 1]
| 1 if the tile is water, 0 otherwise
|-
| nearby_tile_terrain_type
| x- and y-offset (both signed, range -8..7)
| TILETYPE_XX
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|-
| nearby_tile_water_class
| x- and y-offset (both signed, range -8..7)
| WATER_CLASS_XXX
| XXX = [NONE <nowiki>|</nowiki> SEA <nowiki>|</nowiki> CANAL <nowiki>|</nowiki> RIVER] Note that tiles for which <code style="color:darkgreen">nearby_tile_is_water</code> is 0 may still have a water class, e.g. industry tiles with water beneath them.
|-
| nearby_tile_height
| x- and y-offset (both signed, range -8..7)
| 0..255 (currently limited to 0..15)
| Height of the lowest corner of the tile. 1 unit is one height level of 8 pixels.
|-
| nearby_tile_class
| x- and y-offset (both signed, range -8..7)
|
[[NML:List of tile classes|Tile class]]
|
|-
| nearby_tile_animation_frame
| x- and y-offset (both signed, range -8..7)
| 0..255
| Animation frame of the given tile
|-
| cargo_accepted_nearby_ever
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby">Cargo type should be from your cargo translation table. X- and y-offset are optional, if provided both must be in range -128..127. A station is considered nearby if the tile is in the station's acceptance area. This is the purpose of the x- and y-offset, as other tiles may have other stations nearby.</ref>
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was ever accepted at a nearby station, 0 otherwise
|-
| cargo_accepted_nearby_last_month
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was accepted at a nearby station in the last month, 0 otherwise
|-
| cargo_accepted_nearby_this_month
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was ever accepted at a nearby station in this month, 0 otherwise
|-
| cargo_accepted_nearby_last_bigtick
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was ever accepted at a nearby station since the last periodic processing, which happens every 250 ticks. 0 otherwise
|-
| cargo_accepted_nearby_watched
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was one of the cargo types that triggered the <code style="color:darkgreen">watched_cargo_accepted</code>-callback (only during this callback), 0 otherwise
|-
| nearest_house_matching_criterion
| radius (1..63) and criterion (SEARCH_HOUSE_BY_XXX, XXX = [<nowiki>ID | CLASS | GRFID</nowiki>])
| 1..63, or 0 if not found
| Perform a circular search for a house matching either the id, <code style="color:darkgreen">building_class</code> or GRFID of this house, depending on the second parameter. The first parameter specifies the maximum search radius. Return value is the Manhattan distance of the closest matching house tile, or 0 if no match was found. Note that tiles of the originating house never match. See also the note above about [[#Multi-tile houses|multi-tile houses]].
|-
| nearby_tile_house_id
| x- and y-offset (both signed, range -8..7)
| -1, or 0 .. 767
| Return value is -1 if the tile is not a house tile, X (0..255) if the tile contains old house type X, 256+X if the tile contains a house from this NewGRF with ID X, 512+X if the tile contains a house from a different NewGRF with ID X. See the note above about [[#Multi-tile houses|multi-tile houses]].
|-
| nearby_tile_house_class
| x- and y-offset (both signed, range -8..7)
| -1, 0, or 256 .. 767
| Return value is -1 if the tile is not a house tile, 0 if the house tile does not have a class (this includes all old house types), 256+X (X = 0..255) if the house has been defined by this NewGRF with <code style="color:darkgreen">building_class</code> X or 512+X if the house has been defined by a different NewGRF with <code style="color:darkgreen">building_class</code> X. Note that for a multi-tile house, generally only the north tile has a sensible class value.
|-
| nearby_tile_house_grfid
| x- and y-offset (both signed, range -8..7)
| -1, 0 or a GRFID
| Return value is -1 if the tile is not a house tile, 0 if the house tile contains an old house type, or else the GRFID of the NewGRF defining the house.
|}
<references/>

==House callbacks==
Unless noted otherwise, callbacks may be called for any of the tiles of a multi-tile house.

{| class="t"
! callback
! return value
! comment
|-
| default
| Sprite layout
| Graphics for the house tile
|-
| graphics_xxx, xxx = <nowiki>[north | east | south | west]</nowiki>
| Sprite layout
| Tile-specific graphics for one of the tiles of a multi-tile house. Of course, this is callback is called for that tile only.
|-
| random_trigger
| N/A
|
See [[NML:Random switch|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. <code>extra_callback_info1</code> contains 32 random bits, if enabled in the <code>building_flags</code> property. Returning a sound effect in the high byte will cause that sound effect to be played.
|-
| anim_control
| Next animation frame or CB_RESULT_XXX
| Called every 256 ticks. 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. <code>extra_callback_info1</code> contains 32 random bits. The low 16 bits are always different for each house tile, but the high 16 bits are the same for each tile if synchronized animation is enabled in the <code>building_flags</code>-property. Returning a sound effect in the high byte will cause that sound effect to be played.
|-
| construction_anim
| Same as <code>anim_control</code>
| Works the same as the <code>anim_control</code> callback, except that it's called when the construction state changes.
|-
| watched_cargo_accepted
| Same as <code>anim_control</code>
| Works the same as the <code>anim_control</code> callback, except that it's called when one of the watched cargo types is accepted.
|-
| 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 <code>accepted_cargo</code> 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 the acceptance properties are used instead. Cargo types are from the <code>cargo_type_accept</code> callback, or the <code>accepted_cargo</code> 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.
|-
| cargo_production
| (cargo_type * 256) + amount
| Called every 256 ticks. Called multiple times until 0x20FF is returned. The high byte of the result contains a cargo type, the low byte contains the amount of that cargo to produce. <code>extra_callback_info1</code> contains the number of iterations so far, <code>extra_callback_info2</code> contains random bits.
|-
| 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.
|-
| name
| String
| Name of the building (when using tile query tool)
|-
| colour
| Palette number
|
Used to recolour the building. See here [[NML:List of default colour translation palettes|here]] for an overview of default palettes.
|-
| construction_check
| 0 or 1
| Return 1 to allow building the house or 0 to disallow. Called only for the north tile.
|-
| destruction
| 0 or 1
| Called periodically. Return 0 to keep the building or 1 to destroy it. Called only for the north tile.
|-
| protection
| 0 or 1
| Return 0 to allow destruction, or 1 to disallow
|}

NML:Houses

2012-09-03T20:13:56Z

Hirundo: /* House variables */ Add notes about multi-tile houses

{{NMLNavPropVarCB}}
==House IDs==
House 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 house. The value of this property should be the ID of a [[NML:List_of_default_house_properties|default house type]], which will be used instead of your item if it is not available for whatever reason (for example, missing NewGRF).

Although the majority of all original houses occupy a single tile, it is possible to define a larger house of up to 2x2 tiles. For this, you should set the fourth 'size' parameter in the item-block. Valid values are HOUSE_SIZE_XXX, XXX = <nowiki>[1X1 | 1X2 | 2X1 | 2X2]</nowiki>. This size should match the size of the substitute house type.

===Multi-tile houses===
Internally, due to the way NewGRF houses work, a multi-tile house will occupy more than one item ID. If you assign item ID X to a house, item IDs X+1 (for a 2-tile house) and (X+1) .. (X+3) (for a 4-tile house) will also be used. Normally you don't have to care about this, but there are two exceptions:
* If you manually assign numeric ids to your houses. You are recommended to just set all ids to -1 and let NML figure it out for you.
* When working with several variables that work with house type IDs. Keep in mind that tiles of a multi-tile house may have IDs X .. X + N - 1, with X being the assigned id and N the number of house tiles.

==House properties==

{| class="t"
! property
! value range
! comment
|-
| name
| string
| for example string(STR_NAME_EIFFEL_TOWER)
|-
| substitute
| 0 ... 109
| Number of the default house that replaces this one, if this house 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, except for the church / stadium flags (see below). The old house must have the same size as the new house, see the list of [[NML:List_of_default_house_properties|default house types]] for a list of possible substitute IDs.
|-
| override
| 0 ... 109
| id of the default house which this house replaces. This will cause your house to be placed instead of the default house. This is ignored, if the default house has already been overridden. You can define this property multiple times. Your house and the overridden house must have the same size, see the list of [[NML:List_of_default_house_properties|default house types]].
|-
| building_flags.
| bitmask(HOUSE_FLAG_XXX,...)
|
;HOUSE_FLAG_NOT_SLOPED
:Can only be built on flat terrain. Note that 2x2 buildings will always only be built on flat land, even if this bit isn't set.
;HOUSE_FLAG_ANIMATE
:Enable animation
;HOUSE_FLAG_CHURCH
:House is a church (only 1 will be built per town)
;HOUSE_FLAG_STADIUM
:House is a stadium (only 1 will be built per town)
;HOUSE_FLAG_ONLY_SE
:Can only be built in the scenario editor
;HOUSE_FLAG_PROTECTED
:Will not be removed by the game
;HOUSE_FLAG_SYNC_CALLBACK
:Animation callback <code style="color:darkgreen">anim_control</code> is called at the same time for all tiles.
;HOUSE_FLAG_RANDOM_ANIMATION
:Enable random bits in the <code style="color:darkgreen">anim_next_frame</code>-callback.
|-
| population
| 0 ... 255
| number of inhabitants the building adds to the town, if present
|-
| mail_multiplier
| 0 ... 255
|
|-
| accepted_cargos
| Array with up to 3 [cargo_id, amount]-pairs.
| The cargos that are accepted by each tile of the house. 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 fully accept both PASS and MAIL you could use this: <code style="color:darkgreen"><nowiki>accepted_cargos: [[PASS, 8], [MAIL, 8]];</nowiki></code> Example: for a house tile that doesn't accept any cargos at all you'd use: <code style="color:darkgreen">accepted_cargos: [];</code>
|-
| local_authority_impact
| 0 ... 65525
| amount of happiness decrease of the city council, if the building is destroyed. Town ratings can vary between -1000 (appalling) and +1000 (outstanding).
|-
| removal_cost_multiplier
| 0 ... 255
|
|-
| probability
| 0 ... 16 (float)
| Probability with respect to the default houses (=1). Mind that these are relative probabilities with respect to all houses defined. If all probabilities are defined as 16, they'll all have the same probability as if they had all a probability of 1.
|-
| years_available
| array of two int
| [xx, yy] where xx and yy indicate the introduction year and the last year the building can be built
|-
| minimum_lifetime
| 0 ... 255
| number of years the building will remain at least
|-
| availability_mask
|
[bitmask([[NML:List of town zones|town zones]]), bitmask(CLIMATE_XXX, ...)]
|
An array with two bitmasks, the first bitmask is a mask of town zones where this house is available. The second bitmask is a mask of climates combined with the special value ABOVE_SNOWLINE which you need to set for houses available in the arctic climate above the snowline. Examples:

* Available in the centre town zone in toyland only: <code>[bitmask(TOWNZONE_CENTRE), bitmask(CLIMATE_TOYLAND)]</code>
* Available in all town zones in the arctic climate both above and below the snowline: <code>[ALL_TOWNZONES, bitmask(CLIMATE_ARCTIC, ABOVE_SNOWLINE)]</code>
* Available everywhere except on the town edge: <code>[ALL_TOWNZONES & ~bitmask(TOWNZONE_EDGE), ALL_CLIMATES | bitmask(ABOVE_SNOWLINE)</code>
|-
| callback_flags
| bitmask(HOUSE_CBF_XX)
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| random_colours
| array of 4, each COLOUR_XXX
|
colour values in an array, refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for a list of possible values.
|-
| refresh_multiplier
| 0 ... 63
| Defines the frequency with which the tile will be re-randomized which has an impact for random animation.
|-
| animation_info
| Array [ANIMATION_XXX, frame-count]
|
Type of animation and its length (1...128 frames):

;ANIMATION_LOOPING
;ANIMATION_NON_LOOPING
|-
| animation_speed
| 2 ... 16
|
Speed of animation, see [[NML:Animation speed|animation speed table]] for the meaning of the values.
|-
| building_class
| 0 .. 254
| An arbitrary number. You can check for the presence of buildings of the same class when building new buildings or using animation. Only the north tile of a multi-tile building is assigned a class.
|
|-
| watched_cargo_types
| array of values from your [[NML:Cargotable|cargo table]]
| {{ottdp|1.2|2.6|ottdrev=r23072|ttdprev=r1677}}List of cargo types to watch, to be used with the <code style:darkgreen>watched_cargo_accepted</code> callback.
|}

==House variables==

{| class="t"
! name
! value range
! comment
|-
| construction_state
| 0..3
| Current construction state of the house tile. 0..2 = under construction, 3 = finished.
|-
| pseudo_random_bits
| 0..3
| Some pseudo-random bits, based on the tile position. TTD houses use this to randomize their appearance.
|-
| age
| 0..255
| Age of the house in years, limited to 255
|-
| town_zone
|
[[NML:List of town zones|town zone]]
| The town zone of the current tile
|-
| terrain_type
| TILETYPE_XX
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|-
| same_house_count_town
| 0..255
| Number of the houses with the same ID in the same town as this house
|-
| same_house_count_map
| 0..255
| Number of the houses with the same ID on the entire map
|-
| same_class_count_town
| 0..255
| Number of the houses with the same <code style="color:darkgreen">building_class</code> in the same town as this house. The class of the north tile of the use is used for this purpose, as other tiles don't normally have a class.
|-
| same_class_count_map
| 0..255
| Number of the houses with the same <code style="color:darkgreen">building_class</code> on the entire map. The class of the north tile of the use is used for this purpose, as other tiles don't normally have a class.
|-
| generating_town
| [0 <nowiki>|</nowiki> 1]
| 1 a random town is currently being created, 0 otherwise. Note that while generating a random town, [[NML:Towns#Town variables|town variables]] <code style="color:darkgreen">population</code> and <code style="color:darkgreen">building_count</code> are incorrect. The population variable contains the population of buildings generated ''yet'', the final value may be larger. The building_count is surely higher than the final value will be.
|-
| animation_frame
| 0..255
| Current animation frame
|-
| x_coordinate
| 0..2047
| X-coordinate (top right -> bottom left) of the tile on the map
|-
| y_coordinate
| 0..2047
| Y-coordinate (top left -> bottom right) of the tile on the map
|-
| relative_x
| 0..1
| X-coordinate (top right -> bottom left) of the tile relative to the northernmost tile.
|-
| relative_y
| 0..1
| 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 [[NML:Builtin functions|builtin function]] relative_coord(x, y) may be useful when making comparisons.
|-
| house_tile
| HOUSE_TILE_XXX, XXX = <nowiki>[NORTH | EAST | WEST | SOUTH]</nowiki>
| What tile of a multi-tile house this is.
|-
| house_type_id
| 0..255
| Item ID of this house type, that was assigned to the item. See the note above about [[#Multi-tile houses|multi-tile houses]].
|}

The following variables require one or more arguments
{| class="t"
! name
! arguments
! value range
! comment
|-
| old_house_count_town
| ID of old house type (0..109)
| 0..255
| Number of old houses with a given ID in the same town as the current house
|-
| old_house_count_town
| ID of old house type (0..109)
| 0..255
| Number of old houses with a given ID on the whole map
|-
| other_house_count_town
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses with a given ID in the same town as the current house.
|-
| other_house_count_map
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses with a given ID on the whole map
|-
| other_class_count_town
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses, with the same class as the house with the given ID, in the same town as the current house
|-
| other_class_count_map
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses, with the same class as the house with the given ID, on the whole map
|-
| nearby_tile_slope
| x- and y-offset (both signed, range -8..7)
| SLOPE_XXX
| See [[NML:List of tile slopes|tile slopes]] for an overview of possible values
|-
| nearby_tile_is_water
| x- and y-offset (both signed, range -8..7)
| [0 <nowiki>|</nowiki> 1]
| 1 if the tile is water, 0 otherwise
|-
| nearby_tile_terrain_type
| x- and y-offset (both signed, range -8..7)
| TILETYPE_XX
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|-
| nearby_tile_water_class
| x- and y-offset (both signed, range -8..7)
| WATER_CLASS_XXX
| XXX = [NONE <nowiki>|</nowiki> SEA <nowiki>|</nowiki> CANAL <nowiki>|</nowiki> RIVER] Note that tiles for which <code style="color:darkgreen">nearby_tile_is_water</code> is 0 may still have a water class, e.g. industry tiles with water beneath them.
|-
| nearby_tile_height
| x- and y-offset (both signed, range -8..7)
| 0..255 (currently limited to 0..15)
| Height of the lowest corner of the tile. 1 unit is one height level of 8 pixels.
|-
| nearby_tile_class
| x- and y-offset (both signed, range -8..7)
|
[[NML:List of tile classes|Tile class]]
|
|-
| nearby_tile_animation_frame
| x- and y-offset (both signed, range -8..7)
| 0..255
| Animation frame of the given tile
|-
| cargo_accepted_nearby_ever
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby">Cargo type should be from your cargo translation table. X- and y-offset are optional, if provided both must be in range -128..127. A station is considered nearby if the tile is in the station's acceptance area. This is the purpose of the x- and y-offset, as other tiles may have other stations nearby.</ref>
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was ever accepted at a nearby station, 0 otherwise
|-
| cargo_accepted_nearby_last_month
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was accepted at a nearby station in the last month, 0 otherwise
|-
| cargo_accepted_nearby_this_month
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was ever accepted at a nearby station in this month, 0 otherwise
|-
| cargo_accepted_nearby_last_bigtick
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was ever accepted at a nearby station since the last periodic processing, which happens every 250 ticks. 0 otherwise
|-
| cargo_accepted_nearby_watched
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was one of the cargo types that triggered the <code style="color:darkgreen">watched_cargo_accepted</code>-callback (only during this callback), 0 otherwise
|-
| nearest_house_matching_criterion
| radius (1..63) and criterion (SEARCH_HOUSE_BY_XXX, XXX = [<nowiki>ID | CLASS | GRFID</nowiki>])
| 1..63, or 0 if not found
| Perform a circular search for a house matching either the id, <code style="color:darkgreen">building_class</code> or GRFID of this house, depending on the second parameter. The first parameter specifies the maximum search radius. Return value is the Manhattan distance of the closest matching house tile, or 0 if no match was found. Note that tiles of the originating house never match. See also the note above about [[#Multi-tile houses|multi-tile houses]].
|-
| nearby_tile_house_id
| x- and y-offset (both signed, range -8..7)
| -1, or 0 .. 767
| Return value is -1 if the tile is not a house tile, X (0..255) if the tile contains old house type X, 256+X if the tile contains a house from this NewGRF with ID X, 512+X if the tile contains a house from a different NewGRF with ID X. See the note above about [[#Multi-tile houses|multi-tile houses]].
|-
| nearby_tile_house_class
| x- and y-offset (both signed, range -8..7)
| -1, 0, or 256 .. 767
| Return value is -1 if the tile is not a house tile, 0 if the house tile does not have a class (this includes all old house types), 256+X (X = 0..255) if the house has been defined by this NewGRF with <code style="color:darkgreen">building_class</code> X or 512+X if the house has been defined by a different NewGRF with <code style="color:darkgreen">building_class</code> X. Note that for a multi-tile house, generally only the north tile has a sensible class value.
|-
| nearby_tile_house_grfid
| x- and y-offset (both signed, range -8..7)
| -1, 0 or a GRFID
| Return value is -1 if the tile is not a house tile, 0 if the house tile contains an old house type, or else the GRFID of the NewGRF defining the house.
|}
<references/>

==House callbacks==
Unless noted otherwise, callbacks may be called for any of the tiles of a multi-tile house.

{| class="t"
! callback
! return value
! comment
|-
| default
| Sprite layout
| Graphics for the house tile
|-
| graphics_xxx, xxx = <nowiki>[north | east | south | west]</nowiki>
| Sprite layout
| Tile-specific graphics for one of the tiles of a multi-tile house. Of course, this is callback is called for that tile only.
|-
| random_trigger
| N/A
|
See [[NML:Random switch|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. <code>extra_callback_info1</code> contains 32 random bits, if enabled in the <code>building_flags</code> property. Returning a sound effect in the high byte will cause that sound effect to be played.
|-
| anim_control
| Next animation frame or CB_RESULT_XXX
| Called every 256 ticks. 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. <code>extra_callback_info1</code> contains 32 random bits. The low 16 bits are always different for each house tile, but the high 16 bits are the same for each tile if synchronized animation is enabled in the <code>building_flags</code>-property. Returning a sound effect in the high byte will cause that sound effect to be played.
|-
| construction_anim
| Same as <code>anim_control</code>
| Works the same as the <code>anim_control</code> callback, except that it's called when the construction state changes.
|-
| watched_cargo_accepted
| Same as <code>anim_control</code>
| Works the same as the <code>anim_control</code> callback, except that it's called when one of the watched cargo types is accepted.
|-
| 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 <code>accepted_cargo</code> 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 the acceptance properties are used instead. Cargo types are from the <code>cargo_type_accept</code> callback, or the <code>accepted_cargo</code> 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.
|-
| cargo_production
| (cargo_type * 256) + amount
| Called every 256 ticks. Called multiple times until 0x20FF is returned. The high byte of the result contains a cargo type, the low byte contains the amount of that cargo to produce. <code>extra_callback_info1</code> contains the number of iterations so far, <code>extra_callback_info2</code> contains random bits.
|-
| 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.
|-
| name
| String
| Name of the building (when using tile query tool)
|-
| colour
| Palette number
|
Used to recolour the building. See here [[NML:List of default colour translation palettes|here]] for an overview of default palettes.
|-
| construction_check
| 0 or 1
| Return 1 to allow building the house or 0 to disallow. Called only for the north tile.
|-
| destruction
| 0 or 1
| Called periodically. Return 0 to keep the building or 1 to destroy it. Called only for the north tile.
|-
| protection
| 0 or 1
| Return 0 to allow destruction, or 1 to disallow
|}

NML:Houses

2012-09-03T20:09:14Z

Hirundo: /* Multi-tile houses */ Fix indentation

{{NMLNavPropVarCB}}
==House IDs==
House 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 house. The value of this property should be the ID of a [[NML:List_of_default_house_properties|default house type]], which will be used instead of your item if it is not available for whatever reason (for example, missing NewGRF).

Although the majority of all original houses occupy a single tile, it is possible to define a larger house of up to 2x2 tiles. For this, you should set the fourth 'size' parameter in the item-block. Valid values are HOUSE_SIZE_XXX, XXX = <nowiki>[1X1 | 1X2 | 2X1 | 2X2]</nowiki>. This size should match the size of the substitute house type.

===Multi-tile houses===
Internally, due to the way NewGRF houses work, a multi-tile house will occupy more than one item ID. If you assign item ID X to a house, item IDs X+1 (for a 2-tile house) and (X+1) .. (X+3) (for a 4-tile house) will also be used. Normally you don't have to care about this, but there are two exceptions:
* If you manually assign numeric ids to your houses. You are recommended to just set all ids to -1 and let NML figure it out for you.
* When working with several variables that work with house type IDs. Keep in mind that tiles of a multi-tile house may have IDs X .. X + N - 1, with X being the assigned id and N the number of house tiles.

==House properties==

{| class="t"
! property
! value range
! comment
|-
| name
| string
| for example string(STR_NAME_EIFFEL_TOWER)
|-
| substitute
| 0 ... 109
| Number of the default house that replaces this one, if this house 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, except for the church / stadium flags (see below). The old house must have the same size as the new house, see the list of [[NML:List_of_default_house_properties|default house types]] for a list of possible substitute IDs.
|-
| override
| 0 ... 109
| id of the default house which this house replaces. This will cause your house to be placed instead of the default house. This is ignored, if the default house has already been overridden. You can define this property multiple times. Your house and the overridden house must have the same size, see the list of [[NML:List_of_default_house_properties|default house types]].
|-
| building_flags.
| bitmask(HOUSE_FLAG_XXX,...)
|
;HOUSE_FLAG_NOT_SLOPED
:Can only be built on flat terrain. Note that 2x2 buildings will always only be built on flat land, even if this bit isn't set.
;HOUSE_FLAG_ANIMATE
:Enable animation
;HOUSE_FLAG_CHURCH
:House is a church (only 1 will be built per town)
;HOUSE_FLAG_STADIUM
:House is a stadium (only 1 will be built per town)
;HOUSE_FLAG_ONLY_SE
:Can only be built in the scenario editor
;HOUSE_FLAG_PROTECTED
:Will not be removed by the game
;HOUSE_FLAG_SYNC_CALLBACK
:Animation callback <code style="color:darkgreen">anim_control</code> is called at the same time for all tiles.
;HOUSE_FLAG_RANDOM_ANIMATION
:Enable random bits in the <code style="color:darkgreen">anim_next_frame</code>-callback.
|-
| population
| 0 ... 255
| number of inhabitants the building adds to the town, if present
|-
| mail_multiplier
| 0 ... 255
|
|-
| accepted_cargos
| Array with up to 3 [cargo_id, amount]-pairs.
| The cargos that are accepted by each tile of the house. 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 fully accept both PASS and MAIL you could use this: <code style="color:darkgreen"><nowiki>accepted_cargos: [[PASS, 8], [MAIL, 8]];</nowiki></code> Example: for a house tile that doesn't accept any cargos at all you'd use: <code style="color:darkgreen">accepted_cargos: [];</code>
|-
| local_authority_impact
| 0 ... 65525
| amount of happiness decrease of the city council, if the building is destroyed. Town ratings can vary between -1000 (appalling) and +1000 (outstanding).
|-
| removal_cost_multiplier
| 0 ... 255
|
|-
| probability
| 0 ... 16 (float)
| Probability with respect to the default houses (=1). Mind that these are relative probabilities with respect to all houses defined. If all probabilities are defined as 16, they'll all have the same probability as if they had all a probability of 1.
|-
| years_available
| array of two int
| [xx, yy] where xx and yy indicate the introduction year and the last year the building can be built
|-
| minimum_lifetime
| 0 ... 255
| number of years the building will remain at least
|-
| availability_mask
|
[bitmask([[NML:List of town zones|town zones]]), bitmask(CLIMATE_XXX, ...)]
|
An array with two bitmasks, the first bitmask is a mask of town zones where this house is available. The second bitmask is a mask of climates combined with the special value ABOVE_SNOWLINE which you need to set for houses available in the arctic climate above the snowline. Examples:

* Available in the centre town zone in toyland only: <code>[bitmask(TOWNZONE_CENTRE), bitmask(CLIMATE_TOYLAND)]</code>
* Available in all town zones in the arctic climate both above and below the snowline: <code>[ALL_TOWNZONES, bitmask(CLIMATE_ARCTIC, ABOVE_SNOWLINE)]</code>
* Available everywhere except on the town edge: <code>[ALL_TOWNZONES & ~bitmask(TOWNZONE_EDGE), ALL_CLIMATES | bitmask(ABOVE_SNOWLINE)</code>
|-
| callback_flags
| bitmask(HOUSE_CBF_XX)
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| random_colours
| array of 4, each COLOUR_XXX
|
colour values in an array, refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for a list of possible values.
|-
| refresh_multiplier
| 0 ... 63
| Defines the frequency with which the tile will be re-randomized which has an impact for random animation.
|-
| animation_info
| Array [ANIMATION_XXX, frame-count]
|
Type of animation and its length (1...128 frames):

;ANIMATION_LOOPING
;ANIMATION_NON_LOOPING
|-
| animation_speed
| 2 ... 16
|
Speed of animation, see [[NML:Animation speed|animation speed table]] for the meaning of the values.
|-
| building_class
| 0 .. 254
| An arbitrary number. You can check for the presence of buildings of the same class when building new buildings or using animation. Only the north tile of a multi-tile building is assigned a class.
|
|-
| watched_cargo_types
| array of values from your [[NML:Cargotable|cargo table]]
| {{ottdp|1.2|2.6|ottdrev=r23072|ttdprev=r1677}}List of cargo types to watch, to be used with the <code style:darkgreen>watched_cargo_accepted</code> callback.
|}

==House variables==

{| class="t"
! name
! value range
! comment
|-
| construction_state
| 0..3
| Current construction state of the house tile. 0..2 = under construction, 3 = finished.
|-
| pseudo_random_bits
| 0..3
| Some pseudo-random bits, based on the tile position. TTD houses use this to randomize their appearance.
|-
| age
| 0..255
| Age of the house in years, limited to 255
|-
| town_zone
|
[[NML:List of town zones|town zone]]
| The town zone of the current tile
|-
| terrain_type
| TILETYPE_XX
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|-
| same_house_count_town
| 0..255
| Number of the houses with the same ID in the same town as this house
|-
| same_house_count_map
| 0..255
| Number of the houses with the same ID on the entire map
|-
| same_class_count_town
| 0..255
| Number of the houses with the same <code style="color:darkgreen">building_class</code> in the same town as this house. The class of the north tile of the use is used for this purpose, as other tiles don't normally have a class.
|-
| same_class_count_map
| 0..255
| Number of the houses with the same <code style="color:darkgreen">building_class</code> on the entire map. The class of the north tile of the use is used for this purpose, as other tiles don't normally have a class.
|-
| generating_town
| [0 <nowiki>|</nowiki> 1]
| 1 a random town is currently being created, 0 otherwise. Note that while generating a random town, [[NML:Towns#Town variables|town variables]] <code style="color:darkgreen">population</code> and <code style="color:darkgreen">building_count</code> are incorrect. The population variable contains the population of buildings generated ''yet'', the final value may be larger. The building_count is surely higher than the final value will be.
|-
| animation_frame
| 0..255
| Current animation frame
|-
| x_coordinate
| 0..2047
| X-coordinate (top right -> bottom left) of the tile on the map
|-
| y_coordinate
| 0..2047
| Y-coordinate (top left -> bottom right) of the tile on the map
|-
| relative_x
| 0..1
| X-coordinate (top right -> bottom left) of the tile relative to the northernmost tile.
|-
| relative_y
| 0..1
| 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 [[NML:Builtin functions|builtin function]] relative_coord(x, y) may be useful when making comparisons.
|-
| house_tile
| HOUSE_TILE_XXX, XXX = <nowiki>[NORTH | EAST | WEST | SOUTH]</nowiki>
| What tile of a multi-tile house this is.
|-
| house_type_id
| 0..255
| Item ID of this house type, of the north tile.
|}

The following variables require one or more arguments
{| class="t"
! name
! arguments
! value range
! comment
|-
| old_house_count_town
| ID of old house type (0..109)
| 0..255
| Number of old houses with a given ID in the same town as the current house
|-
| old_house_count_town
| ID of old house type (0..109)
| 0..255
| Number of old houses with a given ID on the whole map
|-
| other_house_count_town
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses with a given ID in the same town as the current house
|-
| other_house_count_map
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses with a given ID on the whole map
|-
| other_class_count_town
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses, with the same class as the house with the given ID, in the same town as the current house
|-
| other_class_count_map
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses, with the same class as the house with the given ID, on the whole map
|-
| nearby_tile_slope
| x- and y-offset (both signed, range -8..7)
| SLOPE_XXX
| See [[NML:List of tile slopes|tile slopes]] for an overview of possible values
|-
| nearby_tile_is_water
| x- and y-offset (both signed, range -8..7)
| [0 <nowiki>|</nowiki> 1]
| 1 if the tile is water, 0 otherwise
|-
| nearby_tile_terrain_type
| x- and y-offset (both signed, range -8..7)
| TILETYPE_XX
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|-
| nearby_tile_water_class
| x- and y-offset (both signed, range -8..7)
| WATER_CLASS_XXX
| XXX = [NONE <nowiki>|</nowiki> SEA <nowiki>|</nowiki> CANAL <nowiki>|</nowiki> RIVER] Note that tiles for which <code style="color:darkgreen">nearby_tile_is_water</code> is 0 may still have a water class, e.g. industry tiles with water beneath them.
|-
| nearby_tile_height
| x- and y-offset (both signed, range -8..7)
| 0..255 (currently limited to 0..15)
| Height of the lowest corner of the tile. 1 unit is one height level of 8 pixels.
|-
| nearby_tile_class
| x- and y-offset (both signed, range -8..7)
|
[[NML:List of tile classes|Tile class]]
|
|-
| nearby_tile_animation_frame
| x- and y-offset (both signed, range -8..7)
| 0..255
| Animation frame of the given tile
|-
| cargo_accepted_nearby_ever
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby">Cargo type should be from your cargo translation table. X- and y-offset are optional, if provided both must be in range -128..127. A station is considered nearby if the tile is in the station's acceptance area. This is the purpose of the x- and y-offset, as other tiles may have other stations nearby.</ref>
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was ever accepted at a nearby station, 0 otherwise
|-
| cargo_accepted_nearby_last_month
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was accepted at a nearby station in the last month, 0 otherwise
|-
| cargo_accepted_nearby_this_month
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was ever accepted at a nearby station in this month, 0 otherwise
|-
| cargo_accepted_nearby_last_bigtick
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was ever accepted at a nearby station since the last periodic processing, which happens every 250 ticks. 0 otherwise
|-
| cargo_accepted_nearby_watched
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was one of the cargo types that triggered the <code style="color:darkgreen">watched_cargo_accepted</code>-callback (only during this callback), 0 otherwise
|-
| nearest_house_matching_criterion
| radius (1..63) and criterion (SEARCH_HOUSE_BY_XXX, XXX = [<nowiki>ID | CLASS | GRFID</nowiki>])
| 1..63, or 0 if not found
| Perform a circular search for a house matching either the id, <code style="color:darkgreen">building_class</code> or GRFID of this house, depending on the second parameter. The first parameter specifies the maximum search radius. Return value is the Manhattan distance of the closest matching house tile, or 0 if no match was found. Note that tiles of the originating house never match.
|-
| nearby_tile_house_id
| x- and y-offset (both signed, range -8..7)
| -1, or 0 .. 767
| Return value is -1 if the tile is not a house tile, X (0..255) if the tile contains old house type X, 256+X if the tile contains a house from this NewGRF with ID X, 512+X if the tile contains a house from a different NewGRF with ID X.
|-
| nearby_tile_house_class
| x- and y-offset (both signed, range -8..7)
| -1, 0, or 256 .. 767
| Return value is -1 if the tile is not a house tile, 0 if the house tile does not have a class (this includes all old house types), 256+X (X = 0..255) if the house has been defined by this NewGRF with <code style="color:darkgreen">building_class</code> X or 512+X if the house has been defined by a different NewGRF with <code style="color:darkgreen">building_class</code> X.
|-
| nearby_tile_house_grfid
| x- and y-offset (both signed, range -8..7)
| -1, 0 or a GRFID
| Return value is -1 if the tile is not a house tile, 0 if the house tile contains an old house type, or else the GRFID of the NewGRF defining the house.
|}
<references/>

==House callbacks==
Unless noted otherwise, callbacks may be called for any of the tiles of a multi-tile house.

{| class="t"
! callback
! return value
! comment
|-
| default
| Sprite layout
| Graphics for the house tile
|-
| graphics_xxx, xxx = <nowiki>[north | east | south | west]</nowiki>
| Sprite layout
| Tile-specific graphics for one of the tiles of a multi-tile house. Of course, this is callback is called for that tile only.
|-
| random_trigger
| N/A
|
See [[NML:Random switch|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. <code>extra_callback_info1</code> contains 32 random bits, if enabled in the <code>building_flags</code> property. Returning a sound effect in the high byte will cause that sound effect to be played.
|-
| anim_control
| Next animation frame or CB_RESULT_XXX
| Called every 256 ticks. 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. <code>extra_callback_info1</code> contains 32 random bits. The low 16 bits are always different for each house tile, but the high 16 bits are the same for each tile if synchronized animation is enabled in the <code>building_flags</code>-property. Returning a sound effect in the high byte will cause that sound effect to be played.
|-
| construction_anim
| Same as <code>anim_control</code>
| Works the same as the <code>anim_control</code> callback, except that it's called when the construction state changes.
|-
| watched_cargo_accepted
| Same as <code>anim_control</code>
| Works the same as the <code>anim_control</code> callback, except that it's called when one of the watched cargo types is accepted.
|-
| 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 <code>accepted_cargo</code> 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 the acceptance properties are used instead. Cargo types are from the <code>cargo_type_accept</code> callback, or the <code>accepted_cargo</code> 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.
|-
| cargo_production
| (cargo_type * 256) + amount
| Called every 256 ticks. Called multiple times until 0x20FF is returned. The high byte of the result contains a cargo type, the low byte contains the amount of that cargo to produce. <code>extra_callback_info1</code> contains the number of iterations so far, <code>extra_callback_info2</code> contains random bits.
|-
| 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.
|-
| name
| String
| Name of the building (when using tile query tool)
|-
| colour
| Palette number
|
Used to recolour the building. See here [[NML:List of default colour translation palettes|here]] for an overview of default palettes.
|-
| construction_check
| 0 or 1
| Return 1 to allow building the house or 0 to disallow. Called only for the north tile.
|-
| destruction
| 0 or 1
| Called periodically. Return 0 to keep the building or 1 to destroy it. Called only for the north tile.
|-
| protection
| 0 or 1
| Return 0 to allow destruction, or 1 to disallow
|}

NML:Houses

2012-09-03T20:08:52Z

Hirundo: Add section about house IDs

{{NMLNavPropVarCB}}
==House IDs==
House 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 house. The value of this property should be the ID of a [[NML:List_of_default_house_properties|default house type]], which will be used instead of your item if it is not available for whatever reason (for example, missing NewGRF).

Although the majority of all original houses occupy a single tile, it is possible to define a larger house of up to 2x2 tiles. For this, you should set the fourth 'size' parameter in the item-block. Valid values are HOUSE_SIZE_XXX, XXX = <nowiki>[1X1 | 1X2 | 2X1 | 2X2]</nowiki>. This size should match the size of the substitute house type.

===Multi-tile houses===
Internally, due to the way NewGRF houses work, a multi-tile house will occupy more than one item ID. If you assign item ID X to a house, item IDs X+1 (for a 2-tile house) and (X+1) .. (X+3) (for a 4-tile house) will also be used. Normally you don't have to care about this, but there are two exceptions:
* If you manually assign numeric ids to your houses. You are recommended to just set all ids to -1 and let NML figure it out for you.
* When working with several variables that work with house type IDs. Keep in mind that tiles of a multi-tile house may have IDs X .. X + N - 1, with X being the assigned id and N the number of house tiles.
==House properties==

{| class="t"
! property
! value range
! comment
|-
| name
| string
| for example string(STR_NAME_EIFFEL_TOWER)
|-
| substitute
| 0 ... 109
| Number of the default house that replaces this one, if this house 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, except for the church / stadium flags (see below). The old house must have the same size as the new house, see the list of [[NML:List_of_default_house_properties|default house types]] for a list of possible substitute IDs.
|-
| override
| 0 ... 109
| id of the default house which this house replaces. This will cause your house to be placed instead of the default house. This is ignored, if the default house has already been overridden. You can define this property multiple times. Your house and the overridden house must have the same size, see the list of [[NML:List_of_default_house_properties|default house types]].
|-
| building_flags.
| bitmask(HOUSE_FLAG_XXX,...)
|
;HOUSE_FLAG_NOT_SLOPED
:Can only be built on flat terrain. Note that 2x2 buildings will always only be built on flat land, even if this bit isn't set.
;HOUSE_FLAG_ANIMATE
:Enable animation
;HOUSE_FLAG_CHURCH
:House is a church (only 1 will be built per town)
;HOUSE_FLAG_STADIUM
:House is a stadium (only 1 will be built per town)
;HOUSE_FLAG_ONLY_SE
:Can only be built in the scenario editor
;HOUSE_FLAG_PROTECTED
:Will not be removed by the game
;HOUSE_FLAG_SYNC_CALLBACK
:Animation callback <code style="color:darkgreen">anim_control</code> is called at the same time for all tiles.
;HOUSE_FLAG_RANDOM_ANIMATION
:Enable random bits in the <code style="color:darkgreen">anim_next_frame</code>-callback.
|-
| population
| 0 ... 255
| number of inhabitants the building adds to the town, if present
|-
| mail_multiplier
| 0 ... 255
|
|-
| accepted_cargos
| Array with up to 3 [cargo_id, amount]-pairs.
| The cargos that are accepted by each tile of the house. 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 fully accept both PASS and MAIL you could use this: <code style="color:darkgreen"><nowiki>accepted_cargos: [[PASS, 8], [MAIL, 8]];</nowiki></code> Example: for a house tile that doesn't accept any cargos at all you'd use: <code style="color:darkgreen">accepted_cargos: [];</code>
|-
| local_authority_impact
| 0 ... 65525
| amount of happiness decrease of the city council, if the building is destroyed. Town ratings can vary between -1000 (appalling) and +1000 (outstanding).
|-
| removal_cost_multiplier
| 0 ... 255
|
|-
| probability
| 0 ... 16 (float)
| Probability with respect to the default houses (=1). Mind that these are relative probabilities with respect to all houses defined. If all probabilities are defined as 16, they'll all have the same probability as if they had all a probability of 1.
|-
| years_available
| array of two int
| [xx, yy] where xx and yy indicate the introduction year and the last year the building can be built
|-
| minimum_lifetime
| 0 ... 255
| number of years the building will remain at least
|-
| availability_mask
|
[bitmask([[NML:List of town zones|town zones]]), bitmask(CLIMATE_XXX, ...)]
|
An array with two bitmasks, the first bitmask is a mask of town zones where this house is available. The second bitmask is a mask of climates combined with the special value ABOVE_SNOWLINE which you need to set for houses available in the arctic climate above the snowline. Examples:

* Available in the centre town zone in toyland only: <code>[bitmask(TOWNZONE_CENTRE), bitmask(CLIMATE_TOYLAND)]</code>
* Available in all town zones in the arctic climate both above and below the snowline: <code>[ALL_TOWNZONES, bitmask(CLIMATE_ARCTIC, ABOVE_SNOWLINE)]</code>
* Available everywhere except on the town edge: <code>[ALL_TOWNZONES & ~bitmask(TOWNZONE_EDGE), ALL_CLIMATES | bitmask(ABOVE_SNOWLINE)</code>
|-
| callback_flags
| bitmask(HOUSE_CBF_XX)
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| random_colours
| array of 4, each COLOUR_XXX
|
colour values in an array, refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for a list of possible values.
|-
| refresh_multiplier
| 0 ... 63
| Defines the frequency with which the tile will be re-randomized which has an impact for random animation.
|-
| animation_info
| Array [ANIMATION_XXX, frame-count]
|
Type of animation and its length (1...128 frames):

;ANIMATION_LOOPING
;ANIMATION_NON_LOOPING
|-
| animation_speed
| 2 ... 16
|
Speed of animation, see [[NML:Animation speed|animation speed table]] for the meaning of the values.
|-
| building_class
| 0 .. 254
| An arbitrary number. You can check for the presence of buildings of the same class when building new buildings or using animation. Only the north tile of a multi-tile building is assigned a class.
|
|-
| watched_cargo_types
| array of values from your [[NML:Cargotable|cargo table]]
| {{ottdp|1.2|2.6|ottdrev=r23072|ttdprev=r1677}}List of cargo types to watch, to be used with the <code style:darkgreen>watched_cargo_accepted</code> callback.
|}

==House variables==

{| class="t"
! name
! value range
! comment
|-
| construction_state
| 0..3
| Current construction state of the house tile. 0..2 = under construction, 3 = finished.
|-
| pseudo_random_bits
| 0..3
| Some pseudo-random bits, based on the tile position. TTD houses use this to randomize their appearance.
|-
| age
| 0..255
| Age of the house in years, limited to 255
|-
| town_zone
|
[[NML:List of town zones|town zone]]
| The town zone of the current tile
|-
| terrain_type
| TILETYPE_XX
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|-
| same_house_count_town
| 0..255
| Number of the houses with the same ID in the same town as this house
|-
| same_house_count_map
| 0..255
| Number of the houses with the same ID on the entire map
|-
| same_class_count_town
| 0..255
| Number of the houses with the same <code style="color:darkgreen">building_class</code> in the same town as this house. The class of the north tile of the use is used for this purpose, as other tiles don't normally have a class.
|-
| same_class_count_map
| 0..255
| Number of the houses with the same <code style="color:darkgreen">building_class</code> on the entire map. The class of the north tile of the use is used for this purpose, as other tiles don't normally have a class.
|-
| generating_town
| [0 <nowiki>|</nowiki> 1]
| 1 a random town is currently being created, 0 otherwise. Note that while generating a random town, [[NML:Towns#Town variables|town variables]] <code style="color:darkgreen">population</code> and <code style="color:darkgreen">building_count</code> are incorrect. The population variable contains the population of buildings generated ''yet'', the final value may be larger. The building_count is surely higher than the final value will be.
|-
| animation_frame
| 0..255
| Current animation frame
|-
| x_coordinate
| 0..2047
| X-coordinate (top right -> bottom left) of the tile on the map
|-
| y_coordinate
| 0..2047
| Y-coordinate (top left -> bottom right) of the tile on the map
|-
| relative_x
| 0..1
| X-coordinate (top right -> bottom left) of the tile relative to the northernmost tile.
|-
| relative_y
| 0..1
| 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 [[NML:Builtin functions|builtin function]] relative_coord(x, y) may be useful when making comparisons.
|-
| house_tile
| HOUSE_TILE_XXX, XXX = <nowiki>[NORTH | EAST | WEST | SOUTH]</nowiki>
| What tile of a multi-tile house this is.
|-
| house_type_id
| 0..255
| Item ID of this house type, of the north tile.
|}

The following variables require one or more arguments
{| class="t"
! name
! arguments
! value range
! comment
|-
| old_house_count_town
| ID of old house type (0..109)
| 0..255
| Number of old houses with a given ID in the same town as the current house
|-
| old_house_count_town
| ID of old house type (0..109)
| 0..255
| Number of old houses with a given ID on the whole map
|-
| other_house_count_town
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses with a given ID in the same town as the current house
|-
| other_house_count_map
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses with a given ID on the whole map
|-
| other_class_count_town
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses, with the same class as the house with the given ID, in the same town as the current house
|-
| other_class_count_map
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses, with the same class as the house with the given ID, on the whole map
|-
| nearby_tile_slope
| x- and y-offset (both signed, range -8..7)
| SLOPE_XXX
| See [[NML:List of tile slopes|tile slopes]] for an overview of possible values
|-
| nearby_tile_is_water
| x- and y-offset (both signed, range -8..7)
| [0 <nowiki>|</nowiki> 1]
| 1 if the tile is water, 0 otherwise
|-
| nearby_tile_terrain_type
| x- and y-offset (both signed, range -8..7)
| TILETYPE_XX
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|-
| nearby_tile_water_class
| x- and y-offset (both signed, range -8..7)
| WATER_CLASS_XXX
| XXX = [NONE <nowiki>|</nowiki> SEA <nowiki>|</nowiki> CANAL <nowiki>|</nowiki> RIVER] Note that tiles for which <code style="color:darkgreen">nearby_tile_is_water</code> is 0 may still have a water class, e.g. industry tiles with water beneath them.
|-
| nearby_tile_height
| x- and y-offset (both signed, range -8..7)
| 0..255 (currently limited to 0..15)
| Height of the lowest corner of the tile. 1 unit is one height level of 8 pixels.
|-
| nearby_tile_class
| x- and y-offset (both signed, range -8..7)
|
[[NML:List of tile classes|Tile class]]
|
|-
| nearby_tile_animation_frame
| x- and y-offset (both signed, range -8..7)
| 0..255
| Animation frame of the given tile
|-
| cargo_accepted_nearby_ever
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby">Cargo type should be from your cargo translation table. X- and y-offset are optional, if provided both must be in range -128..127. A station is considered nearby if the tile is in the station's acceptance area. This is the purpose of the x- and y-offset, as other tiles may have other stations nearby.</ref>
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was ever accepted at a nearby station, 0 otherwise
|-
| cargo_accepted_nearby_last_month
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was accepted at a nearby station in the last month, 0 otherwise
|-
| cargo_accepted_nearby_this_month
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was ever accepted at a nearby station in this month, 0 otherwise
|-
| cargo_accepted_nearby_last_bigtick
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was ever accepted at a nearby station since the last periodic processing, which happens every 250 ticks. 0 otherwise
|-
| cargo_accepted_nearby_watched
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was one of the cargo types that triggered the <code style="color:darkgreen">watched_cargo_accepted</code>-callback (only during this callback), 0 otherwise
|-
| nearest_house_matching_criterion
| radius (1..63) and criterion (SEARCH_HOUSE_BY_XXX, XXX = [<nowiki>ID | CLASS | GRFID</nowiki>])
| 1..63, or 0 if not found
| Perform a circular search for a house matching either the id, <code style="color:darkgreen">building_class</code> or GRFID of this house, depending on the second parameter. The first parameter specifies the maximum search radius. Return value is the Manhattan distance of the closest matching house tile, or 0 if no match was found. Note that tiles of the originating house never match.
|-
| nearby_tile_house_id
| x- and y-offset (both signed, range -8..7)
| -1, or 0 .. 767
| Return value is -1 if the tile is not a house tile, X (0..255) if the tile contains old house type X, 256+X if the tile contains a house from this NewGRF with ID X, 512+X if the tile contains a house from a different NewGRF with ID X.
|-
| nearby_tile_house_class
| x- and y-offset (both signed, range -8..7)
| -1, 0, or 256 .. 767
| Return value is -1 if the tile is not a house tile, 0 if the house tile does not have a class (this includes all old house types), 256+X (X = 0..255) if the house has been defined by this NewGRF with <code style="color:darkgreen">building_class</code> X or 512+X if the house has been defined by a different NewGRF with <code style="color:darkgreen">building_class</code> X.
|-
| nearby_tile_house_grfid
| x- and y-offset (both signed, range -8..7)
| -1, 0 or a GRFID
| Return value is -1 if the tile is not a house tile, 0 if the house tile contains an old house type, or else the GRFID of the NewGRF defining the house.
|}
<references/>

==House callbacks==
Unless noted otherwise, callbacks may be called for any of the tiles of a multi-tile house.

{| class="t"
! callback
! return value
! comment
|-
| default
| Sprite layout
| Graphics for the house tile
|-
| graphics_xxx, xxx = <nowiki>[north | east | south | west]</nowiki>
| Sprite layout
| Tile-specific graphics for one of the tiles of a multi-tile house. Of course, this is callback is called for that tile only.
|-
| random_trigger
| N/A
|
See [[NML:Random switch|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. <code>extra_callback_info1</code> contains 32 random bits, if enabled in the <code>building_flags</code> property. Returning a sound effect in the high byte will cause that sound effect to be played.
|-
| anim_control
| Next animation frame or CB_RESULT_XXX
| Called every 256 ticks. 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. <code>extra_callback_info1</code> contains 32 random bits. The low 16 bits are always different for each house tile, but the high 16 bits are the same for each tile if synchronized animation is enabled in the <code>building_flags</code>-property. Returning a sound effect in the high byte will cause that sound effect to be played.
|-
| construction_anim
| Same as <code>anim_control</code>
| Works the same as the <code>anim_control</code> callback, except that it's called when the construction state changes.
|-
| watched_cargo_accepted
| Same as <code>anim_control</code>
| Works the same as the <code>anim_control</code> callback, except that it's called when one of the watched cargo types is accepted.
|-
| 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 <code>accepted_cargo</code> 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 the acceptance properties are used instead. Cargo types are from the <code>cargo_type_accept</code> callback, or the <code>accepted_cargo</code> 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.
|-
| cargo_production
| (cargo_type * 256) + amount
| Called every 256 ticks. Called multiple times until 0x20FF is returned. The high byte of the result contains a cargo type, the low byte contains the amount of that cargo to produce. <code>extra_callback_info1</code> contains the number of iterations so far, <code>extra_callback_info2</code> contains random bits.
|-
| 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.
|-
| name
| String
| Name of the building (when using tile query tool)
|-
| colour
| Palette number
|
Used to recolour the building. See here [[NML:List of default colour translation palettes|here]] for an overview of default palettes.
|-
| construction_check
| 0 or 1
| Return 1 to allow building the house or 0 to disallow. Called only for the north tile.
|-
| destruction
| 0 or 1
| Called periodically. Return 0 to keep the building or 1 to destroy it. Called only for the north tile.
|-
| protection
| 0 or 1
| Return 0 to allow destruction, or 1 to disallow
|}

NML:Item

2012-09-03T19:57:12Z

Hirundo: /* General */ ID allocation by NML

{{NMLNavBlocksyntax}}

== General ==

item (<expression> [, <ID> [, <expression> [, <expression>]]]) {
(<property-block>|<graphics-block>|<livery_override-block>)+
}

The first argument is the feature of the item, the second (optional) argument is the name used to identify the object throughout the NML file and the third (optional) argument is the numerical id you want to use for this item. The meaning and relevance of this id differs per-feature, refer to the feature-specific pages for more information. The default value is -1, which lets NML pick an id for you. The fourth (optional) argument is the size, which is relavant for [[NML:Houses|houses]] only and explained there.

Example:

<pre style="color:blue">
item (FEAT_ROADVEHS, hereford_tram) {
property {
name: string(STR_NAME_HEREFORD_TRAM);
climates_available: ALL_CLIMATES;
introduction_date: date(1940,1,1);
speed: 60 km/h;
}
}
</pre>

== Property block ==

property {
(<ID>: (<string>|(<expression> [<unit>]));)+
}

This one looks a lot more complicated than it actually is. A property-block contains one or more assignments. Each assignment starts with the name of the property that is changed followed by a colon. After the colon follows the value and you end the line with a semicolon. The type of the value depends on the property, some properties require a string as value and some an expression. For some properties you can optionally specify a unit that is used to convert the value to the unit that is written to the output file. You can only use a unit if the expression is constant. [[NML:Units|List of valid units]]

== Graphics block ==

A graphics block must be placed in an item-block. It allows to define the graphics for a particular item, as well as various callbacks. Callbacks are used to define various things at run time, based on information (variables) of the item itself. This provides a much greater degree of flexibility than setting properties. An example (using fictional callback names):

<pre style="color:blue">
graphics {
callback_a: switch_a;
callback_b: return 42 + some_var;
default: some_spritegroup;
}
</pre>

The callbacks that are available differ per feature, refer to the feature-specific pages for more information. The 'default'-callback is usually used to resolve the graphics. For each callback a return value may be specified, in the same way as for [[NML:Switch| switch-blocks]]. Note that all callbacks have to be defined in a '''single''' graphics-block.

For vehicles and stations, a cargo type (identifier from the [[NML:Cargotable|cargo table]]) may be used as callback name, to provide cargo-specific graphics.

== Livery override ==

[[Image:NML liveryoverride.png|frame|left|Same cars, different engine, different car sprites]]

A livery override block offers the option to change the look and behaviour of a wagon depending on the engine it is attached to. It is basically the same as a graphics-block and its syntax is the same. The difference is that it only applies to a particular combination of an engine and a wagon. E.g. passenger wagons could adapt their livery to match the engine, to make the consist look like a multiple-unit train. The spritegroup needs to be defined before it can be used in a livery override. A livery override block is always part of the '''engine''' definition and looks like

livery_override (vehicleID) {
callback_name: switch_name;
callback_name2: return value;
default: spritegroup_name;
}

For an example see the [[NML:Spritegroup|spritegroup]]

NML:Item

2012-09-03T19:53:15Z

Hirundo: /* General */ Add information about item size

{{NMLNavBlocksyntax}}

== General ==

item (<expression> [, <ID> [, <expression> [, <expression>]]]) {
(<property-block>|<graphics-block>|<livery_override-block>)+
}

The first argument is the feature of the item, the second (optional) argument is the name used to identify the object throughout the NML file and the third (optional) argument is the numerical id you want to use for this item. The meaning and relevance of this id differs per-feature, refer to the feature-specific pages for more information. The fourth (optional) argument is the size, which is relavant for [[NML:Houses|houses]] only and explained there.

Example:

<pre style="color:blue">
item (FEAT_ROADVEHS, hereford_tram) {
property {
name: string(STR_NAME_HEREFORD_TRAM);
climates_available: ALL_CLIMATES;
introduction_date: date(1940,1,1);
speed: 60 km/h;
}
}
</pre>

== Property block ==

property {
(<ID>: (<string>|(<expression> [<unit>]));)+
}

This one looks a lot more complicated than it actually is. A property-block contains one or more assignments. Each assignment starts with the name of the property that is changed followed by a colon. After the colon follows the value and you end the line with a semicolon. The type of the value depends on the property, some properties require a string as value and some an expression. For some properties you can optionally specify a unit that is used to convert the value to the unit that is written to the output file. You can only use a unit if the expression is constant. [[NML:Units|List of valid units]]

== Graphics block ==

A graphics block must be placed in an item-block. It allows to define the graphics for a particular item, as well as various callbacks. Callbacks are used to define various things at run time, based on information (variables) of the item itself. This provides a much greater degree of flexibility than setting properties. An example (using fictional callback names):

<pre style="color:blue">
graphics {
callback_a: switch_a;
callback_b: return 42 + some_var;
default: some_spritegroup;
}
</pre>

The callbacks that are available differ per feature, refer to the feature-specific pages for more information. The 'default'-callback is usually used to resolve the graphics. For each callback a return value may be specified, in the same way as for [[NML:Switch| switch-blocks]]. Note that all callbacks have to be defined in a '''single''' graphics-block.

For vehicles and stations, a cargo type (identifier from the [[NML:Cargotable|cargo table]]) may be used as callback name, to provide cargo-specific graphics.

== Livery override ==

[[Image:NML liveryoverride.png|frame|left|Same cars, different engine, different car sprites]]

A livery override block offers the option to change the look and behaviour of a wagon depending on the engine it is attached to. It is basically the same as a graphics-block and its syntax is the same. The difference is that it only applies to a particular combination of an engine and a wagon. E.g. passenger wagons could adapt their livery to match the engine, to make the consist look like a multiple-unit train. The spritegroup needs to be defined before it can be used in a livery override. A livery override block is always part of the '''engine''' definition and looks like

livery_override (vehicleID) {
callback_name: switch_name;
callback_name2: return value;
default: spritegroup_name;
}

For an example see the [[NML:Spritegroup|spritegroup]]

NML:Houses

2012-09-03T19:49:44Z

Hirundo: /* House variables */ Add new variables, update information on others

{{NMLNavPropVarCB}}

==House properties==

{| class="t"
! property
! value range
! comment
|-
| name
| string
| for example string(STR_NAME_EIFFEL_TOWER)
|-
| substitute
| 0 ... 109
| Number of the default house that replaces this one, if this house 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, except for the church / stadium flags (see below). The old house must have the same size as the new house, see the list of [[NML:List_of_default_house_properties|default house types]] for a list of possible substitute IDs.
|-
| override
| 0 ... 109
| id of the default house which this house replaces. This will cause your house to be placed instead of the default house. This is ignored, if the default house has already been overridden. You can define this property multiple times. Your house and the overridden house must have the same size, see the list of [[NML:List_of_default_house_properties|default house types]].
|-
| building_flags.
| bitmask(HOUSE_FLAG_XXX,...)
|
;HOUSE_FLAG_NOT_SLOPED
:Can only be built on flat terrain. Note that 2x2 buildings will always only be built on flat land, even if this bit isn't set.
;HOUSE_FLAG_ANIMATE
:Enable animation
;HOUSE_FLAG_CHURCH
:House is a church (only 1 will be built per town)
;HOUSE_FLAG_STADIUM
:House is a stadium (only 1 will be built per town)
;HOUSE_FLAG_ONLY_SE
:Can only be built in the scenario editor
;HOUSE_FLAG_PROTECTED
:Will not be removed by the game
;HOUSE_FLAG_SYNC_CALLBACK
:Animation callback <code style="color:darkgreen">anim_control</code> is called at the same time for all tiles.
;HOUSE_FLAG_RANDOM_ANIMATION
:Enable random bits in the <code style="color:darkgreen">anim_next_frame</code>-callback.
|-
| population
| 0 ... 255
| number of inhabitants the building adds to the town, if present
|-
| mail_multiplier
| 0 ... 255
|
|-
| accepted_cargos
| Array with up to 3 [cargo_id, amount]-pairs.
| The cargos that are accepted by each tile of the house. 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 fully accept both PASS and MAIL you could use this: <code style="color:darkgreen"><nowiki>accepted_cargos: [[PASS, 8], [MAIL, 8]];</nowiki></code> Example: for a house tile that doesn't accept any cargos at all you'd use: <code style="color:darkgreen">accepted_cargos: [];</code>
|-
| local_authority_impact
| 0 ... 65525
| amount of happiness decrease of the city council, if the building is destroyed. Town ratings can vary between -1000 (appalling) and +1000 (outstanding).
|-
| removal_cost_multiplier
| 0 ... 255
|
|-
| probability
| 0 ... 16 (float)
| Probability with respect to the default houses (=1). Mind that these are relative probabilities with respect to all houses defined. If all probabilities are defined as 16, they'll all have the same probability as if they had all a probability of 1.
|-
| years_available
| array of two int
| [xx, yy] where xx and yy indicate the introduction year and the last year the building can be built
|-
| minimum_lifetime
| 0 ... 255
| number of years the building will remain at least
|-
| availability_mask
|
[bitmask([[NML:List of town zones|town zones]]), bitmask(CLIMATE_XXX, ...)]
|
An array with two bitmasks, the first bitmask is a mask of town zones where this house is available. The second bitmask is a mask of climates combined with the special value ABOVE_SNOWLINE which you need to set for houses available in the arctic climate above the snowline. Examples:

* Available in the centre town zone in toyland only: <code>[bitmask(TOWNZONE_CENTRE), bitmask(CLIMATE_TOYLAND)]</code>
* Available in all town zones in the arctic climate both above and below the snowline: <code>[ALL_TOWNZONES, bitmask(CLIMATE_ARCTIC, ABOVE_SNOWLINE)]</code>
* Available everywhere except on the town edge: <code>[ALL_TOWNZONES & ~bitmask(TOWNZONE_EDGE), ALL_CLIMATES | bitmask(ABOVE_SNOWLINE)</code>
|-
| callback_flags
| bitmask(HOUSE_CBF_XX)
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| random_colours
| array of 4, each COLOUR_XXX
|
colour values in an array, refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for a list of possible values.
|-
| refresh_multiplier
| 0 ... 63
| Defines the frequency with which the tile will be re-randomized which has an impact for random animation.
|-
| animation_info
| Array [ANIMATION_XXX, frame-count]
|
Type of animation and its length (1...128 frames):

;ANIMATION_LOOPING
;ANIMATION_NON_LOOPING
|-
| animation_speed
| 2 ... 16
|
Speed of animation, see [[NML:Animation speed|animation speed table]] for the meaning of the values.
|-
| building_class
| 0 .. 254
| An arbitrary number. You can check for the presence of buildings of the same class when building new buildings or using animation. Only the north tile of a multi-tile building is assigned a class.
|
|-
| watched_cargo_types
| array of values from your [[NML:Cargotable|cargo table]]
| {{ottdp|1.2|2.6|ottdrev=r23072|ttdprev=r1677}}List of cargo types to watch, to be used with the <code style:darkgreen>watched_cargo_accepted</code> callback.
|}

==House variables==

{| class="t"
! name
! value range
! comment
|-
| construction_state
| 0..3
| Current construction state of the house tile. 0..2 = under construction, 3 = finished.
|-
| pseudo_random_bits
| 0..3
| Some pseudo-random bits, based on the tile position. TTD houses use this to randomize their appearance.
|-
| age
| 0..255
| Age of the house in years, limited to 255
|-
| town_zone
|
[[NML:List of town zones|town zone]]
| The town zone of the current tile
|-
| terrain_type
| TILETYPE_XX
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|-
| same_house_count_town
| 0..255
| Number of the houses with the same ID in the same town as this house
|-
| same_house_count_map
| 0..255
| Number of the houses with the same ID on the entire map
|-
| same_class_count_town
| 0..255
| Number of the houses with the same <code style="color:darkgreen">building_class</code> in the same town as this house. The class of the north tile of the use is used for this purpose, as other tiles don't normally have a class.
|-
| same_class_count_map
| 0..255
| Number of the houses with the same <code style="color:darkgreen">building_class</code> on the entire map. The class of the north tile of the use is used for this purpose, as other tiles don't normally have a class.
|-
| generating_town
| [0 <nowiki>|</nowiki> 1]
| 1 a random town is currently being created, 0 otherwise. Note that while generating a random town, [[NML:Towns#Town variables|town variables]] <code style="color:darkgreen">population</code> and <code style="color:darkgreen">building_count</code> are incorrect. The population variable contains the population of buildings generated ''yet'', the final value may be larger. The building_count is surely higher than the final value will be.
|-
| animation_frame
| 0..255
| Current animation frame
|-
| x_coordinate
| 0..2047
| X-coordinate (top right -> bottom left) of the tile on the map
|-
| y_coordinate
| 0..2047
| Y-coordinate (top left -> bottom right) of the tile on the map
|-
| relative_x
| 0..1
| X-coordinate (top right -> bottom left) of the tile relative to the northernmost tile.
|-
| relative_y
| 0..1
| 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 [[NML:Builtin functions|builtin function]] relative_coord(x, y) may be useful when making comparisons.
|-
| house_tile
| HOUSE_TILE_XXX, XXX = <nowiki>[NORTH | EAST | WEST | SOUTH]</nowiki>
| What tile of a multi-tile house this is.
|-
| house_type_id
| 0..255
| Item ID of this house type, of the north tile.
|}

The following variables require one or more arguments
{| class="t"
! name
! arguments
! value range
! comment
|-
| old_house_count_town
| ID of old house type (0..109)
| 0..255
| Number of old houses with a given ID in the same town as the current house
|-
| old_house_count_town
| ID of old house type (0..109)
| 0..255
| Number of old houses with a given ID on the whole map
|-
| other_house_count_town
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses with a given ID in the same town as the current house
|-
| other_house_count_map
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses with a given ID on the whole map
|-
| other_class_count_town
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses, with the same class as the house with the given ID, in the same town as the current house
|-
| other_class_count_map
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses, with the same class as the house with the given ID, on the whole map
|-
| nearby_tile_slope
| x- and y-offset (both signed, range -8..7)
| SLOPE_XXX
| See [[NML:List of tile slopes|tile slopes]] for an overview of possible values
|-
| nearby_tile_is_water
| x- and y-offset (both signed, range -8..7)
| [0 <nowiki>|</nowiki> 1]
| 1 if the tile is water, 0 otherwise
|-
| nearby_tile_terrain_type
| x- and y-offset (both signed, range -8..7)
| TILETYPE_XX
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|-
| nearby_tile_water_class
| x- and y-offset (both signed, range -8..7)
| WATER_CLASS_XXX
| XXX = [NONE <nowiki>|</nowiki> SEA <nowiki>|</nowiki> CANAL <nowiki>|</nowiki> RIVER] Note that tiles for which <code style="color:darkgreen">nearby_tile_is_water</code> is 0 may still have a water class, e.g. industry tiles with water beneath them.
|-
| nearby_tile_height
| x- and y-offset (both signed, range -8..7)
| 0..255 (currently limited to 0..15)
| Height of the lowest corner of the tile. 1 unit is one height level of 8 pixels.
|-
| nearby_tile_class
| x- and y-offset (both signed, range -8..7)
|
[[NML:List of tile classes|Tile class]]
|
|-
| nearby_tile_animation_frame
| x- and y-offset (both signed, range -8..7)
| 0..255
| Animation frame of the given tile
|-
| cargo_accepted_nearby_ever
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby">Cargo type should be from your cargo translation table. X- and y-offset are optional, if provided both must be in range -128..127. A station is considered nearby if the tile is in the station's acceptance area. This is the purpose of the x- and y-offset, as other tiles may have other stations nearby.</ref>
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was ever accepted at a nearby station, 0 otherwise
|-
| cargo_accepted_nearby_last_month
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was accepted at a nearby station in the last month, 0 otherwise
|-
| cargo_accepted_nearby_this_month
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was ever accepted at a nearby station in this month, 0 otherwise
|-
| cargo_accepted_nearby_last_bigtick
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was ever accepted at a nearby station since the last periodic processing, which happens every 250 ticks. 0 otherwise
|-
| cargo_accepted_nearby_watched
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was one of the cargo types that triggered the <code style="color:darkgreen">watched_cargo_accepted</code>-callback (only during this callback), 0 otherwise
|-
| nearest_house_matching_criterion
| radius (1..63) and criterion (SEARCH_HOUSE_BY_XXX, XXX = [<nowiki>ID | CLASS | GRFID</nowiki>])
| 1..63, or 0 if not found
| Perform a circular search for a house matching either the id, <code style="color:darkgreen">building_class</code> or GRFID of this house, depending on the second parameter. The first parameter specifies the maximum search radius. Return value is the Manhattan distance of the closest matching house tile, or 0 if no match was found. Note that tiles of the originating house never match.
|-
| nearby_tile_house_id
| x- and y-offset (both signed, range -8..7)
| -1, or 0 .. 767
| Return value is -1 if the tile is not a house tile, X (0..255) if the tile contains old house type X, 256+X if the tile contains a house from this NewGRF with ID X, 512+X if the tile contains a house from a different NewGRF with ID X.
|-
| nearby_tile_house_class
| x- and y-offset (both signed, range -8..7)
| -1, 0, or 256 .. 767
| Return value is -1 if the tile is not a house tile, 0 if the house tile does not have a class (this includes all old house types), 256+X (X = 0..255) if the house has been defined by this NewGRF with <code style="color:darkgreen">building_class</code> X or 512+X if the house has been defined by a different NewGRF with <code style="color:darkgreen">building_class</code> X.
|-
| nearby_tile_house_grfid
| x- and y-offset (both signed, range -8..7)
| -1, 0 or a GRFID
| Return value is -1 if the tile is not a house tile, 0 if the house tile contains an old house type, or else the GRFID of the NewGRF defining the house.
|}
<references/>

==House callbacks==
Unless noted otherwise, callbacks may be called for any of the tiles of a multi-tile house.

{| class="t"
! callback
! return value
! comment
|-
| default
| Sprite layout
| Graphics for the house tile
|-
| graphics_xxx, xxx = <nowiki>[north | east | south | west]</nowiki>
| Sprite layout
| Tile-specific graphics for one of the tiles of a multi-tile house. Of course, this is callback is called for that tile only.
|-
| random_trigger
| N/A
|
See [[NML:Random switch|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. <code>extra_callback_info1</code> contains 32 random bits, if enabled in the <code>building_flags</code> property. Returning a sound effect in the high byte will cause that sound effect to be played.
|-
| anim_control
| Next animation frame or CB_RESULT_XXX
| Called every 256 ticks. 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. <code>extra_callback_info1</code> contains 32 random bits. The low 16 bits are always different for each house tile, but the high 16 bits are the same for each tile if synchronized animation is enabled in the <code>building_flags</code>-property. Returning a sound effect in the high byte will cause that sound effect to be played.
|-
| construction_anim
| Same as <code>anim_control</code>
| Works the same as the <code>anim_control</code> callback, except that it's called when the construction state changes.
|-
| watched_cargo_accepted
| Same as <code>anim_control</code>
| Works the same as the <code>anim_control</code> callback, except that it's called when one of the watched cargo types is accepted.
|-
| 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 <code>accepted_cargo</code> 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 the acceptance properties are used instead. Cargo types are from the <code>cargo_type_accept</code> callback, or the <code>accepted_cargo</code> 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.
|-
| cargo_production
| (cargo_type * 256) + amount
| Called every 256 ticks. Called multiple times until 0x20FF is returned. The high byte of the result contains a cargo type, the low byte contains the amount of that cargo to produce. <code>extra_callback_info1</code> contains the number of iterations so far, <code>extra_callback_info2</code> contains random bits.
|-
| 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.
|-
| name
| String
| Name of the building (when using tile query tool)
|-
| colour
| Palette number
|
Used to recolour the building. See here [[NML:List of default colour translation palettes|here]] for an overview of default palettes.
|-
| construction_check
| 0 or 1
| Return 1 to allow building the house or 0 to disallow. Called only for the north tile.
|-
| destruction
| 0 or 1
| Called periodically. Return 0 to keep the building or 1 to destroy it. Called only for the north tile.
|-
| protection
| 0 or 1
| Return 0 to allow destruction, or 1 to disallow
|}

NML:Houses

2012-09-03T19:44:45Z

Hirundo: Update information about callbacks

{{NMLNavPropVarCB}}

==House properties==

{| class="t"
! property
! value range
! comment
|-
| name
| string
| for example string(STR_NAME_EIFFEL_TOWER)
|-
| substitute
| 0 ... 109
| Number of the default house that replaces this one, if this house 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, except for the church / stadium flags (see below). The old house must have the same size as the new house, see the list of [[NML:List_of_default_house_properties|default house types]] for a list of possible substitute IDs.
|-
| override
| 0 ... 109
| id of the default house which this house replaces. This will cause your house to be placed instead of the default house. This is ignored, if the default house has already been overridden. You can define this property multiple times. Your house and the overridden house must have the same size, see the list of [[NML:List_of_default_house_properties|default house types]].
|-
| building_flags.
| bitmask(HOUSE_FLAG_XXX,...)
|
;HOUSE_FLAG_NOT_SLOPED
:Can only be built on flat terrain. Note that 2x2 buildings will always only be built on flat land, even if this bit isn't set.
;HOUSE_FLAG_ANIMATE
:Enable animation
;HOUSE_FLAG_CHURCH
:House is a church (only 1 will be built per town)
;HOUSE_FLAG_STADIUM
:House is a stadium (only 1 will be built per town)
;HOUSE_FLAG_ONLY_SE
:Can only be built in the scenario editor
;HOUSE_FLAG_PROTECTED
:Will not be removed by the game
;HOUSE_FLAG_SYNC_CALLBACK
:Animation callback <code style="color:darkgreen">anim_control</code> is called at the same time for all tiles.
;HOUSE_FLAG_RANDOM_ANIMATION
:Enable random bits in the <code style="color:darkgreen">anim_next_frame</code>-callback.
|-
| population
| 0 ... 255
| number of inhabitants the building adds to the town, if present
|-
| mail_multiplier
| 0 ... 255
|
|-
| accepted_cargos
| Array with up to 3 [cargo_id, amount]-pairs.
| The cargos that are accepted by each tile of the house. 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 fully accept both PASS and MAIL you could use this: <code style="color:darkgreen"><nowiki>accepted_cargos: [[PASS, 8], [MAIL, 8]];</nowiki></code> Example: for a house tile that doesn't accept any cargos at all you'd use: <code style="color:darkgreen">accepted_cargos: [];</code>
|-
| local_authority_impact
| 0 ... 65525
| amount of happiness decrease of the city council, if the building is destroyed. Town ratings can vary between -1000 (appalling) and +1000 (outstanding).
|-
| removal_cost_multiplier
| 0 ... 255
|
|-
| probability
| 0 ... 16 (float)
| Probability with respect to the default houses (=1). Mind that these are relative probabilities with respect to all houses defined. If all probabilities are defined as 16, they'll all have the same probability as if they had all a probability of 1.
|-
| years_available
| array of two int
| [xx, yy] where xx and yy indicate the introduction year and the last year the building can be built
|-
| minimum_lifetime
| 0 ... 255
| number of years the building will remain at least
|-
| availability_mask
|
[bitmask([[NML:List of town zones|town zones]]), bitmask(CLIMATE_XXX, ...)]
|
An array with two bitmasks, the first bitmask is a mask of town zones where this house is available. The second bitmask is a mask of climates combined with the special value ABOVE_SNOWLINE which you need to set for houses available in the arctic climate above the snowline. Examples:

* Available in the centre town zone in toyland only: <code>[bitmask(TOWNZONE_CENTRE), bitmask(CLIMATE_TOYLAND)]</code>
* Available in all town zones in the arctic climate both above and below the snowline: <code>[ALL_TOWNZONES, bitmask(CLIMATE_ARCTIC, ABOVE_SNOWLINE)]</code>
* Available everywhere except on the town edge: <code>[ALL_TOWNZONES & ~bitmask(TOWNZONE_EDGE), ALL_CLIMATES | bitmask(ABOVE_SNOWLINE)</code>
|-
| callback_flags
| bitmask(HOUSE_CBF_XX)
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| random_colours
| array of 4, each COLOUR_XXX
|
colour values in an array, refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for a list of possible values.
|-
| refresh_multiplier
| 0 ... 63
| Defines the frequency with which the tile will be re-randomized which has an impact for random animation.
|-
| animation_info
| Array [ANIMATION_XXX, frame-count]
|
Type of animation and its length (1...128 frames):

;ANIMATION_LOOPING
;ANIMATION_NON_LOOPING
|-
| animation_speed
| 2 ... 16
|
Speed of animation, see [[NML:Animation speed|animation speed table]] for the meaning of the values.
|-
| building_class
| 0 .. 254
| An arbitrary number. You can check for the presence of buildings of the same class when building new buildings or using animation. Only the north tile of a multi-tile building is assigned a class.
|
|-
| watched_cargo_types
| array of values from your [[NML:Cargotable|cargo table]]
| {{ottdp|1.2|2.6|ottdrev=r23072|ttdprev=r1677}}List of cargo types to watch, to be used with the <code style:darkgreen>watched_cargo_accepted</code> callback.
|}

==House variables==

{| class="t"
! name
! value range
! comment
|-
| construction_state
| 0..3
| Current construction state of the house tile. 0..2 = under construction, 3 = finished.
|-
| pseudo_random_bits
| 0..3
| Some pseudo-random bits, based on the tile position. TTD houses use this to randomize their appearance.
|-
| age
| 0..255
| Age of the house in years, limited to 255
|-
| town_zone
|
[[NML:List of town zones|town zone]]
| The town zone of the current tile
|-
| terrain_type
| TILETYPE_XX
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|-
| same_house_count_town
| 0..255
| Number of the houses with the same ID in the same town as this house
|-
| same_house_count_map
| 0..255
| Number of the houses with the same ID on the entire map
|-
| same_class_count_town
| 0..255
| Number of the houses with the same <code style="color:darkgreen">building_class</code> in the same town as this house
|-
| same_class_count_map
| 0..255
| Number of the houses with the same <code style="color:darkgreen">building_class</code> on the entire map
|-
| generating_town
| [0 <nowiki>|</nowiki> 1]
| 1 a random town is currently being created, 0 otherwise. Note that while generating a random town, [[NML:Towns#Town variables|town variables]] <code style="color:darkgreen">population</code> and <code style="color:darkgreen">building_count</code> are incorrect. The population variable contains the population of buildings generated ''yet'', the final value may be larger. The building_count is surely higher than the final value will be.
|-
| animation_frame
| 0..255
| Current animation frame
|-
| x_coordinate
| 0..2047
| X-coordinate (top right -> bottom left) of the tile on the map
|-
| y_coordinate
| 0..2047
| Y-coordinate (top left -> bottom right) of the tile on the map
|}

The following variables require one or more arguments
{| class="t"
! name
! arguments
! value range
! comment
|-
| old_house_count_town
| ID of old house type (0..109)
| 0..255
| Number of old houses with a given ID in the same town as the current house
|-
| old_house_count_town
| ID of old house type (0..109)
| 0..255
| Number of old houses with a given ID on the whole map
|-
| other_house_count_town
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses with a given ID in the same town as the current house
|-
| other_house_count_map
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses with a given ID on the whole map
|-
| other_class_count_town
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses, with the same class as the house with the given ID, in the same town as the current house
|-
| other_class_count_map
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses, with the same class as the house with the given ID, on the whole map
|-
| nearby_tile_slope
| x- and y-offset (both signed, range -8..7)
| SLOPE_XXX
| See [[NML:List of tile slopes|tile slopes]] for an overview of possible values
|-
| nearby_tile_is_water
| x- and y-offset (both signed, range -8..7)
| [0 <nowiki>|</nowiki> 1]
| 1 if the tile is water, 0 otherwise
|-
| nearby_tile_terrain_type
| x- and y-offset (both signed, range -8..7)
| TILETYPE_XX
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|-
| nearby_tile_water_class
| x- and y-offset (both signed, range -8..7)
| WATER_CLASS_XXX
| XXX = [NONE <nowiki>|</nowiki> SEA <nowiki>|</nowiki> CANAL <nowiki>|</nowiki> RIVER] Note that tiles for which <code style="color:darkgreen">nearby_tile_is_water</code> is 0 may still have a water class, e.g. industry tiles with water beneath them.
|-
| nearby_tile_height
| x- and y-offset (both signed, range -8..7)
| 0..255 (currently limited to 0..15)
| Height of the lowest corner of the tile. 1 unit is one height level of 8 pixels.
|-
| nearby_tile_class
| x- and y-offset (both signed, range -8..7)
|
[[NML:List of tile classes|Tile class]]
|
|-
| nearby_tile_animation_frame
| x- and y-offset (both signed, range -8..7)
| 0..255
| Animation frame of the given tile
|-
| cargo_accepted_nearby_ever
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby">Cargo type should be from your cargo translation table. X- and y-offset are optional, if provided both must be in range -128..127. A station is considered nearby if the tile is in the station's acceptance area. This is the purpose of the x- and y-offset, as other tiles may have other stations nearby.</ref>
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was ever accepted at a nearby station, 0 otherwise
|-
| cargo_accepted_nearby_last_month
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was accepted at a nearby station in the last month, 0 otherwise
|-
| cargo_accepted_nearby_this_month
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was ever accepted at a nearby station in this month, 0 otherwise
|-
| cargo_accepted_nearby_last_bigtick
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was ever accepted at a nearby station since the last periodic processing, which happens every 250 ticks. 0 otherwise
|-
| cargo_accepted_nearby_watched
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was one of the cargo types that triggered the <code style="color:darkgreen">watched_cargo_accepted</code>-callback (only during this callback), 0 otherwise
|-
| nearest_house_matching_criterion
| radius (1..63) and criterion (SEARCH_HOUSE_BY_XXX, XXX = [<nowiki>ID | CLASS | GRFID</nowiki>])
| 1..63, or 0 if not found
| Perform a circular search for a house matching either the id, <code style="color:darkgreen">building_class</code> or GRFID of this house, depending on the second parameter. The first parameter specifies the maximum search radius. Return value is the Manhattan distance of the closest matching house tile, or 0 if no match was found. Note that tiles of the originating house never match.
|-
| nearby_tile_house_id
| x- and y-offset (both signed, range -8..7)
| -1, or 0 .. 767
| Return value is -1 if the tile is not a house tile, X (0..255) if the tile contains old house type X, 256+X if the tile contains a house from this NewGRF with ID X, 512+X if the tile contains a house from a different NewGRF with ID X.
|-
| nearby_tile_house_class
| x- and y-offset (both signed, range -8..7)
| -1, 0, or 256 .. 767
| Return value is -1 if the tile is not a house tile, 0 if the house tile does not have a class (this includes all old house types), 256+X (X = 0..255) if the house has been defined by this NewGRF with <code style="color:darkgreen">building_class</code> X or 512+X if the house has been defined by a different NewGRF with <code style="color:darkgreen">building_class</code> X.
|-
| nearby_tile_house_grfid
| x- and y-offset (both signed, range -8..7)
| -1, 0 or a GRFID
| Return value is -1 if the tile is not a house tile, 0 if the house tile contains an old house type, or else the GRFID of the NewGRF defining the house.
|}
<references/>

==House callbacks==
Unless noted otherwise, callbacks may be called for any of the tiles of a multi-tile house.

{| class="t"
! callback
! return value
! comment
|-
| default
| Sprite layout
| Graphics for the house tile
|-
| graphics_xxx, xxx = <nowiki>[north | east | south | west]</nowiki>
| Sprite layout
| Tile-specific graphics for one of the tiles of a multi-tile house. Of course, this is callback is called for that tile only.
|-
| random_trigger
| N/A
|
See [[NML:Random switch|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. <code>extra_callback_info1</code> contains 32 random bits, if enabled in the <code>building_flags</code> property. Returning a sound effect in the high byte will cause that sound effect to be played.
|-
| anim_control
| Next animation frame or CB_RESULT_XXX
| Called every 256 ticks. 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. <code>extra_callback_info1</code> contains 32 random bits. The low 16 bits are always different for each house tile, but the high 16 bits are the same for each tile if synchronized animation is enabled in the <code>building_flags</code>-property. Returning a sound effect in the high byte will cause that sound effect to be played.
|-
| construction_anim
| Same as <code>anim_control</code>
| Works the same as the <code>anim_control</code> callback, except that it's called when the construction state changes.
|-
| watched_cargo_accepted
| Same as <code>anim_control</code>
| Works the same as the <code>anim_control</code> callback, except that it's called when one of the watched cargo types is accepted.
|-
| 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 <code>accepted_cargo</code> 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 the acceptance properties are used instead. Cargo types are from the <code>cargo_type_accept</code> callback, or the <code>accepted_cargo</code> 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.
|-
| cargo_production
| (cargo_type * 256) + amount
| Called every 256 ticks. Called multiple times until 0x20FF is returned. The high byte of the result contains a cargo type, the low byte contains the amount of that cargo to produce. <code>extra_callback_info1</code> contains the number of iterations so far, <code>extra_callback_info2</code> contains random bits.
|-
| 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.
|-
| name
| String
| Name of the building (when using tile query tool)
|-
| colour
| Palette number
|
Used to recolour the building. See here [[NML:List of default colour translation palettes|here]] for an overview of default palettes.
|-
| construction_check
| 0 or 1
| Return 1 to allow building the house or 0 to disallow. Called only for the north tile.
|-
| destruction
| 0 or 1
| Called periodically. Return 0 to keep the building or 1 to destroy it. Called only for the north tile.
|-
| protection
| 0 or 1
| Return 0 to allow destruction, or 1 to disallow
|}

NML:Houses

2012-09-02T21:35:09Z

Hirundo: /* House variables */ construction_state erroneously mentioned industry tiles

{{NMLNavPropVarCB}}

==House properties==

{| class="t"
! property
! value range
! comment
|-
| name
| string
| for example string(STR_NAME_EIFFEL_TOWER)
|-
| substitute
| 0 ... 109
| Number of the default house that replaces this one, if this house 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, except for the church / stadium flags (see below). The old house must have the same size as the new house, see the list of [[NML:List_of_default_house_properties|default house types]] for a list of possible substitute IDs.
|-
| override
| 0 ... 109
| id of the default house which this house replaces. This will cause your house to be placed instead of the default house. This is ignored, if the default house has already been overridden. You can define this property multiple times. Your house and the overridden house must have the same size, see the list of [[NML:List_of_default_house_properties|default house types]].
|-
| building_flags.
| bitmask(HOUSE_FLAG_XXX,...)
|
;HOUSE_FLAG_NOT_SLOPED
:Can only be built on flat terrain. Note that 2x2 buildings will always only be built on flat land, even if this bit isn't set.
;HOUSE_FLAG_ANIMATE
:Enable animation
;HOUSE_FLAG_CHURCH
:House is a church (only 1 will be built per town)
;HOUSE_FLAG_STADIUM
:House is a stadium (only 1 will be built per town)
;HOUSE_FLAG_ONLY_SE
:Can only be built in the scenario editor
;HOUSE_FLAG_PROTECTED
:Will not be removed by the game
;HOUSE_FLAG_SYNC_CALLBACK
:Animation callback <code style="color:darkgreen">anim_control</code> is called at the same time for all tiles.
;HOUSE_FLAG_RANDOM_ANIMATION
:Enable random bits in the <code style="color:darkgreen">anim_next_frame</code>-callback.
|-
| population
| 0 ... 255
| number of inhabitants the building adds to the town, if present
|-
| mail_multiplier
| 0 ... 255
|
|-
| accepted_cargos
| Array with up to 3 [cargo_id, amount]-pairs.
| The cargos that are accepted by each tile of the house. 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 fully accept both PASS and MAIL you could use this: <code style="color:darkgreen"><nowiki>accepted_cargos: [[PASS, 8], [MAIL, 8]];</nowiki></code> Example: for a house tile that doesn't accept any cargos at all you'd use: <code style="color:darkgreen">accepted_cargos: [];</code>
|-
| local_authority_impact
| 0 ... 65525
| amount of happiness decrease of the city council, if the building is destroyed. Town ratings can vary between -1000 (appalling) and +1000 (outstanding).
|-
| removal_cost_multiplier
| 0 ... 255
|
|-
| probability
| 0 ... 16 (float)
| Probability with respect to the default houses (=1). Mind that these are relative probabilities with respect to all houses defined. If all probabilities are defined as 16, they'll all have the same probability as if they had all a probability of 1.
|-
| years_available
| array of two int
| [xx, yy] where xx and yy indicate the introduction year and the last year the building can be built
|-
| minimum_lifetime
| 0 ... 255
| number of years the building will remain at least
|-
| availability_mask
|
[bitmask([[NML:List of town zones|town zones]]), bitmask(CLIMATE_XXX, ...)]
|
An array with two bitmasks, the first bitmask is a mask of town zones where this house is available. The second bitmask is a mask of climates combined with the special value ABOVE_SNOWLINE which you need to set for houses available in the arctic climate above the snowline. Examples:

* Available in the centre town zone in toyland only: <code>[bitmask(TOWNZONE_CENTRE), bitmask(CLIMATE_TOYLAND)]</code>
* Available in all town zones in the arctic climate both above and below the snowline: <code>[ALL_TOWNZONES, bitmask(CLIMATE_ARCTIC, ABOVE_SNOWLINE)]</code>
* Available everywhere except on the town edge: <code>[ALL_TOWNZONES & ~bitmask(TOWNZONE_EDGE), ALL_CLIMATES | bitmask(ABOVE_SNOWLINE)</code>
|-
| callback_flags
| bitmask(HOUSE_CBF_XX)
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| random_colours
| array of 4, each COLOUR_XXX
|
colour values in an array, refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for a list of possible values.
|-
| refresh_multiplier
| 0 ... 63
| Defines the frequency with which the tile will be re-randomized which has an impact for random animation.
|-
| animation_info
| Array [ANIMATION_XXX, frame-count]
|
Type of animation and its length (1...128 frames):

;ANIMATION_LOOPING
;ANIMATION_NON_LOOPING
|-
| animation_speed
| 2 ... 16
|
Speed of animation, see [[NML:Animation speed|animation speed table]] for the meaning of the values.
|-
| building_class
| 0 .. 254
| An arbitrary number. You can check for the presence of buildings of the same class when building new buildings or using animation. Only the north tile of a multi-tile building is assigned a class.
|
|-
| watched_cargo_types
| array of values from your [[NML:Cargotable|cargo table]]
| {{ottdp|1.2|2.6|ottdrev=r23072|ttdprev=r1677}}List of cargo types to watch, to be used with the <code style:darkgreen>watched_cargo_accepted</code> callback.
|}

==House variables==

{| class="t"
! name
! value range
! comment
|-
| construction_state
| 0..3
| Current construction state of the house tile. 0..2 = under construction, 3 = finished.
|-
| pseudo_random_bits
| 0..3
| Some pseudo-random bits, based on the tile position. TTD houses use this to randomize their appearance.
|-
| age
| 0..255
| Age of the house in years, limited to 255
|-
| town_zone
|
[[NML:List of town zones|town zone]]
| The town zone of the current tile
|-
| terrain_type
| TILETYPE_XX
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|-
| same_house_count_town
| 0..255
| Number of the houses with the same ID in the same town as this house
|-
| same_house_count_map
| 0..255
| Number of the houses with the same ID on the entire map
|-
| same_class_count_town
| 0..255
| Number of the houses with the same <code style="color:darkgreen">building_class</code> in the same town as this house
|-
| same_class_count_map
| 0..255
| Number of the houses with the same <code style="color:darkgreen">building_class</code> on the entire map
|-
| generating_town
| [0 <nowiki>|</nowiki> 1]
| 1 a random town is currently being created, 0 otherwise. Note that while generating a random town, [[NML:Towns#Town variables|town variables]] <code style="color:darkgreen">population</code> and <code style="color:darkgreen">building_count</code> are incorrect. The population variable contains the population of buildings generated ''yet'', the final value may be larger. The building_count is surely higher than the final value will be.
|-
| animation_frame
| 0..255
| Current animation frame
|-
| x_coordinate
| 0..2047
| X-coordinate (top right -> bottom left) of the tile on the map
|-
| y_coordinate
| 0..2047
| Y-coordinate (top left -> bottom right) of the tile on the map
|}

The following variables require one or more arguments
{| class="t"
! name
! arguments
! value range
! comment
|-
| old_house_count_town
| ID of old house type (0..109)
| 0..255
| Number of old houses with a given ID in the same town as the current house
|-
| old_house_count_town
| ID of old house type (0..109)
| 0..255
| Number of old houses with a given ID on the whole map
|-
| other_house_count_town
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses with a given ID in the same town as the current house
|-
| other_house_count_map
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses with a given ID on the whole map
|-
| other_class_count_town
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses, with the same class as the house with the given ID, in the same town as the current house
|-
| other_class_count_map
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses, with the same class as the house with the given ID, on the whole map
|-
| nearby_tile_slope
| x- and y-offset (both signed, range -8..7)
| SLOPE_XXX
| See [[NML:List of tile slopes|tile slopes]] for an overview of possible values
|-
| nearby_tile_is_water
| x- and y-offset (both signed, range -8..7)
| [0 <nowiki>|</nowiki> 1]
| 1 if the tile is water, 0 otherwise
|-
| nearby_tile_terrain_type
| x- and y-offset (both signed, range -8..7)
| TILETYPE_XX
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|-
| nearby_tile_water_class
| x- and y-offset (both signed, range -8..7)
| WATER_CLASS_XXX
| XXX = [NONE <nowiki>|</nowiki> SEA <nowiki>|</nowiki> CANAL <nowiki>|</nowiki> RIVER] Note that tiles for which <code style="color:darkgreen">nearby_tile_is_water</code> is 0 may still have a water class, e.g. industry tiles with water beneath them.
|-
| nearby_tile_height
| x- and y-offset (both signed, range -8..7)
| 0..255 (currently limited to 0..15)
| Height of the lowest corner of the tile. 1 unit is one height level of 8 pixels.
|-
| nearby_tile_class
| x- and y-offset (both signed, range -8..7)
|
[[NML:List of tile classes|Tile class]]
|
|-
| nearby_tile_animation_frame
| x- and y-offset (both signed, range -8..7)
| 0..255
| Animation frame of the given tile
|-
| cargo_accepted_nearby_ever
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby">Cargo type should be from your cargo translation table. X- and y-offset are optional, if provided both must be in range -128..127. A station is considered nearby if the tile is in the station's acceptance area. This is the purpose of the x- and y-offset, as other tiles may have other stations nearby.</ref>
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was ever accepted at a nearby station, 0 otherwise
|-
| cargo_accepted_nearby_last_month
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was accepted at a nearby station in the last month, 0 otherwise
|-
| cargo_accepted_nearby_this_month
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was ever accepted at a nearby station in this month, 0 otherwise
|-
| cargo_accepted_nearby_last_bigtick
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was ever accepted at a nearby station since the last periodic processing, which happens every 250 ticks. 0 otherwise
|-
| cargo_accepted_nearby_watched
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was one of the cargo types that triggered the <code style="color:darkgreen">watched_cargo_accepted</code>-callback (only during this callback), 0 otherwise
|-
| nearest_house_matching_criterion
| radius (1..63) and criterion (SEARCH_HOUSE_BY_XXX, XXX = [<nowiki>ID | CLASS | GRFID</nowiki>])
| 1..63, or 0 if not found
| Perform a circular search for a house matching either the id, <code style="color:darkgreen">building_class</code> or GRFID of this house, depending on the second parameter. The first parameter specifies the maximum search radius. Return value is the Manhattan distance of the closest matching house tile, or 0 if no match was found. Note that tiles of the originating house never match.
|-
| nearby_tile_house_id
| x- and y-offset (both signed, range -8..7)
| -1, or 0 .. 767
| Return value is -1 if the tile is not a house tile, X (0..255) if the tile contains old house type X, 256+X if the tile contains a house from this NewGRF with ID X, 512+X if the tile contains a house from a different NewGRF with ID X.
|-
| nearby_tile_house_class
| x- and y-offset (both signed, range -8..7)
| -1, 0, or 256 .. 767
| Return value is -1 if the tile is not a house tile, 0 if the house tile does not have a class (this includes all old house types), 256+X (X = 0..255) if the house has been defined by this NewGRF with <code style="color:darkgreen">building_class</code> X or 512+X if the house has been defined by a different NewGRF with <code style="color:darkgreen">building_class</code> X.
|-
| nearby_tile_house_grfid
| x- and y-offset (both signed, range -8..7)
| -1, 0 or a GRFID
| Return value is -1 if the tile is not a house tile, 0 if the house tile contains an old house type, or else the GRFID of the NewGRF defining the house.
|}
<references/>

==House callbacks==

{| class="t"
! callback
! return value
! comment
|-
| default
| Sprite layout
| Graphics for the house tile
|-
| random_trigger
| N/A
|
See [[NML:Random switch|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. <code>extra_callback_info1</code> contains 32 random bits, if enabled in the <code>building_flags</code> property. Returning a sound effect in the high byte will cause that sound effect to be played.
|-
| anim_control
| Next animation frame or CB_RESULT_XXX
| Called every 256 ticks. 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. <code>extra_callback_info1</code> contains 32 random bits. The low 16 bits are always different for each house tile, but the high 16 bits are the same for each tile if synchronized animation is enabled in the <code>building_flags</code>-property. Returning a sound effect in the high byte will cause that sound effect to be played.
|-
| construction_anim
| Same as <code>anim_control</code>
| Works the same as the <code>anim_control</code> callback, except that it's called when the construction state changes.
|-
| watched_cargo_accepted
| Same as <code>anim_control</code>
| Works the same as the <code>anim_control</code> callback, except that it's called when one of the watched cargo types is accepted.
|-
| 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 <code>accepted_cargo</code> 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 the acceptance properties are used instead. Cargo types are from the <code>cargo_type_accept</code> callback, or the <code>accepted_cargo</code> 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.
|-
| cargo_production
| (cargo_type * 256) + amount
| Called every 256 ticks. Called multiple times until 0x20FF is returned. The high byte of the result contains a cargo type, the low byte contains the amount of that cargo to produce. <code>extra_callback_info1</code> contains the number of iterations so far, <code>extra_callback_info2</code> contains random bits.
|-
| 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.
|-
| name
| String
| Name of the building (when using tile query tool)
|-
| colour
| Palette number
|
Used to recolour the building. See here [[NML:List of default colour translation palettes|here]] for an overview of default palettes.
|-
| construction_check
| 0 or 1
| Return 1 to allow building the house or 0 to disallow.
|-
| destruction
| 0 or 1
| Called periodically. Return 0 to keep the building or 1 to destroy it.
|-
| protection
| 0 or 1
| Return 0 to allow destruction, or 1 to disallow
|}

NML:Houses

2012-09-02T17:53:10Z

Hirundo: Add info about building_class property

{{NMLNavPropVarCB}}

==House properties==

{| class="t"
! property
! value range
! comment
|-
| name
| string
| for example string(STR_NAME_EIFFEL_TOWER)
|-
| substitute
| 0 ... 109
| Number of the default house that replaces this one, if this house 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, except for the church / stadium flags (see below). The old house must have the same size as the new house, see the list of [[NML:List_of_default_house_properties|default house types]] for a list of possible substitute IDs.
|-
| override
| 0 ... 109
| id of the default house which this house replaces. This will cause your house to be placed instead of the default house. This is ignored, if the default house has already been overridden. You can define this property multiple times. Your house and the overridden house must have the same size, see the list of [[NML:List_of_default_house_properties|default house types]].
|-
| building_flags.
| bitmask(HOUSE_FLAG_XXX,...)
|
;HOUSE_FLAG_NOT_SLOPED
:Can only be built on flat terrain. Note that 2x2 buildings will always only be built on flat land, even if this bit isn't set.
;HOUSE_FLAG_ANIMATE
:Enable animation
;HOUSE_FLAG_CHURCH
:House is a church (only 1 will be built per town)
;HOUSE_FLAG_STADIUM
:House is a stadium (only 1 will be built per town)
;HOUSE_FLAG_ONLY_SE
:Can only be built in the scenario editor
;HOUSE_FLAG_PROTECTED
:Will not be removed by the game
;HOUSE_FLAG_SYNC_CALLBACK
:Animation callback <code style="color:darkgreen">anim_control</code> is called at the same time for all tiles.
;HOUSE_FLAG_RANDOM_ANIMATION
:Enable random bits in the <code style="color:darkgreen">anim_next_frame</code>-callback.
|-
| population
| 0 ... 255
| number of inhabitants the building adds to the town, if present
|-
| mail_multiplier
| 0 ... 255
|
|-
| accepted_cargos
| Array with up to 3 [cargo_id, amount]-pairs.
| The cargos that are accepted by each tile of the house. 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 fully accept both PASS and MAIL you could use this: <code style="color:darkgreen"><nowiki>accepted_cargos: [[PASS, 8], [MAIL, 8]];</nowiki></code> Example: for a house tile that doesn't accept any cargos at all you'd use: <code style="color:darkgreen">accepted_cargos: [];</code>
|-
| local_authority_impact
| 0 ... 65525
| amount of happiness decrease of the city council, if the building is destroyed. Town ratings can vary between -1000 (appalling) and +1000 (outstanding).
|-
| removal_cost_multiplier
| 0 ... 255
|
|-
| probability
| 0 ... 16 (float)
| Probability with respect to the default houses (=1). Mind that these are relative probabilities with respect to all houses defined. If all probabilities are defined as 16, they'll all have the same probability as if they had all a probability of 1.
|-
| years_available
| array of two int
| [xx, yy] where xx and yy indicate the introduction year and the last year the building can be built
|-
| minimum_lifetime
| 0 ... 255
| number of years the building will remain at least
|-
| availability_mask
|
[bitmask([[NML:List of town zones|town zones]]), bitmask(CLIMATE_XXX, ...)]
|
An array with two bitmasks, the first bitmask is a mask of town zones where this house is available. The second bitmask is a mask of climates combined with the special value ABOVE_SNOWLINE which you need to set for houses available in the arctic climate above the snowline. Examples:

* Available in the centre town zone in toyland only: <code>[bitmask(TOWNZONE_CENTRE), bitmask(CLIMATE_TOYLAND)]</code>
* Available in all town zones in the arctic climate both above and below the snowline: <code>[ALL_TOWNZONES, bitmask(CLIMATE_ARCTIC, ABOVE_SNOWLINE)]</code>
* Available everywhere except on the town edge: <code>[ALL_TOWNZONES & ~bitmask(TOWNZONE_EDGE), ALL_CLIMATES | bitmask(ABOVE_SNOWLINE)</code>
|-
| callback_flags
| bitmask(HOUSE_CBF_XX)
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| random_colours
| array of 4, each COLOUR_XXX
|
colour values in an array, refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for a list of possible values.
|-
| refresh_multiplier
| 0 ... 63
| Defines the frequency with which the tile will be re-randomized which has an impact for random animation.
|-
| animation_info
| Array [ANIMATION_XXX, frame-count]
|
Type of animation and its length (1...128 frames):

;ANIMATION_LOOPING
;ANIMATION_NON_LOOPING
|-
| animation_speed
| 2 ... 16
|
Speed of animation, see [[NML:Animation speed|animation speed table]] for the meaning of the values.
|-
| building_class
| 0 .. 254
| An arbitrary number. You can check for the presence of buildings of the same class when building new buildings or using animation. Only the north tile of a multi-tile building is assigned a class.
|
|-
| watched_cargo_types
| array of values from your [[NML:Cargotable|cargo table]]
| {{ottdp|1.2|2.6|ottdrev=r23072|ttdprev=r1677}}List of cargo types to watch, to be used with the <code style:darkgreen>watched_cargo_accepted</code> callback.
|}

==House variables==

{| class="t"
! name
! value range
! comment
|-
| construction_state
| 0..3
| Current construction state of the industry tile
|-
| pseudo_random_bits
| 0..3
| Some pseudo-random bits, based on the tile position. TTD houses use this to randomize their appearance.
|-
| age
| 0..255
| Age of the house in years, limited to 255
|-
| town_zone
|
[[NML:List of town zones|town zone]]
| The town zone of the current tile
|-
| terrain_type
| TILETYPE_XX
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|-
| same_house_count_town
| 0..255
| Number of the houses with the same ID in the same town as this house
|-
| same_house_count_map
| 0..255
| Number of the houses with the same ID on the entire map
|-
| same_class_count_town
| 0..255
| Number of the houses with the same <code style="color:darkgreen">building_class</code> in the same town as this house
|-
| same_class_count_map
| 0..255
| Number of the houses with the same <code style="color:darkgreen">building_class</code> on the entire map
|-
| generating_town
| [0 <nowiki>|</nowiki> 1]
| 1 a random town is currently being created, 0 otherwise. Note that while generating a random town, [[NML:Towns#Town variables|town variables]] <code style="color:darkgreen">population</code> and <code style="color:darkgreen">building_count</code> are incorrect. The population variable contains the population of buildings generated ''yet'', the final value may be larger. The building_count is surely higher than the final value will be.
|-
| animation_frame
| 0..255
| Current animation frame
|-
| x_coordinate
| 0..2047
| X-coordinate (top right -> bottom left) of the tile on the map
|-
| y_coordinate
| 0..2047
| Y-coordinate (top left -> bottom right) of the tile on the map
|}

The following variables require one or more arguments
{| class="t"
! name
! arguments
! value range
! comment
|-
| old_house_count_town
| ID of old house type (0..109)
| 0..255
| Number of old houses with a given ID in the same town as the current house
|-
| old_house_count_town
| ID of old house type (0..109)
| 0..255
| Number of old houses with a given ID on the whole map
|-
| other_house_count_town
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses with a given ID in the same town as the current house
|-
| other_house_count_map
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses with a given ID on the whole map
|-
| other_class_count_town
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses, with the same class as the house with the given ID, in the same town as the current house
|-
| other_class_count_map
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses, with the same class as the house with the given ID, on the whole map
|-
| nearby_tile_slope
| x- and y-offset (both signed, range -8..7)
| SLOPE_XXX
| See [[NML:List of tile slopes|tile slopes]] for an overview of possible values
|-
| nearby_tile_is_water
| x- and y-offset (both signed, range -8..7)
| [0 <nowiki>|</nowiki> 1]
| 1 if the tile is water, 0 otherwise
|-
| nearby_tile_terrain_type
| x- and y-offset (both signed, range -8..7)
| TILETYPE_XX
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|-
| nearby_tile_water_class
| x- and y-offset (both signed, range -8..7)
| WATER_CLASS_XXX
| XXX = [NONE <nowiki>|</nowiki> SEA <nowiki>|</nowiki> CANAL <nowiki>|</nowiki> RIVER] Note that tiles for which <code style="color:darkgreen">nearby_tile_is_water</code> is 0 may still have a water class, e.g. industry tiles with water beneath them.
|-
| nearby_tile_height
| x- and y-offset (both signed, range -8..7)
| 0..255 (currently limited to 0..15)
| Height of the lowest corner of the tile. 1 unit is one height level of 8 pixels.
|-
| nearby_tile_class
| x- and y-offset (both signed, range -8..7)
|
[[NML:List of tile classes|Tile class]]
|
|-
| nearby_tile_animation_frame
| x- and y-offset (both signed, range -8..7)
| 0..255
| Animation frame of the given tile
|-
| cargo_accepted_nearby_ever
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby">Cargo type should be from your cargo translation table. X- and y-offset are optional, if provided both must be in range -128..127. A station is considered nearby if the tile is in the station's acceptance area. This is the purpose of the x- and y-offset, as other tiles may have other stations nearby.</ref>
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was ever accepted at a nearby station, 0 otherwise
|-
| cargo_accepted_nearby_last_month
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was accepted at a nearby station in the last month, 0 otherwise
|-
| cargo_accepted_nearby_this_month
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was ever accepted at a nearby station in this month, 0 otherwise
|-
| cargo_accepted_nearby_last_bigtick
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was ever accepted at a nearby station since the last periodic processing, which happens every 250 ticks. 0 otherwise
|-
| cargo_accepted_nearby_watched
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was one of the cargo types that triggered the <code style="color:darkgreen">watched_cargo_accepted</code>-callback (only during this callback), 0 otherwise
|-
| nearest_house_matching_criterion
| radius (1..63) and criterion (SEARCH_HOUSE_BY_XXX, XXX = [<nowiki>ID | CLASS | GRFID</nowiki>])
| 1..63, or 0 if not found
| Perform a circular search for a house matching either the id, <code style="color:darkgreen">building_class</code> or GRFID of this house, depending on the second parameter. The first parameter specifies the maximum search radius. Return value is the Manhattan distance of the closest matching house tile, or 0 if no match was found. Note that tiles of the originating house never match.
|-
| nearby_tile_house_id
| x- and y-offset (both signed, range -8..7)
| -1, or 0 .. 767
| Return value is -1 if the tile is not a house tile, X (0..255) if the tile contains old house type X, 256+X if the tile contains a house from this NewGRF with ID X, 512+X if the tile contains a house from a different NewGRF with ID X.
|-
| nearby_tile_house_class
| x- and y-offset (both signed, range -8..7)
| -1, 0, or 256 .. 767
| Return value is -1 if the tile is not a house tile, 0 if the house tile does not have a class (this includes all old house types), 256+X (X = 0..255) if the house has been defined by this NewGRF with <code style="color:darkgreen">building_class</code> X or 512+X if the house has been defined by a different NewGRF with <code style="color:darkgreen">building_class</code> X.
|-
| nearby_tile_house_grfid
| x- and y-offset (both signed, range -8..7)
| -1, 0 or a GRFID
| Return value is -1 if the tile is not a house tile, 0 if the house tile contains an old house type, or else the GRFID of the NewGRF defining the house.
|}
<references/>

==House callbacks==

{| class="t"
! callback
! return value
! comment
|-
| default
| Sprite layout
| Graphics for the house tile
|-
| random_trigger
| N/A
|
See [[NML:Random switch|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. <code>extra_callback_info1</code> contains 32 random bits, if enabled in the <code>building_flags</code> property. Returning a sound effect in the high byte will cause that sound effect to be played.
|-
| anim_control
| Next animation frame or CB_RESULT_XXX
| Called every 256 ticks. 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. <code>extra_callback_info1</code> contains 32 random bits. The low 16 bits are always different for each house tile, but the high 16 bits are the same for each tile if synchronized animation is enabled in the <code>building_flags</code>-property. Returning a sound effect in the high byte will cause that sound effect to be played.
|-
| construction_anim
| Same as <code>anim_control</code>
| Works the same as the <code>anim_control</code> callback, except that it's called when the construction state changes.
|-
| watched_cargo_accepted
| Same as <code>anim_control</code>
| Works the same as the <code>anim_control</code> callback, except that it's called when one of the watched cargo types is accepted.
|-
| 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 <code>accepted_cargo</code> 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 the acceptance properties are used instead. Cargo types are from the <code>cargo_type_accept</code> callback, or the <code>accepted_cargo</code> 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.
|-
| cargo_production
| (cargo_type * 256) + amount
| Called every 256 ticks. Called multiple times until 0x20FF is returned. The high byte of the result contains a cargo type, the low byte contains the amount of that cargo to produce. <code>extra_callback_info1</code> contains the number of iterations so far, <code>extra_callback_info2</code> contains random bits.
|-
| 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.
|-
| name
| String
| Name of the building (when using tile query tool)
|-
| colour
| Palette number
|
Used to recolour the building. See here [[NML:List of default colour translation palettes|here]] for an overview of default palettes.
|-
| construction_check
| 0 or 1
| Return 1 to allow building the house or 0 to disallow.
|-
| destruction
| 0 or 1
| Called periodically. Return 0 to keep the building or 1 to destroy it.
|-
| protection
| 0 or 1
| Return 0 to allow destruction, or 1 to disallow
|}

NML:Houses

2012-09-02T17:51:38Z

Hirundo: /* House properties */ Acceptance

{{NMLNavPropVarCB}}

==House properties==

{| class="t"
! property
! value range
! comment
|-
| name
| string
| for example string(STR_NAME_EIFFEL_TOWER)
|-
| substitute
| 0 ... 109
| Number of the default house that replaces this one, if this house 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, except for the church / stadium flags (see below). The old house must have the same size as the new house, see the list of [[NML:List_of_default_house_properties|default house types]] for a list of possible substitute IDs.
|-
| override
| 0 ... 109
| id of the default house which this house replaces. This will cause your house to be placed instead of the default house. This is ignored, if the default house has already been overridden. You can define this property multiple times. Your house and the overridden house must have the same size, see the list of [[NML:List_of_default_house_properties|default house types]].
|-
| building_flags.
| bitmask(HOUSE_FLAG_XXX,...)
|
;HOUSE_FLAG_NOT_SLOPED
:Can only be built on flat terrain. Note that 2x2 buildings will always only be built on flat land, even if this bit isn't set.
;HOUSE_FLAG_ANIMATE
:Enable animation
;HOUSE_FLAG_CHURCH
:House is a church (only 1 will be built per town)
;HOUSE_FLAG_STADIUM
:House is a stadium (only 1 will be built per town)
;HOUSE_FLAG_ONLY_SE
:Can only be built in the scenario editor
;HOUSE_FLAG_PROTECTED
:Will not be removed by the game
;HOUSE_FLAG_SYNC_CALLBACK
:Animation callback <code style="color:darkgreen">anim_control</code> is called at the same time for all tiles.
;HOUSE_FLAG_RANDOM_ANIMATION
:Enable random bits in the <code style="color:darkgreen">anim_next_frame</code>-callback.
|-
| population
| 0 ... 255
| number of inhabitants the building adds to the town, if present
|-
| mail_multiplier
| 0 ... 255
|
|-
| accepted_cargos
| Array with up to 3 [cargo_id, amount]-pairs.
| The cargos that are accepted by each tile of the house. 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 fully accept both PASS and MAIL you could use this: <code style="color:darkgreen"><nowiki>accepted_cargos: [[PASS, 8], [MAIL, 8]];</nowiki></code> Example: for a house tile that doesn't accept any cargos at all you'd use: <code style="color:darkgreen">accepted_cargos: [];</code>
|-
| local_authority_impact
| 0 ... 65525
| amount of happiness decrease of the city council, if the building is destroyed. Town ratings can vary between -1000 (appalling) and +1000 (outstanding).
|-
| removal_cost_multiplier
| 0 ... 255
|
|-
| probability
| 0 ... 16 (float)
| Probability with respect to the default houses (=1). Mind that these are relative probabilities with respect to all houses defined. If all probabilities are defined as 16, they'll all have the same probability as if they had all a probability of 1.
|-
| years_available
| array of two int
| [xx, yy] where xx and yy indicate the introduction year and the last year the building can be built
|-
| minimum_lifetime
| 0 ... 255
| number of years the building will remain at least
|-
| availability_mask
|
[bitmask([[NML:List of town zones|town zones]]), bitmask(CLIMATE_XXX, ...)]
|
An array with two bitmasks, the first bitmask is a mask of town zones where this house is available. The second bitmask is a mask of climates combined with the special value ABOVE_SNOWLINE which you need to set for houses available in the arctic climate above the snowline. Examples:

* Available in the centre town zone in toyland only: <code>[bitmask(TOWNZONE_CENTRE), bitmask(CLIMATE_TOYLAND)]</code>
* Available in all town zones in the arctic climate both above and below the snowline: <code>[ALL_TOWNZONES, bitmask(CLIMATE_ARCTIC, ABOVE_SNOWLINE)]</code>
* Available everywhere except on the town edge: <code>[ALL_TOWNZONES & ~bitmask(TOWNZONE_EDGE), ALL_CLIMATES | bitmask(ABOVE_SNOWLINE)</code>
|-
| callback_flags
| bitmask(HOUSE_CBF_XX)
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| random_colours
| array of 4, each COLOUR_XXX
|
colour values in an array, refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for a list of possible values.
|-
| refresh_multiplier
| 0 ... 63
| Defines the frequency with which the tile will be re-randomized which has an impact for random animation.
|-
| animation_info
| Array [ANIMATION_XXX, frame-count]
|
Type of animation and its length (1...128 frames):

;ANIMATION_LOOPING
;ANIMATION_NON_LOOPING
|-
| animation_speed
| 2 ... 16
|
Speed of animation, see [[NML:Animation speed|animation speed table]] for the meaning of the values.
|-
| building_class
| 0 .. 255
| An arbitrary number. You can check for the presence of buildings of the same class when building new buildings or using animation
|
|-
| watched_cargo_types
| array of values from your [[NML:Cargotable|cargo table]]
| {{ottdp|1.2|2.6|ottdrev=r23072|ttdprev=r1677}}List of cargo types to watch, to be used with the <code style:darkgreen>watched_cargo_accepted</code> callback.
|}

==House variables==

{| class="t"
! name
! value range
! comment
|-
| construction_state
| 0..3
| Current construction state of the industry tile
|-
| pseudo_random_bits
| 0..3
| Some pseudo-random bits, based on the tile position. TTD houses use this to randomize their appearance.
|-
| age
| 0..255
| Age of the house in years, limited to 255
|-
| town_zone
|
[[NML:List of town zones|town zone]]
| The town zone of the current tile
|-
| terrain_type
| TILETYPE_XX
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|-
| same_house_count_town
| 0..255
| Number of the houses with the same ID in the same town as this house
|-
| same_house_count_map
| 0..255
| Number of the houses with the same ID on the entire map
|-
| same_class_count_town
| 0..255
| Number of the houses with the same <code style="color:darkgreen">building_class</code> in the same town as this house
|-
| same_class_count_map
| 0..255
| Number of the houses with the same <code style="color:darkgreen">building_class</code> on the entire map
|-
| generating_town
| [0 <nowiki>|</nowiki> 1]
| 1 a random town is currently being created, 0 otherwise. Note that while generating a random town, [[NML:Towns#Town variables|town variables]] <code style="color:darkgreen">population</code> and <code style="color:darkgreen">building_count</code> are incorrect. The population variable contains the population of buildings generated ''yet'', the final value may be larger. The building_count is surely higher than the final value will be.
|-
| animation_frame
| 0..255
| Current animation frame
|-
| x_coordinate
| 0..2047
| X-coordinate (top right -> bottom left) of the tile on the map
|-
| y_coordinate
| 0..2047
| Y-coordinate (top left -> bottom right) of the tile on the map
|}

The following variables require one or more arguments
{| class="t"
! name
! arguments
! value range
! comment
|-
| old_house_count_town
| ID of old house type (0..109)
| 0..255
| Number of old houses with a given ID in the same town as the current house
|-
| old_house_count_town
| ID of old house type (0..109)
| 0..255
| Number of old houses with a given ID on the whole map
|-
| other_house_count_town
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses with a given ID in the same town as the current house
|-
| other_house_count_map
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses with a given ID on the whole map
|-
| other_class_count_town
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses, with the same class as the house with the given ID, in the same town as the current house
|-
| other_class_count_map
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses, with the same class as the house with the given ID, on the whole map
|-
| nearby_tile_slope
| x- and y-offset (both signed, range -8..7)
| SLOPE_XXX
| See [[NML:List of tile slopes|tile slopes]] for an overview of possible values
|-
| nearby_tile_is_water
| x- and y-offset (both signed, range -8..7)
| [0 <nowiki>|</nowiki> 1]
| 1 if the tile is water, 0 otherwise
|-
| nearby_tile_terrain_type
| x- and y-offset (both signed, range -8..7)
| TILETYPE_XX
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|-
| nearby_tile_water_class
| x- and y-offset (both signed, range -8..7)
| WATER_CLASS_XXX
| XXX = [NONE <nowiki>|</nowiki> SEA <nowiki>|</nowiki> CANAL <nowiki>|</nowiki> RIVER] Note that tiles for which <code style="color:darkgreen">nearby_tile_is_water</code> is 0 may still have a water class, e.g. industry tiles with water beneath them.
|-
| nearby_tile_height
| x- and y-offset (both signed, range -8..7)
| 0..255 (currently limited to 0..15)
| Height of the lowest corner of the tile. 1 unit is one height level of 8 pixels.
|-
| nearby_tile_class
| x- and y-offset (both signed, range -8..7)
|
[[NML:List of tile classes|Tile class]]
|
|-
| nearby_tile_animation_frame
| x- and y-offset (both signed, range -8..7)
| 0..255
| Animation frame of the given tile
|-
| cargo_accepted_nearby_ever
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby">Cargo type should be from your cargo translation table. X- and y-offset are optional, if provided both must be in range -128..127. A station is considered nearby if the tile is in the station's acceptance area. This is the purpose of the x- and y-offset, as other tiles may have other stations nearby.</ref>
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was ever accepted at a nearby station, 0 otherwise
|-
| cargo_accepted_nearby_last_month
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was accepted at a nearby station in the last month, 0 otherwise
|-
| cargo_accepted_nearby_this_month
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was ever accepted at a nearby station in this month, 0 otherwise
|-
| cargo_accepted_nearby_last_bigtick
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was ever accepted at a nearby station since the last periodic processing, which happens every 250 ticks. 0 otherwise
|-
| cargo_accepted_nearby_watched
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was one of the cargo types that triggered the <code style="color:darkgreen">watched_cargo_accepted</code>-callback (only during this callback), 0 otherwise
|-
| nearest_house_matching_criterion
| radius (1..63) and criterion (SEARCH_HOUSE_BY_XXX, XXX = [<nowiki>ID | CLASS | GRFID</nowiki>])
| 1..63, or 0 if not found
| Perform a circular search for a house matching either the id, <code style="color:darkgreen">building_class</code> or GRFID of this house, depending on the second parameter. The first parameter specifies the maximum search radius. Return value is the Manhattan distance of the closest matching house tile, or 0 if no match was found. Note that tiles of the originating house never match.
|-
| nearby_tile_house_id
| x- and y-offset (both signed, range -8..7)
| -1, or 0 .. 767
| Return value is -1 if the tile is not a house tile, X (0..255) if the tile contains old house type X, 256+X if the tile contains a house from this NewGRF with ID X, 512+X if the tile contains a house from a different NewGRF with ID X.
|-
| nearby_tile_house_class
| x- and y-offset (both signed, range -8..7)
| -1, 0, or 256 .. 767
| Return value is -1 if the tile is not a house tile, 0 if the house tile does not have a class (this includes all old house types), 256+X (X = 0..255) if the house has been defined by this NewGRF with <code style="color:darkgreen">building_class</code> X or 512+X if the house has been defined by a different NewGRF with <code style="color:darkgreen">building_class</code> X.
|-
| nearby_tile_house_grfid
| x- and y-offset (both signed, range -8..7)
| -1, 0 or a GRFID
| Return value is -1 if the tile is not a house tile, 0 if the house tile contains an old house type, or else the GRFID of the NewGRF defining the house.
|}
<references/>

==House callbacks==

{| class="t"
! callback
! return value
! comment
|-
| default
| Sprite layout
| Graphics for the house tile
|-
| random_trigger
| N/A
|
See [[NML:Random switch|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. <code>extra_callback_info1</code> contains 32 random bits, if enabled in the <code>building_flags</code> property. Returning a sound effect in the high byte will cause that sound effect to be played.
|-
| anim_control
| Next animation frame or CB_RESULT_XXX
| Called every 256 ticks. 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. <code>extra_callback_info1</code> contains 32 random bits. The low 16 bits are always different for each house tile, but the high 16 bits are the same for each tile if synchronized animation is enabled in the <code>building_flags</code>-property. Returning a sound effect in the high byte will cause that sound effect to be played.
|-
| construction_anim
| Same as <code>anim_control</code>
| Works the same as the <code>anim_control</code> callback, except that it's called when the construction state changes.
|-
| watched_cargo_accepted
| Same as <code>anim_control</code>
| Works the same as the <code>anim_control</code> callback, except that it's called when one of the watched cargo types is accepted.
|-
| 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 <code>accepted_cargo</code> 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 the acceptance properties are used instead. Cargo types are from the <code>cargo_type_accept</code> callback, or the <code>accepted_cargo</code> 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.
|-
| cargo_production
| (cargo_type * 256) + amount
| Called every 256 ticks. Called multiple times until 0x20FF is returned. The high byte of the result contains a cargo type, the low byte contains the amount of that cargo to produce. <code>extra_callback_info1</code> contains the number of iterations so far, <code>extra_callback_info2</code> contains random bits.
|-
| 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.
|-
| name
| String
| Name of the building (when using tile query tool)
|-
| colour
| Palette number
|
Used to recolour the building. See here [[NML:List of default colour translation palettes|here]] for an overview of default palettes.
|-
| construction_check
| 0 or 1
| Return 1 to allow building the house or 0 to disallow.
|-
| destruction
| 0 or 1
| Called periodically. Return 0 to keep the building or 1 to destroy it.
|-
| protection
| 0 or 1
| Return 0 to allow destruction, or 1 to disallow
|}

NML:Houses

2012-09-02T17:46:17Z

Hirundo: /* House callbacks */ Improve documentation of animation callbacks

{{NMLNavPropVarCB}}

==House properties==

{| class="t"
! property
! value range
! comment
|-
| name
| string
| for example string(STR_NAME_EIFFEL_TOWER)
|-
| substitute
| 0 ... 109
| Number of the default house that replaces this one, if this house 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, except for the church / stadium flags (see below). The old house must have the same size as the new house, see the list of [[NML:List_of_default_house_properties|default house types]] for a list of possible substitute IDs.
|-
| override
| 0 ... 109
| id of the default house which this house replaces. This will cause your house to be placed instead of the default house. This is ignored, if the default house has already been overridden. You can define this property multiple times. Your house and the overridden house must have the same size, see the list of [[NML:List_of_default_house_properties|default house types]].
|-
| building_flags.
| bitmask(HOUSE_FLAG_XXX,...)
|
;HOUSE_FLAG_NOT_SLOPED
:Can only be built on flat terrain. Note that 2x2 buildings will always only be built on flat land, even if this bit isn't set.
;HOUSE_FLAG_ANIMATE
:Enable animation
;HOUSE_FLAG_CHURCH
:House is a church (only 1 will be built per town)
;HOUSE_FLAG_STADIUM
:House is a stadium (only 1 will be built per town)
;HOUSE_FLAG_ONLY_SE
:Can only be built in the scenario editor
;HOUSE_FLAG_PROTECTED
:Will not be removed by the game
;HOUSE_FLAG_SYNC_CALLBACK
:Animation callback <code style="color:darkgreen">anim_control</code> is called at the same time for all tiles.
;HOUSE_FLAG_RANDOM_ANIMATION
:Enable random bits in the <code style="color:darkgreen">anim_next_frame</code>-callback.
|-
| population
| 0 ... 255
| number of inhabitants the building adds to the town, if present
|-
| mail_multiplier
| 0 ... 255
|
|-
| pax_acceptance
| 0 ... 1
| Can be increased in steps of 0.125. A station accepts a cargo, if the combined acceptance of all houses in range is at least 1.
|-
| mail_acceptance
| 0 ... 1
|
|-
| cargo_acceptance
| 0 ... 1
| Like passenger acceptance. Additionally flag can be added which defines one of the cargo type
;HOUSE_ACCEPT_GOODS
;HOUSE_ACCEPT_FOOD
;HOUSE_ACCEPT_FIZZY_DRINKS
:FIZZY_DRINKS has in toyland the same meaning as FOOD in other climates.
|-
| accepted_cargo
|
| up to three cargo labels, e.g. MAIL, PASS, COAL
|-
| local_authority_impact
| 0 ... 65525
| amount of happiness decrease of the city council, if the building is destroyed. Town ratings can vary between -1000 (appalling) and +1000 (outstanding).
|-
| removal_cost_multiplier
| 0 ... 255
|
|-
| probability
| 0 ... 16 (float)
| Probability with respect to the default houses (=1). Mind that these are relative probabilities with respect to all houses defined. If all probabilities are defined as 16, they'll all have the same probability as if they had all a probability of 1.
|-
| years_available
| array of two int
| [xx, yy] where xx and yy indicate the introduction year and the last year the building can be built
|-
| minimum_lifetime
| 0 ... 255
| number of years the building will remain at least
|-
| availability_mask
|
[bitmask([[NML:List of town zones|town zones]]), bitmask(CLIMATE_XXX, ...)]
|
An array with two bitmasks, the first bitmask is a mask of town zones where this house is available. The second bitmask is a mask of climates combined with the special value ABOVE_SNOWLINE which you need to set for houses available in the arctic climate above the snowline. Examples:

* Available in the centre town zone in toyland only: <code>[bitmask(TOWNZONE_CENTRE), bitmask(CLIMATE_TOYLAND)]</code>
* Available in all town zones in the arctic climate both above and below the snowline: <code>[ALL_TOWNZONES, bitmask(CLIMATE_ARCTIC, ABOVE_SNOWLINE)]</code>
* Available everywhere except on the town edge: <code>[ALL_TOWNZONES & ~bitmask(TOWNZONE_EDGE), ALL_CLIMATES | bitmask(ABOVE_SNOWLINE)</code>
|-
| callback_flags
| bitmask(HOUSE_CBF_XX)
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| random_colours
| array of 4, each COLOUR_XXX
|
colour values in an array, refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for a list of possible values.
|-
| refresh_multiplier
| 0 ... 63
| Defines the frequency with which the tile will be re-randomized which has an impact for random animation.
|-
| animation_info
| Array [ANIMATION_XXX, frame-count]
|
Type of animation and its length (1...128 frames):

;ANIMATION_LOOPING
;ANIMATION_NON_LOOPING
|-
| animation_speed
| 2 ... 16
|
Speed of animation, see [[NML:Animation speed|animation speed table]] for the meaning of the values.
|-
| building_class
| 0 .. 255
| An arbitrary number. You can check for the presence of buildings of the same class when building new buildings or using animation
|
|-
| watched_cargo_types
| array of values from your [[NML:Cargotable|cargo table]]
| {{ottdp|1.2|2.6|ottdrev=r23072|ttdprev=r1677}}List of cargo types to watch, to be used with the <code style:darkgreen>watched_cargo_accepted</code> callback.
|}

==House variables==

{| class="t"
! name
! value range
! comment
|-
| construction_state
| 0..3
| Current construction state of the industry tile
|-
| pseudo_random_bits
| 0..3
| Some pseudo-random bits, based on the tile position. TTD houses use this to randomize their appearance.
|-
| age
| 0..255
| Age of the house in years, limited to 255
|-
| town_zone
|
[[NML:List of town zones|town zone]]
| The town zone of the current tile
|-
| terrain_type
| TILETYPE_XX
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|-
| same_house_count_town
| 0..255
| Number of the houses with the same ID in the same town as this house
|-
| same_house_count_map
| 0..255
| Number of the houses with the same ID on the entire map
|-
| same_class_count_town
| 0..255
| Number of the houses with the same <code style="color:darkgreen">building_class</code> in the same town as this house
|-
| same_class_count_map
| 0..255
| Number of the houses with the same <code style="color:darkgreen">building_class</code> on the entire map
|-
| generating_town
| [0 <nowiki>|</nowiki> 1]
| 1 a random town is currently being created, 0 otherwise. Note that while generating a random town, [[NML:Towns#Town variables|town variables]] <code style="color:darkgreen">population</code> and <code style="color:darkgreen">building_count</code> are incorrect. The population variable contains the population of buildings generated ''yet'', the final value may be larger. The building_count is surely higher than the final value will be.
|-
| animation_frame
| 0..255
| Current animation frame
|-
| x_coordinate
| 0..2047
| X-coordinate (top right -> bottom left) of the tile on the map
|-
| y_coordinate
| 0..2047
| Y-coordinate (top left -> bottom right) of the tile on the map
|}

The following variables require one or more arguments
{| class="t"
! name
! arguments
! value range
! comment
|-
| old_house_count_town
| ID of old house type (0..109)
| 0..255
| Number of old houses with a given ID in the same town as the current house
|-
| old_house_count_town
| ID of old house type (0..109)
| 0..255
| Number of old houses with a given ID on the whole map
|-
| other_house_count_town
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses with a given ID in the same town as the current house
|-
| other_house_count_map
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses with a given ID on the whole map
|-
| other_class_count_town
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses, with the same class as the house with the given ID, in the same town as the current house
|-
| other_class_count_map
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses, with the same class as the house with the given ID, on the whole map
|-
| nearby_tile_slope
| x- and y-offset (both signed, range -8..7)
| SLOPE_XXX
| See [[NML:List of tile slopes|tile slopes]] for an overview of possible values
|-
| nearby_tile_is_water
| x- and y-offset (both signed, range -8..7)
| [0 <nowiki>|</nowiki> 1]
| 1 if the tile is water, 0 otherwise
|-
| nearby_tile_terrain_type
| x- and y-offset (both signed, range -8..7)
| TILETYPE_XX
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|-
| nearby_tile_water_class
| x- and y-offset (both signed, range -8..7)
| WATER_CLASS_XXX
| XXX = [NONE <nowiki>|</nowiki> SEA <nowiki>|</nowiki> CANAL <nowiki>|</nowiki> RIVER] Note that tiles for which <code style="color:darkgreen">nearby_tile_is_water</code> is 0 may still have a water class, e.g. industry tiles with water beneath them.
|-
| nearby_tile_height
| x- and y-offset (both signed, range -8..7)
| 0..255 (currently limited to 0..15)
| Height of the lowest corner of the tile. 1 unit is one height level of 8 pixels.
|-
| nearby_tile_class
| x- and y-offset (both signed, range -8..7)
|
[[NML:List of tile classes|Tile class]]
|
|-
| nearby_tile_animation_frame
| x- and y-offset (both signed, range -8..7)
| 0..255
| Animation frame of the given tile
|-
| cargo_accepted_nearby_ever
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby">Cargo type should be from your cargo translation table. X- and y-offset are optional, if provided both must be in range -128..127. A station is considered nearby if the tile is in the station's acceptance area. This is the purpose of the x- and y-offset, as other tiles may have other stations nearby.</ref>
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was ever accepted at a nearby station, 0 otherwise
|-
| cargo_accepted_nearby_last_month
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was accepted at a nearby station in the last month, 0 otherwise
|-
| cargo_accepted_nearby_this_month
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was ever accepted at a nearby station in this month, 0 otherwise
|-
| cargo_accepted_nearby_last_bigtick
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was ever accepted at a nearby station since the last periodic processing, which happens every 250 ticks. 0 otherwise
|-
| cargo_accepted_nearby_watched
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was one of the cargo types that triggered the <code style="color:darkgreen">watched_cargo_accepted</code>-callback (only during this callback), 0 otherwise
|-
| nearest_house_matching_criterion
| radius (1..63) and criterion (SEARCH_HOUSE_BY_XXX, XXX = [<nowiki>ID | CLASS | GRFID</nowiki>])
| 1..63, or 0 if not found
| Perform a circular search for a house matching either the id, <code style="color:darkgreen">building_class</code> or GRFID of this house, depending on the second parameter. The first parameter specifies the maximum search radius. Return value is the Manhattan distance of the closest matching house tile, or 0 if no match was found. Note that tiles of the originating house never match.
|-
| nearby_tile_house_id
| x- and y-offset (both signed, range -8..7)
| -1, or 0 .. 767
| Return value is -1 if the tile is not a house tile, X (0..255) if the tile contains old house type X, 256+X if the tile contains a house from this NewGRF with ID X, 512+X if the tile contains a house from a different NewGRF with ID X.
|-
| nearby_tile_house_class
| x- and y-offset (both signed, range -8..7)
| -1, 0, or 256 .. 767
| Return value is -1 if the tile is not a house tile, 0 if the house tile does not have a class (this includes all old house types), 256+X (X = 0..255) if the house has been defined by this NewGRF with <code style="color:darkgreen">building_class</code> X or 512+X if the house has been defined by a different NewGRF with <code style="color:darkgreen">building_class</code> X.
|-
| nearby_tile_house_grfid
| x- and y-offset (both signed, range -8..7)
| -1, 0 or a GRFID
| Return value is -1 if the tile is not a house tile, 0 if the house tile contains an old house type, or else the GRFID of the NewGRF defining the house.
|}
<references/>

==House callbacks==

{| class="t"
! callback
! return value
! comment
|-
| default
| Sprite layout
| Graphics for the house tile
|-
| random_trigger
| N/A
|
See [[NML:Random switch|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. <code>extra_callback_info1</code> contains 32 random bits, if enabled in the <code>building_flags</code> property. Returning a sound effect in the high byte will cause that sound effect to be played.
|-
| anim_control
| Next animation frame or CB_RESULT_XXX
| Called every 256 ticks. 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. <code>extra_callback_info1</code> contains 32 random bits. The low 16 bits are always different for each house tile, but the high 16 bits are the same for each tile if synchronized animation is enabled in the <code>building_flags</code>-property. Returning a sound effect in the high byte will cause that sound effect to be played.
|-
| construction_anim
| Same as <code>anim_control</code>
| Works the same as the <code>anim_control</code> callback, except that it's called when the construction state changes.
|-
| watched_cargo_accepted
| Same as <code>anim_control</code>
| Works the same as the <code>anim_control</code> callback, except that it's called when one of the watched cargo types is accepted.
|-
| 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 <code>accepted_cargo</code> 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 the acceptance properties are used instead. Cargo types are from the <code>cargo_type_accept</code> callback, or the <code>accepted_cargo</code> 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.
|-
| cargo_production
| (cargo_type * 256) + amount
| Called every 256 ticks. Called multiple times until 0x20FF is returned. The high byte of the result contains a cargo type, the low byte contains the amount of that cargo to produce. <code>extra_callback_info1</code> contains the number of iterations so far, <code>extra_callback_info2</code> contains random bits.
|-
| 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.
|-
| name
| String
| Name of the building (when using tile query tool)
|-
| colour
| Palette number
|
Used to recolour the building. See here [[NML:List of default colour translation palettes|here]] for an overview of default palettes.
|-
| construction_check
| 0 or 1
| Return 1 to allow building the house or 0 to disallow.
|-
| destruction
| 0 or 1
| Called periodically. Return 0 to keep the building or 1 to destroy it.
|-
| protection
| 0 or 1
| Return 0 to allow destruction, or 1 to disallow
|}

NML:Houses

2012-09-02T17:43:10Z

Hirundo: /* House properties */ Add notes about substitute/override types having same size. Update building_flags documentation.

{{NMLNavPropVarCB}}

==House properties==

{| class="t"
! property
! value range
! comment
|-
| name
| string
| for example string(STR_NAME_EIFFEL_TOWER)
|-
| substitute
| 0 ... 109
| Number of the default house that replaces this one, if this house 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, except for the church / stadium flags (see below). The old house must have the same size as the new house, see the list of [[NML:List_of_default_house_properties|default house types]] for a list of possible substitute IDs.
|-
| override
| 0 ... 109
| id of the default house which this house replaces. This will cause your house to be placed instead of the default house. This is ignored, if the default house has already been overridden. You can define this property multiple times. Your house and the overridden house must have the same size, see the list of [[NML:List_of_default_house_properties|default house types]].
|-
| building_flags.
| bitmask(HOUSE_FLAG_XXX,...)
|
;HOUSE_FLAG_NOT_SLOPED
:Can only be built on flat terrain. Note that 2x2 buildings will always only be built on flat land, even if this bit isn't set.
;HOUSE_FLAG_ANIMATE
:Enable animation
;HOUSE_FLAG_CHURCH
:House is a church (only 1 will be built per town)
;HOUSE_FLAG_STADIUM
:House is a stadium (only 1 will be built per town)
;HOUSE_FLAG_ONLY_SE
:Can only be built in the scenario editor
;HOUSE_FLAG_PROTECTED
:Will not be removed by the game
;HOUSE_FLAG_SYNC_CALLBACK
:Animation callback <code style="color:darkgreen">anim_control</code> is called at the same time for all tiles.
;HOUSE_FLAG_RANDOM_ANIMATION
:Enable random bits in the <code style="color:darkgreen">anim_next_frame</code>-callback.
|-
| population
| 0 ... 255
| number of inhabitants the building adds to the town, if present
|-
| mail_multiplier
| 0 ... 255
|
|-
| pax_acceptance
| 0 ... 1
| Can be increased in steps of 0.125. A station accepts a cargo, if the combined acceptance of all houses in range is at least 1.
|-
| mail_acceptance
| 0 ... 1
|
|-
| cargo_acceptance
| 0 ... 1
| Like passenger acceptance. Additionally flag can be added which defines one of the cargo type
;HOUSE_ACCEPT_GOODS
;HOUSE_ACCEPT_FOOD
;HOUSE_ACCEPT_FIZZY_DRINKS
:FIZZY_DRINKS has in toyland the same meaning as FOOD in other climates.
|-
| accepted_cargo
|
| up to three cargo labels, e.g. MAIL, PASS, COAL
|-
| local_authority_impact
| 0 ... 65525
| amount of happiness decrease of the city council, if the building is destroyed. Town ratings can vary between -1000 (appalling) and +1000 (outstanding).
|-
| removal_cost_multiplier
| 0 ... 255
|
|-
| probability
| 0 ... 16 (float)
| Probability with respect to the default houses (=1). Mind that these are relative probabilities with respect to all houses defined. If all probabilities are defined as 16, they'll all have the same probability as if they had all a probability of 1.
|-
| years_available
| array of two int
| [xx, yy] where xx and yy indicate the introduction year and the last year the building can be built
|-
| minimum_lifetime
| 0 ... 255
| number of years the building will remain at least
|-
| availability_mask
|
[bitmask([[NML:List of town zones|town zones]]), bitmask(CLIMATE_XXX, ...)]
|
An array with two bitmasks, the first bitmask is a mask of town zones where this house is available. The second bitmask is a mask of climates combined with the special value ABOVE_SNOWLINE which you need to set for houses available in the arctic climate above the snowline. Examples:

* Available in the centre town zone in toyland only: <code>[bitmask(TOWNZONE_CENTRE), bitmask(CLIMATE_TOYLAND)]</code>
* Available in all town zones in the arctic climate both above and below the snowline: <code>[ALL_TOWNZONES, bitmask(CLIMATE_ARCTIC, ABOVE_SNOWLINE)]</code>
* Available everywhere except on the town edge: <code>[ALL_TOWNZONES & ~bitmask(TOWNZONE_EDGE), ALL_CLIMATES | bitmask(ABOVE_SNOWLINE)</code>
|-
| callback_flags
| bitmask(HOUSE_CBF_XX)
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| random_colours
| array of 4, each COLOUR_XXX
|
colour values in an array, refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for a list of possible values.
|-
| refresh_multiplier
| 0 ... 63
| Defines the frequency with which the tile will be re-randomized which has an impact for random animation.
|-
| animation_info
| Array [ANIMATION_XXX, frame-count]
|
Type of animation and its length (1...128 frames):

;ANIMATION_LOOPING
;ANIMATION_NON_LOOPING
|-
| animation_speed
| 2 ... 16
|
Speed of animation, see [[NML:Animation speed|animation speed table]] for the meaning of the values.
|-
| building_class
| 0 .. 255
| An arbitrary number. You can check for the presence of buildings of the same class when building new buildings or using animation
|
|-
| watched_cargo_types
| array of values from your [[NML:Cargotable|cargo table]]
| {{ottdp|1.2|2.6|ottdrev=r23072|ttdprev=r1677}}List of cargo types to watch, to be used with the <code style:darkgreen>watched_cargo_accepted</code> callback.
|}

==House variables==

{| class="t"
! name
! value range
! comment
|-
| construction_state
| 0..3
| Current construction state of the industry tile
|-
| pseudo_random_bits
| 0..3
| Some pseudo-random bits, based on the tile position. TTD houses use this to randomize their appearance.
|-
| age
| 0..255
| Age of the house in years, limited to 255
|-
| town_zone
|
[[NML:List of town zones|town zone]]
| The town zone of the current tile
|-
| terrain_type
| TILETYPE_XX
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|-
| same_house_count_town
| 0..255
| Number of the houses with the same ID in the same town as this house
|-
| same_house_count_map
| 0..255
| Number of the houses with the same ID on the entire map
|-
| same_class_count_town
| 0..255
| Number of the houses with the same <code style="color:darkgreen">building_class</code> in the same town as this house
|-
| same_class_count_map
| 0..255
| Number of the houses with the same <code style="color:darkgreen">building_class</code> on the entire map
|-
| generating_town
| [0 <nowiki>|</nowiki> 1]
| 1 a random town is currently being created, 0 otherwise. Note that while generating a random town, [[NML:Towns#Town variables|town variables]] <code style="color:darkgreen">population</code> and <code style="color:darkgreen">building_count</code> are incorrect. The population variable contains the population of buildings generated ''yet'', the final value may be larger. The building_count is surely higher than the final value will be.
|-
| animation_frame
| 0..255
| Current animation frame
|-
| x_coordinate
| 0..2047
| X-coordinate (top right -> bottom left) of the tile on the map
|-
| y_coordinate
| 0..2047
| Y-coordinate (top left -> bottom right) of the tile on the map
|}

The following variables require one or more arguments
{| class="t"
! name
! arguments
! value range
! comment
|-
| old_house_count_town
| ID of old house type (0..109)
| 0..255
| Number of old houses with a given ID in the same town as the current house
|-
| old_house_count_town
| ID of old house type (0..109)
| 0..255
| Number of old houses with a given ID on the whole map
|-
| other_house_count_town
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses with a given ID in the same town as the current house
|-
| other_house_count_map
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses with a given ID on the whole map
|-
| other_class_count_town
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses, with the same class as the house with the given ID, in the same town as the current house
|-
| other_class_count_map
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses, with the same class as the house with the given ID, on the whole map
|-
| nearby_tile_slope
| x- and y-offset (both signed, range -8..7)
| SLOPE_XXX
| See [[NML:List of tile slopes|tile slopes]] for an overview of possible values
|-
| nearby_tile_is_water
| x- and y-offset (both signed, range -8..7)
| [0 <nowiki>|</nowiki> 1]
| 1 if the tile is water, 0 otherwise
|-
| nearby_tile_terrain_type
| x- and y-offset (both signed, range -8..7)
| TILETYPE_XX
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|-
| nearby_tile_water_class
| x- and y-offset (both signed, range -8..7)
| WATER_CLASS_XXX
| XXX = [NONE <nowiki>|</nowiki> SEA <nowiki>|</nowiki> CANAL <nowiki>|</nowiki> RIVER] Note that tiles for which <code style="color:darkgreen">nearby_tile_is_water</code> is 0 may still have a water class, e.g. industry tiles with water beneath them.
|-
| nearby_tile_height
| x- and y-offset (both signed, range -8..7)
| 0..255 (currently limited to 0..15)
| Height of the lowest corner of the tile. 1 unit is one height level of 8 pixels.
|-
| nearby_tile_class
| x- and y-offset (both signed, range -8..7)
|
[[NML:List of tile classes|Tile class]]
|
|-
| nearby_tile_animation_frame
| x- and y-offset (both signed, range -8..7)
| 0..255
| Animation frame of the given tile
|-
| cargo_accepted_nearby_ever
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby">Cargo type should be from your cargo translation table. X- and y-offset are optional, if provided both must be in range -128..127. A station is considered nearby if the tile is in the station's acceptance area. This is the purpose of the x- and y-offset, as other tiles may have other stations nearby.</ref>
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was ever accepted at a nearby station, 0 otherwise
|-
| cargo_accepted_nearby_last_month
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was accepted at a nearby station in the last month, 0 otherwise
|-
| cargo_accepted_nearby_this_month
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was ever accepted at a nearby station in this month, 0 otherwise
|-
| cargo_accepted_nearby_last_bigtick
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was ever accepted at a nearby station since the last periodic processing, which happens every 250 ticks. 0 otherwise
|-
| cargo_accepted_nearby_watched
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was one of the cargo types that triggered the <code style="color:darkgreen">watched_cargo_accepted</code>-callback (only during this callback), 0 otherwise
|-
| nearest_house_matching_criterion
| radius (1..63) and criterion (SEARCH_HOUSE_BY_XXX, XXX = [<nowiki>ID | CLASS | GRFID</nowiki>])
| 1..63, or 0 if not found
| Perform a circular search for a house matching either the id, <code style="color:darkgreen">building_class</code> or GRFID of this house, depending on the second parameter. The first parameter specifies the maximum search radius. Return value is the Manhattan distance of the closest matching house tile, or 0 if no match was found. Note that tiles of the originating house never match.
|-
| nearby_tile_house_id
| x- and y-offset (both signed, range -8..7)
| -1, or 0 .. 767
| Return value is -1 if the tile is not a house tile, X (0..255) if the tile contains old house type X, 256+X if the tile contains a house from this NewGRF with ID X, 512+X if the tile contains a house from a different NewGRF with ID X.
|-
| nearby_tile_house_class
| x- and y-offset (both signed, range -8..7)
| -1, 0, or 256 .. 767
| Return value is -1 if the tile is not a house tile, 0 if the house tile does not have a class (this includes all old house types), 256+X (X = 0..255) if the house has been defined by this NewGRF with <code style="color:darkgreen">building_class</code> X or 512+X if the house has been defined by a different NewGRF with <code style="color:darkgreen">building_class</code> X.
|-
| nearby_tile_house_grfid
| x- and y-offset (both signed, range -8..7)
| -1, 0 or a GRFID
| Return value is -1 if the tile is not a house tile, 0 if the house tile contains an old house type, or else the GRFID of the NewGRF defining the house.
|}
<references/>

==House callbacks==

{| class="t"
! callback
! return value
! comment
|-
| default
| Sprite layout
| Graphics for the house tile
|-
| random_trigger
| N/A
|
See [[NML:Random switch|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. <code>extra_callback_info1</code> contains random bits, if enabled in the <code>special_flags</code> property. Returning a sound effect in the high byte will cause that sound effect to be played.
|-
| anim_control
| Next animation frame or CB_RESULT_XXX
| Called every 256 ticks. 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. <code>extra_callback_info1</code> contains random bits, if enabled in the <code>building_flags</code> property. Returning a sound effect in the high byte will cause that sound effect to be played.
|-
| construction_anim
| Same as <code>anim_control</code>
| Works the same as the <code>anim_control</code> callback, except that it's called when the construction state changes.
|-
| watched_cargo_accepted
| Same as <code>anim_control</code>
| Works the same as the <code>anim_control</code> callback, except that it's called when one of the watched cargo types is accepted.
|-
| 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 <code>accepted_cargo</code> 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 the acceptance properties are used instead. Cargo types are from the <code>cargo_type_accept</code> callback, or the <code>accepted_cargo</code> 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.
|-
| cargo_production
| (cargo_type * 256) + amount
| Called every 256 ticks. Called multiple times until 0x20FF is returned. The high byte of the result contains a cargo type, the low byte contains the amount of that cargo to produce. <code>extra_callback_info1</code> contains the number of iterations so far, <code>extra_callback_info2</code> contains random bits.
|-
| 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.
|-
| name
| String
| Name of the building (when using tile query tool)
|-
| colour
| Palette number
|
Used to recolour the building. See here [[NML:List of default colour translation palettes|here]] for an overview of default palettes.
|-
| construction_check
| 0 or 1
| Return 1 to allow building the house or 0 to disallow.
|-
| destruction
| 0 or 1
| Called periodically. Return 0 to keep the building or 1 to destroy it.
|-
| protection
| 0 or 1
| Return 0 to allow destruction, or 1 to disallow
|}

NML:List of default house properties

2012-09-02T17:34:40Z

Hirundo: Separate size and flags

{{NMLNavAdditionalreferences}}

{| class="t"
! Number
! Name
! Climate
! Town zones
! Size
! Minimum year built
! Last year built
! Population
! Mail generation
! Passenger acceptance
! Mail acceptance
! Goods acceptance
! Remove ratings decrease
! Remove cost multiplier
! Flags
|-
| 00
| tall office block
| temperate
| CENTRE
| HOUSE_SIZE_1x1
| 1963
| none
| 187
| 70
| 8
| 3
| 4
| 140
| 150
|
|-
| 01
| office block
| temperate
| INNER_SUBURB, CENTRE
| HOUSE_SIZE_1x1
| 1957
| none
| 85
| 55
| 8
| 3
| 4
| 130
| 140
|
|-
| 02
| small block of flats
| temperate
| OUTSKIRT .. INNER_SUBURB
| HOUSE_SIZE_1x1
| 1968
| none
| 40
| 20
| 8
| 3
| 1
| 90
| 100
|
|-
| 03
| church
| temperate
| EDGE ... INNER_SUBURB
| HOUSE_SIZE_1x1
| 1930
| none
| 5
| 2
| 2
| 0
| 0
| 230
| 90
|
|-
| 04
| large office block
| temperate, sub-arctic, subtropical
| CENTRE
| HOUSE_SIZE_1x1
| 1975
| none
| 220
| 85
| 10
| 4
| 6
| 160
| 160
| HOUSE_FLAG_ANIMATE
|-
| 05
| large office block
| snow
| CENTRE
| HOUSE_SIZE_1x1
| 1975
| none
| 220
| 85
| 10
| 4
| 6
| 160
| 160
| HOUSE_FLAG_ANIMATE
|-
| 06
| town houses
| temperate
| EDGE ... INNER_SUBURB
| HOUSE_SIZE_1x1
| 1930
| none
| 30
| 12
| 4
| 1
| 0
| 80
| 80
|
|-
| 07
| hotel (N part)
| temperate
| OUTER_SUBURB, CENTRE
| HOUSE_SIZE_1x2
| 1959
| none
| 140
| 22
| 6
| 1
| 2
| 150
| 180
|
|-
| 08
| hotel (E part)
|
|
| N/A
| 1959
| none
| 0
| 22
| 6
| 1
| 2
| 150
| 180
|
|-
| 09
| statue
| temperate, sub-arctic, subtropical
| INNER_SUBURB, CENTRE
| HOUSE_SIZE_1x1
| 1945
| none
| 0
| 0
| 2
| 0
| 0
| 40
| 65
|
|-
| 10
| fountain
| temperate, sub-arctic, subtropical
| CENTRE
| HOUSE_SIZE_1x1
| 1945
| none
| 0
| 0
| 2
| 0
| 0
| 40
| 65
|
|-
| 11
| park (with a pond)
| temperate
| OUTER_SUBURB
| HOUSE_SIZE_1x1
| 1930
| none
| 0
| 0
| 2
| 0
| 0
| 75
| 60
|
|-
| 12
| park (with an alley)
| temperate
| INNER_SUBURB
| HOUSE_SIZE_1x1
| 1935
| none
| 0
| 0
| 2
| 0
| 0
| 75
| 60
|
|-
| 13
| office block
| temperate
| INNER_SUBURB, CENTRE
| HOUSE_SIZE_1x1
| 1951
| none
| 150
| 65
| 8
| 2
| 4
| 110
| 130
|
|-
| 14
| shops and offices 1
| temperate
| OUTER_SUBURB ... CENTRE
| HOUSE_SIZE_1x1
| 1930
| 1960
| 95
| 48
| 6
| 2
| 3
| 100
| 110
|
|-
| 15
| shops and offices 2
| temperate
| OUTER_SUBURB ... CENTRE
| HOUSE_SIZE_1x1
| 1930
| 1960
| 95
| 48
| 6
| 2
| 3
| 100
| 105
|
|-
| 16
| shops and offices 3
| temperate
| OUTER_SUBURB ... CENTRE
| HOUSE_SIZE_1x1
| 1930
| 1960
| 95
| 48
| 6
| 2
| 3
| 100
| 107
|
|-
| 17
| modern office building
| temperate, sub-arctic, subtropical
| CENTRE
| HOUSE_SIZE_1x1
| 1977
| none
| 130
| 50
| 10
| 3
| 6
| 150
| 200
|
|-
| 18
| warehouse
| temperate
| CENTRE
| HOUSE_SIZE_1x1
| 1983
| none
| 6
| 10
| 6
| 3
| 8
| 110
| 145
|
|-
| 19
| office block (with spiral stairway)
| temperate
| CENTRE
| HOUSE_SIZE_1x1
| 1985
| none
| 110
| 55
| 6
| 2
| 6
| 110
| 155
|
|-
| 20
| stadium (N part)
| temperate
| EDGE ... INNER_SUBURB
| HOUSE_SIZE_2x2
| 1930
| none
| 65
| 5
| 4
| 0
| 0
| 300
| 250
|
|-
| 21
| stadium (E part)
|
|
| N/A
| 1930
| none
| 0
| 5
| 4
| 0
| 0
| 300
| 250
|
|-
| 22
| stadium (W part)
|
|
| N/A
| 1930
| none
| 0
| 5
| 4
| 0
| 0
| 300
| 250
|
|-
| 23
| stadium (S part)
|
|
| N/A
| 1930
| none
| 0
| 5
| 4
| 0
| 0
| 300
| 250
|
|-
| 24
| old houses
| temperate
| EDGE, OUTSKIRT
| HOUSE_SIZE_1x1
| 1930
| 1951
| 15
| 6
| 3
| 1
| 0
| 75
| 70
|
|-
| 25
| cottages
| temperate
| EDGE
| HOUSE_SIZE_1x1
| 1930
| 1952
| 12
| 7
| 3
| 1
| 0
| 75
| 75
|
|-
| 26
| houses
| temperate
| EDGE ... INNER_SUBURB
| HOUSE_SIZE_1x1
| 1931
| none
| 13
| 8
| 3
| 1
| 0
| 75
| 71
|
|-
| 27
| flats
| temperate
| OUTER_SUBURB ... CENTRE
| HOUSE_SIZE_1x1
| 1935
| none
| 100
| 35
| 7
| 2
| 2
| 100
| 135
|
|-
| 28
| tall office block
| temperate
| OUTER_SUBURB ... CENTRE
| HOUSE_SIZE_1x1
| 1963
| none
| 170
| 50
| 8
| 3
| 3
| 170
| 145
|
|-
| 29
| shops and offices
| temperate
| OUTER_SUBURB ... CENTRE
| HOUSE_SIZE_1x1
| 1930
| 1955
| 100
| 40
| 6
| 2
| 3
| 135
| 132
|
|-
| 30
| shops and offices
| temperate, subtropical
| OUTER_SUBURB, CENTRE
| HOUSE_SIZE_1x1
| 1973
| none
| 180
| 64
| 8
| 3
| 3
| 180
| 155
|
|-
| 31
| theatre
| temperate
| INNER_SUBURB, CENTRE
| HOUSE_SIZE_1x1
| 1930
| none
| 35
| 23
| 8
| 2
| 2
| 230
| 220
|
|-
| 32
| stadium (modern style, N part)
| temperate, sub-arctic, subtropical
| EDGE ... INNER_SUBURB
| HOUSE_SIZE_2x2
| 1958
| none
| 65
| 5
| 4
| 0
| 0
| 300
| 250
|
|-
| 33
| stadium (modern style, E part)
|
|
| N/A
| 1958
| none
| 0
| 5
| 4
| 0
| 0
| 300
| 250
|
|-
| 34
| stadium (modern style, W part)
|
|
| N/A
| 1958
| none
| 0
| 5
| 4
| 0
| 0
| 300
| 250
|
|-
| 35
| stadium (modern style, S part)
|
|
| N/A
| 1958
| none
| 0
| 5
| 4
| 0
| 0
| 300
| 250
|
|-
| 36
| offices ('vertical tube' style)
| temperate, sub-arctic, subtropical
| INNER_SUBURB, CENTRE
| HOUSE_SIZE_1x1
| 2000
| none
| 140
| 65
| 8
| 3
| 2
| 250
| 170
|
|-
| 37
| houses
| sub-arctic
| EDGE, OUTSKIRT
| HOUSE_SIZE_1x1
| 1930
| 1960
| 15
| 6
| 3
| 1
| -1
| 75
| 70
|
|-
| 38
| houses
| snow
| EDGE, OUTSKIRT
| HOUSE_SIZE_1x1
| 1930
| 1960
| 15
| 6
| 3
| 1
| -1
| 75
| 70
|
|-
| 39
| cinema
| temperate
| OUTER_SUBURB ... CENTRE
| HOUSE_SIZE_1x1
| 1945
| none
| 35
| 23
| 8
| 2
| 2
| 230
| 210
|
|-
| 40
| shopping mall (N part)
| temperate
| OUTSKIRT ... CENTRE
| HOUSE_SIZE_2x2
| 1983
| none
| 180
| 5
| 8
| 2
| 3
| 300
| 250
|
|-
| 41
| shopping mall (E part)
|
|
| N/A
| 1983
| none
| 0
| 5
| 8
| 2
| 3
| 300
| 250
|
|-
| 42
| shopping mall (W part)
|
|
| N/A
| 1983
| none
| 0
| 5
| 8
| 2
| 3
| 300
| 250
|
|-
| 43
| shopping mall (S part)
|
|
| N/A
| 1983
| none
| 0
| 5
| 8
| 2
| 3
| 300
| 250
|
|-
| 44
| flats
| sub-arctic
| OUTER_SUBURB ... CENTRE
| HOUSE_SIZE_1x1
| 1930
| none
| 80
| 20
| 5
| 2
| -2
| 90
| 100
|
|-
| 45
| flats
| snow
| OUTER_SUBURB ... CENTRE
| HOUSE_SIZE_1x1
| 1930
| none
| 80
| 20
| 5
| 2
| -2
| 90
| 100
|
|-
| 46
| houses
| sub-arctic
| EDGE ... INNER_SUBURB
| HOUSE_SIZE_1x1
| 1930
| none
| 16
| 6
| 3
| 1
| -2
| 70
| 70
|
|-
| 47
| houses
| snow
| EDGE ... INNER_SUBURB
| HOUSE_SIZE_1x1
| 1930
| none
| 16
| 6
| 3
| 1
| -2
| 70
| 70
|
|-
| 48
| houses
| sub-arctic
| EDGE ... OUTER_SUBURB
| HOUSE_SIZE_1x1
| 1930
| 1963
| 14
| 6
| 3
| 1
| -2
| 70
| 80
|
|-
| 49
| houses
| snow
| EDGE ... OUTER_SUBURB
| HOUSE_SIZE_1x1
| 1930
| 1963
| 14
| 6
| 3
| 1
| -2
| 70
| 80
|
|-
| 50
| tall office block
| sub-arctic, subtropical
| INNER_OUTSKIRT, CENTRE
| HOUSE_SIZE_1x1
| 1966
| none
| 135
| 60
| 8
| 3
| 4
| 120
| 150
|
|-
| 51
| tall office block
| snow
| INNER_SUBURB, CENTRE
| HOUSE_SIZE_1x1
| 1966
| none
| 135
| 60
| 8
| 3
| 4
| 120
| 150
|
|-
| 52
| tall office block
| sub-arctic
| INNER_SUBURB, CENTRE
| HOUSE_SIZE_1x1
| 1970
| none
| 170
| 70
| 9
| 3
| 4
| 130
| 170
|
|-
| 53
| tall office block
| snow
| INNER_SUBURB, CENTRE
| HOUSE_SIZE_1x1
| 1970
| none
| 170
| 70
| 9
| 3
| 4
| 130
| 170
|
|-
| 54
| tall office block
| sub-arctic, subtropical
| INNER_SUBURB, CENTRE
| HOUSE_SIZE_1x1
| 1974
| none
| 210
| 80
| 10
| 3
| 5
| 140
| 200
|
|-
| 55
| tall office block
| snow
| INNER_SUBURB, CENTRE
| HOUSE_SIZE_1x1
| 1974
| none
| 210
| 80
| 10
| 3
| 5
| 140
| 200
|
|-
| 56
| houses
| sub-arctic
| EDGE
| HOUSE_SIZE_1x1
| 1930
| none
| 10
| 5
| 2
| 1
| -1
| 60
| 60
|
|-
| 57
| houses
| snow
| EDGE
| HOUSE_SIZE_1x1
| 1930
| none
| 10
| 5
| 2
| 1
| -1
| 60
| 60
|
|-
| 58
| shops and offices
| sub-arctic
| OUTSKIRT ... CENTRE
| HOUSE_SIZE_1x1
| 1930
| none
| 25
| 20
| 3
| 1
| -1
| 80
| 100
|
|-
| 59
| shops and offices
| snow
| OUTSKIRT ... CENTRE
| HOUSE_SIZE_1x1
| 1930
| none
| 25
| 20
| 3
| 1
| -1
| 80
| 100
|
|-
| 60
| church
| sub-arctic
| EDGE ... INNER_SUBURB
| HOUSE_SIZE_1x1
| 1930
| none
| 6
| 2
| 2
| 0
| 0
| 230
| 85
|
|-
| 61
| church
| snow
| EDGE ... INNER_SUBURB
| HOUSE_SIZE_1x1
| 1930
| none
| 6
| 2
| 2
| 0
| 0
| 230
| 85
|
|-
| 62
| houses
| sub-arctic
| EDGE ... OUTER_SUBURB
| HOUSE_SIZE_1x1
| 1930
| none
| 17
| 7
| 3
| 1
| -1
| 80
| 80
|
|-
| 63
| houses
| snow
| EDGE ... OUTER_SUBURB
| HOUSE_SIZE_1x1
| 1930
| none
| 17
| 7
| 3
| 1
| -1
| 80
| 80
|
|-
| 64
| shops and offices
| sub-arctic
| OUTER_SUBURB ... CENTRE
| HOUSE_SIZE_1x1
| 1930
| 1960
| 90
| 45
| 6
| 2
| 3
| 110
| 140
|
|-
| 65
| shops and offices
| snow
| OUTER_SUBURB ... CENTRE
| HOUSE_SIZE_1x1
| 1930
| 1960
| 90
| 45
| 6
| 2
| 3
| 110
| 140
|
|-
| 66
| hotel (N part)
| sub-arctic
| OUTER_SUBURB ... CENTRE
| HOUSE_SIZE_1x2
| 1972
| none
| 140
| 25
| 6
| 1
| -3
| 160
| 160
|
|-
| 67
| hotel (E part)
|
|
| N/A
| 1972
| none
| 0
| 25
| 6
| 1
| 2
| 160
| 160
|
|-
| 68
| hotel (N part)
| snow
| OUTER_SUBURB ... CENTRE
| HOUSE_SIZE_1x2
| 1972
| none
| 140
| 25
| 6
| 1
| -3
| 160
| 160
|
|-
| 69
| hotel (E part)
|
|
| N/A
| 1972
| none
| 0
| 25
| 6
| 1
| 2
| 160
| 160
|
|-
| 70
| shops and offices
| sub-arctic, subtropical
| OUTER_SUBURB ... CENTRE
| HOUSE_SIZE_1x1
| 1963
| none
| 105
| 50
| 7
| 2
| 3
| 105
| 130
|
|-
| 71
| shops and offices
| snow
| OUTER_SUBURB ... CENTRE
| HOUSE_SIZE_1x1
| 1963
| none
| 105
| 50
| 7
| 2
| 3
| 105
| 130
|
|-
| 72
| tall office block
| sub-arctic
| INNER_SUBURB, CENTRE
| HOUSE_SIZE_1x1
| 1978
| none
| 190
| 75
| 9
| 3
| 4
| 135
| 190
|
|-
| 73
| tall office block
| snow
| INNER_SUBURB, CENTRE
| HOUSE_SIZE_1x1
| 1978
| none
| 190
| 75
| 9
| 3
| 4
| 135
| 190
|
|-
| 74
| tall office block (N part)
| sub-arctic
| OUTER_SUBURB ... CENTRE
| HOUSE_SIZE_2x1
| 1967
| none
| 250
| 60
| 7
| 2
| 2
| 200
| 140
|
|-
| 75
| tall office block (W part)
|
|
| N/A
| 1967
| none
| 0
| 60
| 7
| 2
| 2
| 200
| 140
|
|-
| 76
| tall office block (N part)
| snow
| OUTER_SUBURB ... CENTRE
| HOUSE_SIZE_2x1
| 1967
| none
| 250
| 60
| 7
| 2
| 2
| 200
| 140
|
|-
| 77
| tall office block (W part)
|
|
| N/A
| 1967
| none
| 0
| 60
| 7
| 2
| 2
| 200
| 140
|
|-
| 78
| houses (with a tree in a corner)
| subtropical
| OUTSKIRT ... CENTRE
| HOUSE_SIZE_1x1
| 1930
| none
| 16
| 6
| 3
| 1
| -2
| 80
| 80
|
|-
| 79
| houses
| subtropical
| OUTSKIRT ... CENTRE
| HOUSE_SIZE_1x1
| 1930
| none
| 16
| 6
| 3
| 1
| -2
| 80
| 80
|
|-
| 80
| houses
| subtropical
| OUTSKIRT ... CENTRE
| HOUSE_SIZE_1x1
| 1930
| none
| 16
| 5
| 3
| 1
| -2
| 80
| 80
|
|-
| 81
| houses (suburb-type)
| subtropical
| EDGE
| HOUSE_SIZE_1x1
| 1930
| none
| 7
| 4
| 3
| 1
| -1
| 30
| 30
|
|-
| 82
| flats
| subtropical
| OUTER_SUBURB ... CENTRE
| HOUSE_SIZE_1x1
| 1930
| none
| 45
| 15
| 6
| 2
| 1
| 95
| 130
|
|-
| 83
| church
| subtropical
| OUTSKIRT ... INNER_SUBURB
| HOUSE_SIZE_1x1
| 1930
| none
| 8
| 3
| 2
| 0
| 0
| 200
| 90
|
|-
| 84
| houses (with two trees in front)
| subtropical
| OUTSKIRT ... CENTRE
| HOUSE_SIZE_1x1
| 1930
| none
| 18
| 7
| 3
| 1
| -2
| 80
| 80
|
|-
| 85
| flats
| subtropical
| OUTER_SUBURB ... CENTRE
| HOUSE_SIZE_1x1
| 1973
| none
| 90
| 24
| 6
| 2
| 1
| 95
| 110
|
|-
| 86
| flats
| subtropical
| OUTER_SUBURB ... CENTRE
| HOUSE_SIZE_1x1
| 1962
| none
| 120
| 25
| 6
| 2
| 1
| 95
| 120
|
|-
| 87
| tall office block (N part)
| subtropical
| INNER_SUBURB, CENTRE
| HOUSE_SIZE_2x1
| 1984
| none
| 250
| 80
| 8
| 3
| 4
| 140
| 190
|
|-
| 88
| tall office block (W part)
| subtropical
|
| N/A
| 1984
| none
| 0
| 80
| 8
| 3
| 4
| 140
| 190
|
|-
| 89
| flats
| subtropical
| OUTER_SUBURB ... CENTRE
| HOUSE_SIZE_1x1
| 1930
| none
| 80
| 23
| 6
| 2
| 1
| 95
| 110
|
|-
| 90
| tall office block
| subtropical
| INNER_SUBURB, CENTRE
| HOUSE_SIZE_1x1
| 1993
| none
| 180
| 90
| 8
| 3
| 4
| 150
| 180
|
|-
| 91
| church
| toyland
| EDGE ... CENTRE
| HOUSE_SIZE_1x1
| 1930
| none
| 8
| 3
| 2
| 0
| 0
| 200
| 90
|
|-
| 92
| toyland houses
| toyland
| EDGE ... CENTRE
| HOUSE_SIZE_1x1
| 1930
| none
| 18
| 5
| 6
| 2
| 2
| 90
| 90
|
|-
| 93
| toyland houses
| toyland
| EDGE, OUTSKIRT
| HOUSE_SIZE_1x1
| 1930
| none
| 7
| 3
| 3
| 1
| 1
| 50
| 70
|
|-
| 94
| toyland houses
| toyland
| EDGE ... INNER_SUBURB
| HOUSE_SIZE_1x1
| 1930
| none
| 15
| 6
| 3
| 1
| 2
| 75
| 80
|
|-
| 95
| toyland houses
| toyland
| EDGE ... INNER_SUBURB
| HOUSE_SIZE_1x1
| 1930
| none
| 17
| 6
| 3
| 1
| 2
| 75
| 80
|
|-
| 96
| toyland houses
| toyland
| EDGE ... INNER_SUBURB
| HOUSE_SIZE_1x1
| 1930
| none
| 19
| 6
| 3
| 1
| 2
| 75
| 80
|
|-
| 97
| toyland houses
| toyland
| EDGE ... INNER_SUBURB
| HOUSE_SIZE_1x1
| 1930
| none
| 21
| 6
| 3
| 1
| 2
| 75
| 80
|
|-
| 98
| tall office block
| toyland
| OUTER_SUBURB ... CENTRE
| HOUSE_SIZE_1x1
| 1930
| none
| 75
| 20
| 8
| 4
| 2
| 130
| 160
|
|-
| 99
| shoe house (N part)
| toyland
| EDGE ... CENTRE
| HOUSE_SIZE_1x2
| 1930
| none
| 35
| 9
| 4
| 1
| 2
| 80
| 90
|
|-
| 100
| shoe house (E part)
|
|
| N/A
| 1930
| none
| 0
| 0
| 4
| 1
| 2
| 80
| 90
|
|-
| 101
| tall office block
| toyland
| OUTER_SUBURB ... CENTRE
| HOUSE_SIZE_1x1
| 1930
| none
| 85
| 18
| 8
| 4
| 2
| 130
| 150
|
|-
| 102
| igloo
| toyland
| EDGE
| HOUSE_SIZE_1x1
| 1930
| none
| 11
| 3
| 3
| 1
| 1
| 45
| 60
|
|-
| 103
| tepees
| toyland
| EDGE
| HOUSE_SIZE_1x1
| 1930
| none
| 10
| 3
| 3
| 1
| 1
| 45
| 60
|
|-
| 104
| shops and offices
| toyland
| OUTER_SUBURB ... CENTRE
| HOUSE_SIZE_1x1
| 1930
| none
| 67
| 22
| 8
| 4
| -4
| 130
| 140
|
|-
| 105
| shops and offices
| toyland
| OUTER_SUBURB ... CENTRE
| HOUSE_SIZE_1x1
| 1930
| none
| 86
| 23
| 8
| 4
| -4
| 130
| 145
|
|-
| 106
| tall office block
| toyland
| OUTER_SUBURB ... CENTRE
| HOUSE_SIZE_1x1
| 1930
| none
| 95
| 28
| 8
| 4
| 2
| 130
| 165
|
|-
| 107
| statue
| toyland
| OUTER_SUBURB ... CENTRE
| HOUSE_SIZE_1x1
| 1930
| none
| 30
| 10
| 4
| 1
| 2
| 70
| 90
|
|-
| 108
| teapot-house
| toyland
| EDGE ... CENTRE
| HOUSE_SIZE_1x1
| 1930
| none
| 25
| 8
| 3
| 1
| 2
| 65
| 75
|
|-
| 109
| piggy-bank
| toyland
| EDGE ... CENTRE
| HOUSE_SIZE_1x1
| 1930
| none
| 18
| 7
| 3
| 2
| -4
| 95
| 85
|
|}

VariationalAction2/Houses

2012-09-02T10:20:52Z

Hirundo: /* Other building counts (60, 61) */ Property->variable

==Introduction==

== Variables ==

{| |-
!Variable!![[GRFActionsDetailed|'''Size''']]!!Version*!!Description
|-
|40||B||{{ottdp|0.6|2.5}}||Construction stage and pseudo-random values
|-
|41||B||{{ottdp|0.6|2.5}}||Age of the building in years (or, strictly speaking, the difference between the current year and the year the building was built). Returns 255 for buildings older than 255 years.
|-
|42||B||{{ottdp|0.6|2.5|ttdprev=alpha 43}}||Town zone where the building is situated.
|-
|43||B||{{ottdp|0.6|2.5}}||Terrain type: 0 normal, 1 desert, 2 rainforest, 4 on or above snowline
|-
|44||D||{{ottdp|0.6|2.5|ttdprev=alpha 43}}||Building counts
|-
|45||B||{{ottdp|0.6|2.5|ttdprev=alpha 38}}||Town expansion bits
|-
|46||B||{{ottdp|0.6|2.5|ttdprev=alpha 67}}||Current animation frame
|-
|47||D||{{ottdp|0.7|2.6|ottdrev=r14294|ttdprev=r2020}}||XY Coordinate of the building
|-
|60||D||{{ottdp|0.6|2.5|ttdprev=alpha 56}}||Other building counts
|-
|61||D||{{ottdp|0.6|2.5|ttdprev=alpha 56}}||Other building counts
|-
|62||D||{{ottdp|0.6|2.5|ttdprev=alpha 72}}||Land info for nearby tiles
|-
|63||B||{{ottdp|0.7|2.6|ttdprev=r1665}}||Current animation frame of nearby house tiles
|-
|64||B||{{ottdp|1.2|2.6|ottdrev=r23070|ttdprev=r1672}}||Cargo acceptance history of nearby stations
|-
|65||B||{{ottdp|0.7|2.6|ottdrev=r13603|ttdprev=r2242}}||Distance of nearest house matching a given criterion
|-
|66||D||{{ottdp|1.0|2.6|ttdprev=r2246}}||Class and ID of nearby house tile
|-
|67||D||{{ottdp|1.0|2.6|ttdprev=r2246}}||GRFID of nearby house tile
|-
|80+x||||||None defined, and none ever will because town buildings don't have an internal structure. Trying to access these variables crashes TTD.
|}

<nowiki>*</nowiki> Specified version is earliest known to support the variable in its current form. Some variables may have been available earlier.

== Description ==

=== Construction stage and pseudo-random values (40) ===

{| |-
!Bits!!Meaning
|-
|0..1||Construction state: 0..2: various states of construction, 3: construction finished
|-
|2..3||A pseudo-random value. It isn't actually random, but is derived from the position of the building. Old buildings use this value to randomize their colors. TTDPatch has a better way to randomize things, but you can still use that value to mimic unpatched TTD behaviour. Note that adjacent tiles aren't guaranteed to have the same pseudo-random bits
|}

=== Town zone (42) ===

Town zone where the building is situated. The value is between 0 and 4, where 0 is the outermost zone of the town. Smaller towns have fewer zones. Roads are plain in zone 0 and 1, paved in zone 2, have trees in zone 3 and streetlights in zone 4

=== Building counts (44) ===

Returns dword LLllCCcc, where cc means how many buildings of the current type can be found in the current town, while CC is the same for the whole map. ll and LL are similar to cc and CC, but contain the number of tiles that have the same class as the current one. For tiles that have no class, ll and LL are always zero. Overridden old types are considered to be the new type they were overridden with. During [[Callbacks#House construction check (17)|callback 17]], the current building isn't on the map yet, and therefore isn't counted. In other cases, the building count is at least one, since the current building is counted as well.

=== Town expansion bits (45) ===

{| |-
!Bit!!Value!!Meaning
|-
|0||1||Set if TTD is currently creating a random town, clear otherwise. PLEASE NOTE: while TTD is generating a random town, town variables 82 (town population) and B6 (number of buildings) are incorrect. The population counter contains the population of buildings generated _yet_, which means the final value may be larger than you get. The building count variable, on the other hand, is surely higher than the final value will be. If you want to check these variables during [[Callbacks#House construction check (17)|callback 17]], you may need to check variable 45 as well and make adjustments if this bit is set.
|}

Other bits are currently reserved for future use.

=== Current animation frame (46) ===

The current animation frame being displayed. If you don't use animation callbacks, it's between zero and the value set in property 1A. Animation callbacks can set this to anything between 0 and 127.

Enabling animation on a house tile by setting properties 9, 1A and probably 1B ensures that variable 46 will indeed change with time, and the building is redrawn every time variable 46 changes. This means that you can use a VarAction2 to choose the current frame according to variable 46. Please note that this kind of animation needs more CPU time and more sprites, so you should prefer palette animation if possible.

=== XY Coordinate of the building (47) ===

The coordinate of the tile this part of the building is located.  If the building is not yet constructed, like during [[Callbacks#House construction check (17)|callback 17]], the returned value will be the proposed location.  The format of the var is YYYYXXXX.

=== Other building counts (60, 61) ===

For variable 60, the parameter is an old house type number. For variable 61, it is a new house type number defined in the current GRF file.

These variables work like variable 44, but they count the given house type instead of the current one.

Please note that, unlike random graphics, changes of deterministic building graphics don't automatically redraw the building (except when either the construction state or variable 46 changes), resulting in temporary graphics glitches when a visible building changes its graphics. These glitches can be fixed by scrolling the building out of view, then back again.

=== Land info for nearby tiles (62) ===

This variable works exactly like [[VarAction2IndustryTiles#Land info of nearby tiles 60|var. 60 for industry tiles]], except that bit 0 of the '''bb''' part is undefined.

=== Current animation frame of nearby house tiles (63) ===

The parameter of this variable is an offset from the position of the current tile. The low nibble contains the signed X offset (that is 0h=0, 1h=+1 ... 7h=+7; 8h=-8, 9h=-7 ... Fh=-1), the high nibble contains the Y offset. Although you can query a 16x16 area with these parameters, it's currently useless to use offsets other than -1, 0 and +1; if you query a tile that doesn't belong to the same building as the current tile, the result is meaningless. It may even be junk if the queried tile isn't a house tile at all.

=== Cargo acceptance history of nearby stations (64) ===

The parameter of this variable is a cargo identifier. {{grfFrom|7}} If your GRF is version 7 or later and has a cargo translation table, this is an index to that table; otherwise, it's a cargo slot number. Additionally, GRF register 100h should contain an offset relative to the current tile (use 0 for the current tile). The lowest byte contains the signed X offset and the next higher byte the signed Y offset.

The returned value looks like this:

{| |-
!Bit number!!Meaning
|-
|0||This cargo was accepted in a nearby station some time in the past
|-
|1||This cargo was accepted in a nearby station last month
|-
|2||This cargo was accepted in a nearby station this month
|-
|3||This cargo was accepted in a nearby station since the last periodic processing (which happens every 250 ticks)
|-
|4||This cargo is one of the types that triggered [[Callbacks#Watched_cargo_accepted_.28148.29|callback 148]] (only during callback 148)
|-
|other bits||undefined; reserved for future use
|}

A station is considered nearby if the selected tile is inside its acceptance area. That's why you can give an offset - other tiles of your multi-tile building may have different stations "nearby".

{{ttdp|}} The information required for this variable is stored in the station2 structure, and therefore works only if the station2 structure is present. The station2 structure is present if any of the following is true:
* Generalfixes is on, and miscmods.noextendstationrange is off
* Any of fifoloading, newcargos or irregularstations is on

If the station2 structure isn't present, the returned value is always zero.

=== Distance of nearest house matching a given criterion (65) ===

This will perform a circular search around the current tile, trying to find another house tile that will match the same type, class or GRFID. (Note: other tiles of the originating house will not match.)  Search result will be the [http://en.wikipedia.org/wiki/Taxicab_geometry Manhattan distance] between both tiles or 0, if no house tile matching the given criteria has been found.

The parameter of this variable is composed of two parts:

Bits 0..5 indicate the radius of the search going to be performed (given in Manhattan metric). Maximum search radius is 63 while the minimum is 1. A radius of 0 is considered reserved - do not use.

Bits 6..7 indicate the type of search to be carried out:

0 : Search by house type as defined in the grf file

1 : Search by building class

2 : Search by GRFID

Just like other search variables, be aware that this is a CPU intensive one

=== Class and ID of nearby house tile (66) ===

The parameter of this variable is an offset from the position of the current tile. The low nibble contains the signed X offset (that is 0h=0, 1h=+1 ... 7h=+7; 8h=-8, 9h=-7 ... Fh=-1), the high nibble contains the Y offset. The returned value is structured like this:

{| |-
!High word!!Information about house class
|-
|||'''FFFFh''' if the selected tile isn't a house tile
|-
|||'''0000h''' if the selected house doesn't have a class specified (including old houses, which cannot have a class)
|-
|||'''01XXh''' if the selected house has been defined in the current GRF with class XX
|-
|||'''02XXh''' if the selected house has been defined in a different GRF with class XX
|-
!Low word!!Information about house ID
|-
|||'''FFFFh''' if the selected tile isn't a house tile
|-
|||'''00XXh''' if the selected house is old house type XX
|-
|||'''01XXh''' if the selected house has been defined in the current GRF with ID XX
|-
|||'''02XXh''' if the selected house has been defined in a different GRF with ID XX
|}

In case the selected house comes from another GRF, you need to use variable 67 (see below) to find out the corresponding GRFID and identify the exact type of the house. Please note that variable 67 is cheaper to calculate than this one, so if you are looking for a specific GRFID/houseID combination, you should try matching the GRFID first, and get variable 66 only if the GRFID matches.

=== GRFID of nearby house tile (67) ===

The parameter of this variable is an offset from the position of the current tile. The low nibble contains the signed X offset (that is 0h=0, 1h=+1 ... 7h=+7; 8h=-8, 9h=-7 ... Fh=-1), the high nibble contains the Y offset. The returned value is one of the following:
* '''FFFFFFFFh''' if the selected tile isn't a house tile
* '''00000000h''' if the selected house is an old house type
* otherwise, the GRFID of the GRF which defined the type of the selected house

==Example==

NML:Changes 0.3

2012-08-14T19:16:33Z

Hirundo: Add note about removal of single_unit_text and multiple_units_text

<div style="float:right; padding-left:12px; background:none;">{{NMLNavMain}}</div>

== Introduction ==
Between NML 0.2.x and NML 0.3.x (and their corresponding nightlies) the generated NewGRF version by NML changed from v7 to v8. This brings lot of advantages, but requires a few changes to existing NML files. NewGRFs thus will require a minimum OpenTTD version of 1.2.0 (r23166).

== Callbacks ==
NML 0.3 only supports the new style callbacks. Thus all callback_flag properties have been removed as have the callback flag constants *CBF*. For a complete list of affected constants see the [http://dev.openttdcoop.org/projects/nml/repository/revisions/28c88515e5e7/diff/nml/global_constants.py related commit]

== New named constants ==
A few constants have recently been introduced in both NML 0.2 and 0.3 that make the transition easier. Make sure to use them. For callback "articulated_part" use CB_RESULT_NO_MORE_ARTICULATED_PARTS and/or CB_RESULT_REVERSED_VEHICLE instead of hard-coded 0xFF / 0x80.
For callbacks "cargo_subtype_text", "cargo_subtype_display" and "start_stop" use CB_RESULT_NO_TEXT instead of hard-coded 0xFF.

== Industry availability ==
The callback "availability" is no longer available. Use the callback "construction_probability" instead.

== Changed variables ==

=== snowline_height ===
The "snowline_height" variable returns the height in tiles instead of pixels (=tiles*8).

=== nearby_tile_height ===
The "nearby_tile_height" variable returns the height in tiles instead of pixels (=tiles*8).

=== date_of_last_service ===
This variable is no longer limited to the range of 1920 ... 2050. It returns now the year 0-based date.

== Base costs ==
Base costs are treated in NewGRF v8 (NML 0.3.x) differently than in NewGRF v7 (NML 0.2.x and earlier). Base costs do '''NOT''' influence eachother anymore. You'll need to set all base costs directly and cannot rely anymore that any are set indirectly. See the [[NML:Base_cost_table| base costs table]] which will be influenced.

== New properties ==
=== Railtypes: alternative_railtype_list ===
This property allows to define a list of rail types which this rail type will also define - unless the rail type is defined separately.

=== Trains / Road vehicles: Length ===
Trains and road vehicles now have a property 'length', this replaces the old property 'shorten_vehicle'.

=== Cargos: Capacity multiplier ===
This new property allows answering the question: How much units of cargo X are equivalent to 1 ton of coal, resp. 1000 litres of water?

=== Houses: watched_cargo_types ===
With the implementation of this property, the watched_cargo_accepted callback becomes usable.

== Vehicle refitting ==
The 'xor'-property 'refittable_cargo_types' is no longer available; use 'cargo_allow_refit' resp. 'cargo_disallow_refit' instead. For trains, road vehicles and ships you can now specify a default cargo type.

== Alternative sprites ==
The way OpenTTD supports 32bpp has been changed and enhanced. <code style="color:darkgreen">alternative_sprites</code> now takes more and different zoom level arguments and a type argument has been added as 8bpp sprites are now also permissible. See the description of the [[Alternative_Sprites| <code style="color:darkgreen">alternative_sprites</code>]] for details.

== Sounds ==
It is now possible to specify a relative volume for sound effects. Additionally, the 64kB size limit has been removed.

== Cargo strings ==
The cargo properties 'single_unit_text' and 'multiple_units_text' have been removed, as they didn't work properly in OpenTTD anyways. Use 'units_of_cargo' and 'items_of_cargo' instead.

NML:Cargos

2012-08-14T19:14:03Z

Hirundo: /* Cargo properties */ Improve documentation of string properties

{{NMLNavPropVarCB}}

==Cargo IDs==
For cargos, the item ID corresponds to the cargo type slot of the cargo. TTD default cargos occupy slots 0-11, so if you want to define a new cargo be sure to set this ID to 12 or higher. It is recommended to set the 'number'-property to the same value as the item ID.

==Cargo properties==

{| class="t"
! name
! value range
! comment
|-
| number
| 0..31
| Number of the cargo for bitmasks. This mostly affects old NewGRFs that don't have a cargo translation table.
|-
| type_name
| string
| String to use as cargo type name. Example: "Passengers". The list of [[NML:Default_TTD_strings|default TTD strings]] contains the strings used by the default cargos (TTD_STR_CARGO_PLURAL_XXX), which may be re-used.
|-
| unit_name
| string
| String to use for the name of one unit from the cargo type. Currently used for subsidies only (First Passenger service to..). Example string: "Passenger". The list of [[NML:Default_TTD_strings|default TTD strings]] contains the strings used by the default cargos (TTD_STR_CARGO_SINGULAR_XXX), which may be re-used.
|-
| units_of_cargo
| string
| String used to show the "short cargo" form for cargo units, e.g. "10 tonnes" or "20.000 litres". Example: "{COMMA} item{P "" s}". The list of [[NML:Default_TTD_strings|default TTD strings]] contains the strings used by the default cargos (TTD_STR_PASSENGERS and further), which may be re-used.
|-
| items_of_cargo
| string
| String used to show the "long cargo" form for cargo units, e.g. "10 tonnes of coal" or "20.000 litres of water". Example: "{COMMA} item{P "" s} of livestock". The list of [[NML:Default_TTD_strings|default TTD strings]] contains the strings used by the default cargos (TTD_STR_QUANTITY_XXX), which may be re-used.
|-
| type_abbreviation
| string
| String used for the two-letter cargo type abbreviation. Must start with a {TINYFONT} string-code. Example: "{TINYFONT}XX". Make sure to avoid multiple cargos having the same abbreviation. The list of [[NML:Default_TTD_strings|default TTD strings]] contains the strings used by the default cargos (TTD_STR_ABBREV_XXX), which may be re-used.
|-
| sprite
| sprite
| TTD sprite number for the icon of the cargo. Alternatively, set to NEW_CARGO_SPRITE and use a graphics block to define a custom sprite.
|-
| weight
| float 0..255
| Weight of one unit of the cargo (in tons)
|-
| penalty_lowerbound
| 0..255
| Delivery time until penalty is applied
|-
| single_penalty_length
| 0..255
| Length of the interval where a single penalty is applied
|-
| price_factor
| float
| Payment for delivering 10 units of cargo across a distance of 20 squares (in British Pounds).
|-
| station_list_colour
| 0..255
|
Colour for the station list window (index from the [[NML:Graphic files|DOS palette]])
|-
| cargo_payment_list_colour
| 0..255
|
Colour for the cargo payment list window (index from the [[NML:Graphic files|DOS palette]])
|-
| is_freight
| 0 or 1
| Freight status (for the freighttrains switch); 0=not freight, 1=is freight
|-
| cargo_classes
|
bitmask([[#Cargo classes|cargo classes]])
| Cargo classes
|-
| cargo_label
| 4 letters
| Cargo label, as used in the cargo table
|-
| town_growth_effect
| TOWNGROWTH_XXX
|
Effect for town growth, see [[#Cargo effects on town growth|Cargo effects on town growth]]
|-
| town_growth_multiplier
| float 0..255
| Multiplier for town growth. To be used in conjuction with town_growth_effect, when that is not TOWNGROWTH_NONE. For example, a value of 4 makes your cargo have the same effect on town growth as 4 units of food/goods/etc.
|-
| callback_flags
| bitmask(flags)
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| capacity_multiplier
| float 0 .. 255
| {{ottd|1.2|r22860}} This defines the capacity of vehicles carrying this cargo type, if the vehicle sets no specific capacity to this specific cargo type. Set this property to the amount of cargo a vehicle shall carry, which can carry 1 ton of coal or 1000 thousand litres of water (whatever comparison is more suitable for your cargotype). Depending on whether your cargo type is light or heavy you should set this property either comparing the weight or the volume. Default values are 4 for passengers, 2 for mail, goods and sweets and 1 for all other cargos.
|}

Cargo payment is computed from <code style="color:darkgreen">price_factor</code>, amount of cargo transported, distance, and a time delivery factor. Unit of the delivery time is 185 ticks, roughly 2.5 days. The factor is constant (with value 255) if delivery time is less than <code style="color:darkgreen">penalty_lowerbound</code>. It goes down with rate 1 between <code style="color:darkgreen">penalty_lowerbound + single_penalty_length</code>, and goes down with rate 2 if the delivery time is even longer. Time delivery factor is never less than 31.

===Cargo classes===

Available cargo classes are listed in the following table. Cargos may be in more than one class. Cargo classes are always used as a bitmask, use the built-in function <code>bitmask()</code>. For example, <code style="color:darkgreen">bitmask(CC_EXPRESS, CC_REFRIGERATED)</code> is used for food.

{| class="t"
! name
! type of cargo
|-
| CC_PASSENGERS
| passengers, also tourists (ECS)
|-
| CC_MAIL
| mail
|-
| CC_EXPRESS
| express goods, also tourists (ECS)
|-
| CC_ARMOURED
| valuables, diamonds, gold and alike
|-
| CC_BULK
| coal, ore, grain,...
|-
| CC_PIECE_GOODS
| containers, crates, livestock
|-
| CC_LIQUID
| oil, milk, water, ...
|-
| CC_REFRIGERATED
| food, milk, ...
|-
| CC_HAZARDOUS
| chemicals?, uranium, ...
|-
| CC_COVERED
| grain, cement, fruit, ...
|-
| CC_OVERSIZED
| vehicles, ...
|-
| CC_POWDERIZED
| cement, ...
|-
| CC_NON_POURABLE CC_NEO_BULK
| sugar cane, wool or straw bales, ...
|-
| CC_SPECIAL
| Special cargo, used for refit tricks. (e.g. regearing in NARS)
|-
| NO_CARGO_CLASS
| Special value that you can used to instead of 0.
|-
| ALL_NORMAL_CARGO_CLASSES
| Bitmask of all cargo classes except CC_SPECIAL. This is the same as <code style="color:darkgreen">bitmask(CC_PASSENGERS, CC_MAIL, ..., CC_OVERSIZED)</code>. Note: This is already a bitmask, don't use the <code style="color:darkgreen">bitmask(..)</code> function with this.
|-
| ALL_CARGO_CLASSES
| Bitmask of all cargo classes. Same as <code style="color:darkgreen">ALL_NORMAL_CARGO_CLASSES | bitmask(CC_SPECIAL)</code> Note: This is already a bitmask, don't use the <code style="color:darkgreen">bitmask(..)</code> function with this.
|}

===Cargo effects on town growth===

{| class="t"
! value
! effect
|-
| TOWNGROWTH_PASSENGERS
| Affect towns as passengers do
|-
| TOWNGROWTH_MAIL
| Affect towns as mail does
|-
| TOWNGROWTH_GOODS
| Affect towns as goods/candy does
|-
| TOWNGROWTH_WATER
| Affect towns as water does (second required cargo for towngrowth in the desert)
|-
| TOWNGROWTH_FOOD
| Affect towns as food/fizzy drinks do (first required cargo for towngrowth in desert/above snowline)
|-
| TOWNGROWTH_NONE
| Don't affect town growth (default)
|}

==Cargo variables==

Cargos have no variables (yet).

==Cargo callbacks==

{| class="t"
! callback
! return value
! comment
|-
| default
| Sprite set (with 1 sprite)
| Graphics for the cargo icon (only if property <code style="color:darkgreen">sprite</code> is set to NEW_CARGO_SPRITE)
|-
| station_rating
| -16384 .. 16383
| See detailed explanation below
|-
| profit
| -12748 .. 12748
| Called whenever cargo is delivered. <code style="color:darkgreen">extra_callback_info2</code> contains <code style="color:darkgreen">0xttaadddd</code> with <code style="color:darkgreen">tt</code> being the time spent en-route (1 unit = 2.5 days), <code style="color:darkgreen">aa</code> the amount of cargo delivered and <code style="color:darkgreen">dddd</code> the manhattan distance it was transported. The returned value is multiplied by the amount and the <code style="color:darkgreen">price_factor</code> and then divided by 256 to determine the income the player receives. Returning negative values is possible, it makes players pay for the delivery.
|}

===Station rating callback===

The station rating callback is quite complicated and deserves some detailed explanation. The default station rating calculation works as follows:

Internally, station rating is byte with values 0 .. 255, representing respectively 0% and 100%. Every 2.5 days, the transportation 'performance' is calculated using some factors outlined below. The station rating is then set to this performance value, with the caveat that the rating change cannot exceed 2 points. Therefore, rating changes are always slow, this callback cannot change this. The initial rating is 175 points (69%). The following factors are parts of the performance, their effects are summed.

====Time since the cargo was last picked up====

{| class="t"
! Time units (days)
! Score (%, rounded)
|-
| >21 (>52.5 days)
| 0 (0%)
|-
| 13 .. 21 (32.5 days .. 52.5 days)
| 25 (10%)
|-
| 7 .. 12 (17.5 days .. 32.5 days)
| 50 (20%)
|-
| 4 .. 6 (10 days .. 17.5 days)
| 95 (37%)
|-
| 0..3 (0 days..10 days)
| 130 (51%)
|}

The time unit used equals 185 engine ticks, or 2.5 TTD days. For ships, the time units are divided by 4 before calculating this component, so ships have four times more time before the ratings start dropping.

====Amount of cargo waiting====

{| class="t"
! Amount of cargo
! Score (%, rounded)
|-
| >1500
| -90 (-35%)
|-
| 1001..1500
| -35 (-14%)
|-
| 601..1000
| 0 (0%)
|-
| 301..600
| 10 (4%)
|-
| 101..300
| 30 (12%)
|-
| 0..100
| 40 (16%)
|}

====Max. speed of the last vehicle picking up the cargo====

This calculation is somewhat complicated. The maximum speed of the vehicle is expressed in "speed units". For trains and road vehicles, the speed unit is 1 km/h; for ships, it's 0.5 km/h; for aircraft, it's 8 mph. If the max. speed is above 255 speed units, 255 is used instead. If the vehicle is slower than 85 units, no points are awarded; otherwise, you get (speed_units-85)/4 points. Therefore, the maximum you can get is 42 points, or 16%.

====Age of the last carrier picking up the cargo====

{| class="t"
! Age of vehicle (years)
! Score (%, rounded)
|-
| 2
| 10 (4%)
|-
| 1
| 20 (8%)
|-
| 0
| 33 (13%)
|}

In TTDPatch this changes when the 'newagerating' switch is enabled

====Bonus for AI companies (TTDPatch only)====

{| class="t"
! AI intelligence setting
! Score (%, rounded)
|-
| Low
| 0 (0%)
|-
| Medium
| 31 (12%)
|-
| High
| 63 (25%)
|}

====Bonus for statue in nearest town====

If your company has erected a statue in the nearest town, you get 26 points (10%) bonus to all cargo ratings.

====Callback parameters====

During the callback, <code style="color:darkgreen">extra_callback_info1</code> contains one of the following values in the lowest byte:

{| |-
!value!!meaning
|-
|0x10||the last vehicle entering the station was a train
|-
|0x11||the last vehicle entering the station was a road vehicle
|-
|0x12||the last vehicle entering the station was a ship
|-
|0x13||the last vehicle entering the station was an aircraft
|-
|0||no vehicle entered the station yet, or (TTDPatch) the last one entering was sold
|}

Please note that there's only one "last vehicle type" field per station, so the vehicle this refers to may not have picked up any of your cargo.

<code style="color:darkgreen">extra_callback_info2</code> has the value <code style="color:darkgreen">0xssaaaatt</code>, where
* <code style="color:darkgreen">tt</code> is the time since the cargo was last picked up, in the time units described above (1 unit = 2.5 days independent of vehicle type)
* <code style="color:darkgreen">aaaa</code> is the amount of cargo waiting
* <code style="color:darkgreen">ss</code> is the speed of the last vehicle picking the cargo up, in the speed units described above (if no vehicle entered the station yet, the value is 0xFF)

====Effect of callback====

The return value of the callback replaces the first three components (time since pickup, amount of cargo, max speed) of the calculation. The bonus for statues, TTDPatch AIs and new vehicles is always in effect, you cannot (yet) change this.

NML:Vehicles

2012-08-02T20:34:37Z

Hirundo: /* Item IDs */

{{NMLNavPropVarCB}}
== Vehicle IDs ==
Picking an item ID requires keeping two cases in mind: OpenTTD with the engine pool enabled and OpenTTD with engine pool disabled / TTDPatch. The status of the engine pool may be checked with the global variable [[NML:General#General_variables|dynamic_engines]].

=== Engine pool enabled ===
With the engine pool enabled, each NewGRF has its own ID range, NewGRFs don't influence each other. IDs may freely be chosen between 0 and 65535. If the chosen ID belongs to an existing vehicle, this vehicle is overridden by your vehicle. If another NewGRF is already overriding that vehicle, a new vehicle will be allocated, but all the properties will be copied from the old vehicle. If you define an ID for which no original vehicle exists, a new (blank) vehicle is allocated.

This behaviour can be modified using an [[NML:Overriding_vehicles_in_other_NewGRFs|engine_override]], this allows changing the properties of vehicles defined in other NewGRFs instead of allocating a new vehicle.

=== TTDPatch / Engine pool disabled ===
Each new vehicle has to replace an existing vehicle. If multiple NewGRFs try to replace the same vehicle, the last NewGRF loaded 'wins'. [[VehicleIDs|This page]] contains a list of valid vehicle IDs for each vehicle type, look in the 'NML ID' column. Note that IDs are not bound to a specific sort of vehicle (e.g. monorail wagons) but to a feature (e.g. trains, road vehicles).

In general, you should take the following steps:
* If your NewGRF is intended as a complete replacement for the default vehicles, disable the relevant default vehicles using [[NML:Disable_items|disable_item]].
* Re-use IDs of existing vehicles as much as possible.
* If your NewGRF uses IDs outside of the normal range (for example, because you there are more vehicles than slots available), let your code check if dynamic_engies is enabled. If not, skip the vehicles outside the normal range (using an if-statement) and make sure that the remaining vehicles allow for reasonable gameplay. It is recommended to issue a warning to the user about this. Alternatively, it is also possible to disable your entire NewGRF. If you don't do this check and dynamic_engines is off, OpenTTD may disable your NewGRF with the somewhat cryptic message 'Attempt to use invalid ID', which will likely lead to bug reports about your NewGRF and/or your OpenTTD.

==Properties common to all vehicle types==

{| class="t"
! property
! value range
! available for articulated vehicle
! comment
|-
| <code style="color:green">name</code>
| (string)
| yes
| for example <code style="color:darkgreen">string(STR_NAME_HEREFORD_TRAM)</code>
|-
| <code style="color:green">climates_available</code>
| bitmask(CLIMATE_XXX, CLIMATE_YYY, ...)
| set to <code style="color:green">NO_CLIMATE</code>
|
;CLIMATE_TEMPERATE
;CLIMATE_ARCTIC
;CLIMATE_TROPICAL
;CLIMATE_TOYLAND
;NO_CLIMATE
:Vehicle is availble in no climate (e.g. for articulated parts)
;ALL_CLIMATES
:Vehicle is available irrespective of climate

To make a vehicle available in all climates except toyland you could use: <code style="color:green">ALL_CLIMATES & ~bitmask(CLIMATE_TOYLAND)</code>.
|-
| <code style="color:green">introduction_date</code>
| <code style="color:green">date</code>(yyyy,mm,dd)
| no
| Valid range for yyyy is 0 ... 5000000. In TTDPatch, dates after 2044 will be limited to 2044. Unless the engine is introduced within two years after game-start (always 1920 in TTDPatch), a random number of days between 0 and 511 will be added to this.
|-
| <code style="color:green">model_life</code>
| 0 ... 254 (years) or <code style="color:green">VEHICLE_NEVER_EXPIRES</code>
| no
|
Number of years a model is "supported" by the manufacturer, see [[#Engine life cycle|below]].
|-
| <code style="color:green">retire_early</code>
| -128 ... 127 (years)
| no
|
Retire the vehicle (make it unavailable in the purchase menu) this many years before reliability starts dropping, see [[#Engine life cycle|below]]. May be negative.
|-
| <code style="color:green">vehicle_life</code>
| 0 ... 255 (years)
| no
| Life length of an individual vehicle, before it is considered too old and in need of replacement.
|-
| <code style="color:green">reliability_decay</code>
| 0 ... 255
| no
| Default vehicles use 20. The higher the value the faster reliability decays, the more frequent service is needed. 0 means reliability never decreases if the vehicle is not too old
|-
| <code style="color:green">refittable_cargo_classes</code>
|
bit set of [[NML:Cargos#Cargo classes|cargo classes]]
| yes
| for example: <code style="color:darkgreen">bitmask(CC_BULK, CC_COVERED)</code>
|-
| <code style="color:green">non_refittable_cargo_classes</code>
|
bit set of [[NML:Cargos#Cargo classes|cargo classes]]
| yes
| for example: <code style="color:darkgreen">bitmask(CC_OVERSIZED, CC_SPECIAL)</code>
|-
| <code style="color:green">refittable_cargo_types</code>
| bit mask of entries into the cargo translation table
| yes
| As of NML 0.3, do not use this. Use cargo_[dis]allow_refit (see below) instead.
|-
| <code style="color:green">cargo_allow_refit</code>
| Array of cargo labels from the [[NML:Cargotable|cargotable]]
| Yes
| {{ottdp|1.2|no|ottdrev=r23291}} A list of cargo types to allow refitting to, irrespective of cargo classes. Example: <code style="color:darkgreen">[COAL, IORE]</code>
|-
| <code style="color:green">cargo_disallow_refit</code>
| Array of cargo labels from the [[NML:Cargotable|cargotable]]
| Yes
| {{ottdp|1.2|no|ottdrev=r23291}} A list of cargo types to disallow refitting to, irrespective of cargo classes. Example: <code style="color:darkgreen">[MAIL]</code>
|-
| <code style="color:green">loading_speed</code>
| 0 ... 255 (cargo units)
| yes
| Units of cargo loaded per time unit. Default vehicles use 5 for trains and road vehicles, 10 for ships and 20 for aircraft. This amount of cargo is loaded to or unloaded from the vehicle every 40 ticks for trains, every 20 ticks for road vehicles and aircraft and every 10 ticks for ships.
|-
| <code style="color:green">cost_factor</code>
| 0 ... 255
| Set to 0
| multiplier to the base purchase cost
|-
| <code style="color:green">running_cost_factor</code>
| 0 ... 255
| Set to 0
| multiplier to the base running costs
|-
| <code style="color:green">cargo_age_period</code>
| 0 ... 65535
| yes
|
{{ottd|1.2|r22713}} This property specifies after how many ticks cargo is aged. Default value is 185. 74 ticks is equal to 1 day.
|}

===Refittability===

To determine whether your vehicle can be refitted to a certain cargo, OpenTTD uses the following table

{| class="t"
! Cargo matches refittable_cargo_classes
! Cargo matches non_refittable_cargo_classes
! Cargo in cargo_allow_refit
! Cargo in cargo_disallow_refit
! Result
|-
| Yes
| No
| Doesn't matter
| No
| Refittable
|-
| No
| Doesn't matter
| No
| Doesn't matter
| Not refittable
|-
| Doesn't matter
| Doesn't matter
| Yes
| No
| Refittable
|-
| Doesn't matter
| Doesn't matter
| Doesn't matter
| Yes
| Not refittable
|}

For those that prefer boolean logic, the formula is as follows:

refittable = ((cargo classes in refittable_cargo_classes AND NOT cargo classes in non_refittable_cargo_classes) OR cargo in cargo_allow_refit) AND NOT (cargo in cargo_disallow_refit)

In general, you should use refittable_cargo_classes and non_refittable_cargo_classes to decide to which cargos your vehicle is refittable, and only then use cargo_allow_refit and cargo_disallow_refit to allow/disallow specific cargos.

===Engine life cycle===

The life cycle of a vehicle model consists of three phases, as outlined in the following table.

{| class="t"
! phase
! duration
! reliability
|-
| 1
| 7 to 38 months
| increases from 48-73% to 75-100%
|-
| 2
| <code style="color:darkgreen">model_life</code> - 8 years
| stays constant at peak, 75-100%
|-
| 3
| 10 to 20.5 years
| decreases from peak to 25-50%
|}

If <code style="color:darkgreen">model_life</code> is set to <code style="color:darkgreen">VEHICLE_NEVER_EXPIRES</code>, the engine remains in phase 2 forever.

Normally, the vehicle is removed from the purchase menu at the and of phase 3. However if you set the <code style="color:darkgreen">retire_early</code> property, it will be retired this many years before (or after, if the value is negative) the end of phase 2.

==Sorting vehicles in the purchase list==
This is a special property that is not encoded in an item/property-block like most other properties but it has it's own block instead. The syntax is as follows:

sort(<feature>, [<ID>, <ID>, <ID>...]);

The engines will be sorted in the given order on the position where originally the first element was. Say the original engine sorting is this: A B C D E and you use this code <code style="color:darkgreen">sort(FEAT_TRAINS, [D, B, A]);</code> the final sorting will be this: C D B A E

==Train properties==

{| class="t"
! property
! value range
! available for articulated vehicle
! comment
|-
| <code style="color:green">sprite_id</code>
| <code style="color:green">SPRITE_ID_NEW_TRAIN</code>
| yes
| Set this property to enable new graphics
|-
| <code style="color:green">speed</code>
| 0 ... 65000 (float, speed units)
| no
| Max speed for engines, speed limit for wagons
|-
| <code style="color:green">misc_flags</code>
| bitmask(TRAIN_FLAG_XXX, ...)
| FLIP should not be set, TILT and MU TO the same value as the 1st part
|
;TRAIN_FLAG_TILT
: enable the tilt bonus (20% speed in curves, if all vehicles in consist have it set)
;TRAIN_FLAG_2CC
:Enable use of the 2nd company colour
;TRAIN_FLAG_MU
:act as multiple unit (used for livery selection only)
;TRAIN_FLAG_FLIP
:Allow vehicle to be flipped (reversed) in depot
;TRAIN_FLAG_AUTOREFIT
:Allow autoreffitting. To enable autorefit, furthermore the [[#Vehicle callbacks|refit_cost]]-callback has to allow it, or else (if this callback is not implemented or fails) the <code style="color:green">refit_cost</code>-property (see below) must be set to 0.
;TRAIN_FLAG_NO_BREAKDOWN_SMOKE
:{{nml|0.3}} {{ottdp|1.3|no|ottdrev=r24124}} Disable breakdown smoke effect
|-
| <code style="color:green">refit_cost</code>
| 0 ... 255
| yes
| in 50% units of the purchase price cost base
|-
| <code style="color:green">callback_flags</code>
| bitmask(VEH_CBF_XXX, ...)
| yes
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| <code style="color:green">track_type</code>
| item from railtypetable
| must be the same as front
| Default railtype table: RAIL, MONO, MGLV. If you install a railtypetable yourself you'll always get the railtype you specified. If you want a vehicle to run on electric rail and you don't have a railtypetable, set <code style="color:green">track_type</code> to RAIL and make sure that you set <code style="color:green">engine_class</code> to <code style="color:green">ENGINE_CLASS_ELECTRIC</code>.
|-
| <code style="color:green">ai_special_flag</code>
| [<code style="color:green">AI_FLAG_PASSENGER</code> <nowiki>|</nowiki> <code style="color:green">AI_FLAG_CARGO</code>]
| no
|
;<code style="color:green">AI_FLAG_PASSENGER</code>
:Tell computer players that it's an engine that should only be used for passenger service.
|-
| <code style="color:green">power</code>
| 0 ... 65000 hp (float, power units)
| Set to 0
|
|-
| <code style="color:green">running_cost_base</code>
| RUNNING_COST_XXX
| Set to RUNNING_COST_NONE
|
;RUNNING_COST_STEAM
;RUNNING_COST_DIESEL
;RUNNING_COST_ELECTRIC
;RUNNING_COST_ROADVEH
;RUNNING_COST_NONE
:no running costs
|-
| <code style="color:green">dual_headed</code>
| [0 <nowiki>|</nowiki> 1]
| Set to 0 for all parts of an articulated vehicle
| 1 = dual_headed, otherwise normal engine
|-
| <code style="color:green">default_cargo_type</code>
| An identifier from the [[NML:Cargotable|cargo table]], or DEFAULT_CARGO_FIRST_REFITTABLE
| Yes
| If the vehicle is refittable to at least one cargo, but the chosen default cargo is not available or is set to DEFAULT_CARGO_FIRST_REFITTABLE, then the first refittable cargo is used. The first refittable is chosen according to the order in your [[NML:Cargotable|cargo table]]. If this property is set to a valid cargo but the vehicle cannot refit to any cargo type, then the vehicle will be able to carry only this cargo, but it cannot be refitted (like e.g. the default train wagons).
|-
| <code style="color:green">cargo_capacity</code>
| 0 .. 255
| yes
| By default, passenger capacity is 4x, and mail/goods capacity 2x larger than capacity for other cargoes. The capacity set here is used for the default (i.e. first refittable) cargo. Use the <code style="color:green">cargo_capacity</code> callback to avoid this effect.
|-
| <code style="color:green">weight</code>
| 0 .. 1279 ton (float, mass units)
| Set to 0
|
|-
| <code style="color:green">ai_engine_rank</code>
| 0 ... 255
| no
| TTDPatch only: Higher values make the engine for the TTDPatch AI more attractive
|-
| <code style="color:green">engine_class</code>
| ENGINE_CLASS_XXX
| no
|
Defines which livery colour settings apply to the vehicle
;ENGINE_CLASS_STEAM
;ENGINE_CLASS_DIESEL
;ENGINE_CLASS_ELECTRIC
;ENGINE_CLASS_MONORAIL
;ENGINE_CLASS_MAGLEV
|-
| <code style="color:green">extra_power_per_wagon</code>
| 0 ... 65000 hp (float, power units)
| Set to 0
| Only wagons with a livery override for this engine will add power
|-
| <code style="color:green">tractive_effort_coefficient</code>
| 0 ... 1 (float)
| Set to 0
| Fraction of the vehicle weight that is available as tractive effort. Tractive effort (in kN) is calculated as (TE coefficient) * 10 * weight (in tons), with 10 being an approximation of the acceleration of gravity (9.81 m/s). Default value is 0.3.
|-
| <code style="color:green">air_drag_coefficient</code>
| 0 ... 1 (float)
| Set to 0
| Coefficient of the relative air drag, in arbitrary units. The default value is approximately (8 / max_speed), with max_speed in km/h, clamped to the range 0.004 .. 0.75.
|-
| <code style="color:green">length</code>
| 1 ... 8
| yes
| Length of the vehicle in arbitrary units. Use a value of 8 (equal to the predefined constant VEHICLE_LENGTH) for a full-length vehicle.
|-
| <code style="color:green">visual_effect_and_powered</code>
| <code style="color:green">visual_effect_and_powered</code> (VISUAL_EFFECT_XXX, offset, <code style="color:green">ENABLE_WAGON_POWER</code> or <code style="color:green">DISABLE_WAGON_POWER</code>)
| yes
|
Set the type of visual effect for the vehicle and its positional offset with respect to the vehicle. An offset of 0 is default, negative values mean more to the front and positive values are backwards. Minimum offset is -8, maximum is 7.

;VISUAL_EFFECT_DEFAULT
:No effect, unless for the default vehicles
;VISUAL_EFFECT_STEAM
:Steam like from steam engine
;VISUAL_EFFECT_DIESEL
:Steam from internal combustion engine
;VISUAL_EFFECT_ELECTRIC
:Electric sparks
;VISUAL_EFFECT_DISABLE
:No effect
|-
| <code style="color:green">extra_weight_per_wagon</code>
| 0 ... 255 ton (float, mass units)
| Set to 0
| Adds extra weight for powered wagons, see <code style="color:green">extra_power_per_wagon</code>
|-
| <code style="color:green">bitmask_vehicle_info</code>
| 8-bit bitmask
| yes
|
Used for obtaining [[#bitmask consist info|<code style="color:green">bitmask_consist_info</code>]]
|}

==Road vehicle properties==

{| class="t"
! property
! value range
! available for articulated vehicle
! comment
|-
| sprite_id
| SPRITE_ID_NEW_ROADVEH
| yes
| Set this property to enable new graphics
|-
| speed
| 0 ... 514km/h (float, speed units)
| no
|
|-
| misc_flags
| bitmask(ROADVEH_FLAG_XXX, ...)
| partly; tram flag must the same
|
;ROADVEH_FLAG_TRAM
:The vehicle requires tram tracks to run on
;ROADVEH_FLAG_2CC
:Enable 2nd company colour
;ROADVEH_FLAG_AUTOREFIT
:Allow autorefitting. To enable autorefit, furthermore the [[#Vehicle callbacks|refit_cost]]-callback has to allow it, or else (if this callback is not implemented or fails) the <code style="color:green">refit_cost</code>-property (see below) must be set to 0.
;ROADVEH_FLAG_NO_BREAKDOWN_SMOKE
:{{nml|0.3}} {{ottdp|1.3|no|ottdrev=r24124}} Disable breakdown smoke effect
|-
| refit_cost
| 0 ... 255
| yes
| in 25% units of the purchase price cost base
|-
| callback_flags
| bitmask(VEH_CBF_XXX, ...)
| yes
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| running_cost_base
| RUNNING_COST_XXX
| set to RUNNING_COST_NONE
|
;RUNNING_COST_STEAM
;RUNNING_COST_DIESEL
;RUNNING_COST_ELECTRIC
;RUNNING_COST_ROADVEH
;RUNNING_COST_NONE
:no running costs
|-
| power
| 0 ... 2550hp (float, power units)
| Set to 0
|
|-
| weight
| 0 ... 63.75ton (float, mass units)
| Set to 0
|
|-
| tractive_effort_coefficient
| 0 ... 1 (float)
| Set to 0
| Fraction of the vehicle weight that is available as tractive effort. Tractive effort (in kN) is calculated as (TE coefficient) * 10 * weight (in tons), with 10 being an approximation of the acceleration of gravity (9.81 m/s). Default value is 0.3.
|-
| air_drag_coefficient
| 0 ... 1 (float)
| Set to 0
| Coefficient of the relative air drag, in arbitrary units. The default value is approximately (8 / max_speed), with max_speed in km/h, clamped to the range 0.004 .. 0.75.
|-
| <code style="color:green">default_cargo_type</code>
| An identifier from the [[NML:Cargotable|cargo table]], or DEFAULT_CARGO_FIRST_REFITTABLE
| Yes
| If the vehicle is refittable to at least one cargo, but the chosen default cargo is not available or is set to DEFAULT_CARGO_FIRST_REFITTABLE, then the first refittable cargo is used. The first refittable is chosen according to the order in your [[NML:Cargotable|cargo table]]. If this property is set to a valid cargo but the vehicle cannot refit to any cargo type, then the vehicle will be able to carry only this cargo, but it cannot be refitted (like e.g. the default train wagons).
|-
| cargo_capacity
| 0 ... 255
| yes
| By default, passenger capacity is 4x, and mail/goods capacity 2x larger than capacity for other cargoes. The capacity set here is used for the default (i.e. first refittable) cargo. Use the <code style="color:green">cargo_capacity</code> callback to avoid this effect.
|-
| sound_effect
| SOUND_XXX
| no
|
See available [[NML:List of sound effects|sound effects]].
|-
| visual_effect
| visual_effect( VISUAL_EFFECT_XXX, offset)
| yes
|
Set the type of visual effect for the vehicle and its positional offset with respect to the vehicle. An offset of 0 is default, negative values mean more to the front and positive values are backwards. Minimum offset is -8, maximum is 7.

;VISUAL_EFFECT_DEFAULT
:No effect, unless for the default vehicles
;VISUAL_EFFECT_STEAM
:Steam like from steam engine
;VISUAL_EFFECT_DIESEL
:Steam from internal combustion engine
;VISUAL_EFFECT_ELECTRIC
:Electric sparks
;VISUAL_EFFECT_DISABLE
:No effect
|-
| length
| 1 ... 8
| yes
| Length of the vehicle in arbitrary units. Use a value of 8 (equal to the predefined constant VEHICLE_LENGTH) for a full-length vehicle.
|}

==Ship properties==

{| class="t"
! property
! value range
! comment
|-
| sprite_id
| SPRITE_ID_NEW_SHIP
| Set this property to enable new graphics
|-
| speed
| 0 ... 127 km/h (float, speed units)
|
|-
| misc_flags
| bitmask(SHIP_FLAG_XXX)
| Bitmask with to possible flags, set to 0 to disable all.

;SHIP_FLAG_2CC
:Enable use of the 2nd company colour
;SHIP_FLAG_AUTOREFIT
:llow autorefitting. To enable autorefit, furthermore the [[#Vehicle callbacks|refit_cost]]-callback has to allow it, or else (if this callback is not implemented or fails) the <code style="color:green">refit_cost</code>-property (see below) must be set to 0.
;SHIP_FLAG_NO_BREAKDOWN_SMOKE
:{{nml|0.3}} {{ottdp|1.3|no|ottdrev=r24124}} Disable breakdown smoke effect
|-
| refit_cost
| 0 ... 255
| in 1/32 of the default refit cost base
|-
| callback_flags
| bitmask(VEH_CBF_XXX, ...)
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| is_refittable
| [0 <nowiki>|</nowiki> 1]
| 0=false, 1=true. Note: if you do not set this property to 1, then refittable_cargo_classes / non_refittable_cargo_classes have no effect.
|-
| <code style="color:green">default_cargo_type</code>
| An identifier from the [[NML:Cargotable|cargo table]], or DEFAULT_CARGO_FIRST_REFITTABLE
| If the vehicle is refittable to at least one cargo, but the chosen default cargo is not available or is set to DEFAULT_CARGO_FIRST_REFITTABLE, then the first refittable cargo is used. The first refittable is chosen according to the order in your [[NML:Cargotable|cargo table]]. If this property is set to a valid cargo but the vehicle cannot refit to any cargo type, then the vehicle will be able to carry only this cargo, but it cannot be refitted (like e.g. the default train wagons).
|-
| cargo_capacity
| 0 ... 255
| For ships (unlike other vehicle types) the capacity set here is not affected by the cargo type.
|-
| sound_effect
| SOUND_XXX
|
See available [[NML:List of sound effects|sound effects]].
|-
| ocean_speed_fraction
| 0 ... 1 (float)
|
{{ottd|1.2|r22639}} fraction of base speed on ocean tiles (default: 1)
|-
| canal_speed_fraction
| 0 ... 1 (float)
|
{{ottd|1.2|r22639}} fraction of base speed on canal tiles (default: 1)
|-
| visual_effect
| visual_effect(VISUAL_EFFECT_XXX, offset)
| XXX=[DEFAULT <nowiki>|</nowiki> STEAM <nowiki>|</nowiki> DIESEL <nowiki>|</nowiki> ELECTRIC <nowiki>|</nowiki> DISABLE], it is the type of the visual effect you want for this ship. Default means no effect. Offset is the position of the effect. 0 is default, negative values mean more to the front and positive values are backwards. Minimum offset is -8, maximum is 7.
|}

==Aircraft properties==

{| class="t"
! property
! value range
! comment
|-
| sprite_id
| SPRITE_ID_NEW_AIRCRAFT
| Set this property to enable new graphics
|-
| speed
| 0 .. 3280 km/h (float, speed units)
|
|-
| range
| 0 .. 2894
| {{nml|0.3}} {{ottdp|1.2|no|ottdrev=r23504}} Maximum (euclidean) distance the aircraft can cover between two airports. Set to 0 for unlimited range.
|-
| misc_flags
| bitmask(AIRCRAFT_FLAG_2CC, AIRCRAFT_FLAG_AUTOREFIT)
| Bitmask with to possible flags, set to 0 to disable all.

;AIRCRAFT_FLAG_2CC
:Enable 2nd company colour
;AIRCRAFT_FLAG_AUTOREFIT
:Allow autorefitting. To enable autorefit, furthermore the [[#Vehicle callbacks|refit_cost]]-callback has to allow it, or else (if this callback is not implemented or fails) the <code style="color:green">refit_cost</code>-property (see below) must be set to 0.
;AIRCRAFT_FLAG_NO_BREAKDOWN_SMOKE
:{{nml|0.3}} {{ottdp|1.3|no|ottdrev=r24124}} Disable breakdown smoke effect
|-
| refit_cost
| 0 ... 255
| in 1/32 of default refit cost base
|-
| callback_flags
| bitmask(VEH_CBF_XXX, ...)
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| aircraft_type
| AIRCRAFT_TYPE_XXX
|
;AIRCRAFT_TYPE_HELICOPTER
:Can land on helipad
;AIRCRAFT_TYPE_SMALL
:Can land on all airports with runway
;AIRCRAFT_TYPE_LARGE
:Can land on all airports with runway. But have a high crash chance on small airports
|-
| acceleration
| 0 ... 255
| In arbitrary units
|-
| passenger_capacity
| 0 ... 65536
| Capacity for the passenger compartment. See also the notes at <code style="color:darkgreen">mail_capacity</code> below.
|-
| mail_capacity
| 0 ... 255
| Capacity for the mail compartment, if refitted to a cargo in the CC_PASSENGERS class. When refitted to other cargoes, this capacity is added to the passenger capacity to determine the base capacity. The actual capacity is set to this base capacity divided by 1 for mail, 2 for goods and 4 for all other cargoes. To override this effect, use the <code style="color:darkgreen">passenger_capacity</code> and <code style="color:darkgreen">mail_capacity</code> callbacks.
|-
| sound_effect
| SOUND_XXX
|
See available [[NML:List of sound effects|sound effects]].
|}

==Vehicle variables==

Below an overview of all vehicle-specific variables. Not that in the purchase list, the vehicle is not built yet and as such many variables are not available. All general variables are available, refer to the table for info on vehicle-specific variables. Trying to access a non-available variable invokes undefined behaviour. Please note that while all variables are available for all vehicles types, some of them only make sense for one or more vehicle types. For example checking current_railtype for a non-rail vehicle doesn't make sense at all.

===Variables without parameter===

{| class="t"
! name
! value range
! available in purchase list?
! comment
|-
| position_in_consist
| 0 ... 255
| No
| The position of the current vehicle-part from the start of the vehicle. The engine will get value 0, the first wagon (or second engine) gets value 1, etc.
|-
| position_in_consist_from_end
| 0 ... 255
| No
| Same as position_in_consist but counted from the end. The last wagon will get value 0.
|-
| num_vehs_in_consist
| 1 ... 256
| No
| The total number of vehicles-parts in this vehicle. For aircraft this will include the shadow and the rotor.
|-
| position_in_vehid_chain
| 0 ... 255
| No
| See position_in_consist, but not of the complete vehicle but only all consecutive parts with the same id.
|-
| position_in_vehid_chain_from_end
| 0 ... 255
| No
| See position_in_consist_from_end, but not of the complete vehicle but only all consecutive parts with the same id.
|-
| num_vehs_in_vehid_chain
| 1 ... 256
| No
| See num_vehs_in_consist, but not of the complete vehicle but only all consecutive parts with the same id.
|-
| cargo_classes_in_consist
| Bitmask of CC_XXX
| No
|
[[NML:Cargos#Cargo classes|cargo classes]]
|-
| most_common_refit
|
[[NML:Cargos#Cargo properties|cargo class]]
| No
| cargo class most often refit to
|-
| bitmask_consist_info
| Bitmask 8 bit
| No
|
Binary OR of the values of [[#bitmask vehicle info|bitmask_vehicle_info]] of all vehicles (engines, wagons) in the consist. Only available for rail vehicles.
|-
| company_num
| 0 ... 14
| Yes
| company number of the vehicle owner. TTDPatch only supports up to 8 companies (0 ... 7)
|-
| company_type
| PLAYERTYPE_XX
| Yes
|
;PLAYERTYPE_HUMAN
:human player
;PLAYERTYPE_AI
:AI player
;PLAYERTYPE_HUMAN_IN_AI
:human managing AI company
;PLAYERTYPE_AI_IN_HUMAN
:AI managing human company

OpenTTD only uses PLAYERTYPE_HUMAN and PLAYERTYPE_AI. If you cheat yourself to be part of an AI company OpenTTD will still report PLAYERTYPE_AI for the company with yourself and the AI and it'll report PLAYERTYPE_HUMAN for the now uncontrolled company.
|-
| company_colour1
| COLOUR_XXX
| Yes
|
Refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for possible values.
|-
| company_colour2
| COLOUR_XXX
| Yes
|
Same as company_colour1, if no 2nd company colour is chosen. Refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for possible values.
|-
| aircraft_height
| 0 ... 255
| No
| Height difference between the aircraft and its shadow. 8 Units are equivalent to one height level on the map.
|-
| airport_type
| AIRPORTTYPE_XX
| No
|
;AIRPORTTYPE_SMALL
;AIRPORTTYPE_LARGE
;AIRPORTTYPE_HELIPORT
;AIRPORTTYPE_OILRIG
|-
| curv_info_prev_cur
| -2 ... 2
| No
| Difference in direction between the previous (towards engine) vehicle and this vehicle. Curvature to the right is positive. 1 unit is 45 degrees.
|-
| curv_info_cur_next
| -2 ... 2
| No
| Difference in direction between this vehicle and the next (towards rear end) vehicle. Curvature to the right is positive. 1 unit is 45 degrees.
|-
| curv_info_prev_next
| -4 ... 4
| No
| Difference in direction between the previous (towards engine) and next (towards rear end) vehicle. Curvature to the right is positive. 1 unit is 45 degrees. Equal to <code style="color:darkgreen">curve_invo_prev_cur + curv_info_cur_next</code>.
|-
| curv_info
| vehicle_curv_info(''prev_cur'', ''cur_next'')''''
| No
|
Returns a magic number that represents the curvature state of the prev-cur-next vehicle triplet. Do not try to make sense of this magic number, use the [[NML:Builtin functions|builtin function]] <code style="color:darkgreen">vehicle_curv_info()</code> instead to make comparisons. <code style="color:darkgreen">curv_info == vehicle_curv_info(a, b)</code> is equivalent to <code style="color:darkgreen">(curv_info_prev_cur == a) && (curv_info_cur_next == b)</code>, however the former can easily be used in a switch-block.
|-
| motion_counter
| 0 ... 15
| Yes, always 0
| Is increased every time the vehicle moves a single step on the map. Useful for animations.
|-
| cargo_type_in_veh
| entry in cargo translation table
| Yes, for the default cargo
| 0xFF if not present in the table
|-
| cargo_unit_weight
| weight per unit in 1/16t
| Yes, for the default cargo
|
|-
| cargo_classes
| Bitmask of [[NML:Cargos#Cargo properties|cargo class]]
| Yes, for the default cargo
| class of the currently transported cargo
|-
| vehicle_is_available
| [0 <nowiki>|</nowiki> 1]
| Yes
| Value is 1 if the vehicle is available on the open market
|-
| vehicle_is_testing
| [0 <nowiki>|</nowiki> 1]
| Yes
| Value is 1 if the vehicle is currently being tested
|-
| vehicle_is_offered
| [0 <nowiki>|</nowiki> 1]
| Yes
| Value is 1 if the vehicle is currently being offered for exclusive preview
|-
| build_year
| 0 ... 5000000
| Yes
| 0-based year when the vehicle was built, current year if the vehicle is not built yet
|-
| direction
| DIRECTION_XX
| No
|
See [[NML:List of direction constants|here]] for an overview of possible values and their meaning.
|-
| cargo_capacity
| 0 ... 65535
| No
| Cargo capacity (number of units) of the vehicle
|-
| cargo_count
| 0 ... 65535
| No
| Number of cargo units of cargo in the vehicle
|-
| cargo_subtype
| 0 ... 255
| Yes, always 0
| Cargo subtype, used to provide more than one refit option for the same cargo type. See also the <code style="color:darkgreen">cargo_subtype_text</code> callback.
|-
| vehicle_is_powered
| [0 <nowiki>|</nowiki> 1]
| No
| Vehicle provides power and is on the correct track type
|-
| vehicle_is_not_powered
| [0 <nowiki>|</nowiki> 1]
| No
| Vehicle is either on a wrong track type or it doesn't provide power at all
|-
| vehicle_is_potentially_powered
| [0 <nowiki>|</nowiki> 1]
| No
| Vehicle provides power, if it is on a suitable track type
|-
| vehicle_is_reversed
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle has reversed an odd number of times
|-
| built_during_preview
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle was built during the exclusive preview stage
|-
| current_railtype
| No
| Entry from railtype translation table or 0xFF
| Don't use this variable unless you've defined a railtype translation table. If the train is running on a railtype that is not listed in your railtype translation table this variable will contain 0xFF. Available since OpenTTD r20164.
|-
| waiting_triggers
|
| No
|
Random triggers waiting to be matched. (see [[NML:Random switch|Random switch]])
|-
| random_bits
| 0 ... 255
| No
|
Random data that can be used to randomize certain descisions. (see [[NML:Random switch|Random switch]])
|-
| grfid
| 0 ... 0xFFFFFFFF
| No
|
GRFID that defined the [[NML:Graphics|graphics]]-block for this vehicle. To compare this with other grfids, use the [[NML:Builtin functions|builtin function]] <code style="color:darkgreen">str2number()</code> to convert the other GRFID to a number as well.
|-
| vehicle_type_id
| 0 ... 65535
| No
| GRF-local ID of the vehicle, equal to the item ID. Note that vehicles from other NewGRFs may have the same ID, so you'll generally have to check the <code style="color:darkgreen">grfid</code> as well.
|-
| vehicle_is_hidden
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle is hidden in a depot or tunnel.
|-
| vehicle_is_stopped
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle is stopped, or if it is braking for a stop (trains only).
|-
| vehicle_is_crashed
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle has crashed.
|-
| vehicle_is_broken
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle is broken down.
|-
| date_of_last_service
| date(year, month, day)
| No
|
|-
| breakdowns_since_last_service
| 0 ... 255
| No
| Number of breakdowns since the last service
|-
| reliability
| 0 ... 100
| No
| Reliability (percentage)
|-
| age_in_days
| 0 ... 65535
| No
| Vehicle age in days.
|-
| max_age_in_days
| 0 ... 65535
| No
| Maximum vehicle age in days.
|-
| current_speed
| (speed units)
| No
| The current speed of the vehicle in m/s
|-
| max_speed
| (speed units)
| No
| The maximum speed of the vehicle in m/s
|-
| current_max_speed
| (speed units)
| No
| {{nml|0.3}} {{ottdp|1.3|no|ottdrev=r24246}} Current maximum speed of the vehicle in m/s. This includes e.g. track or timetable limits. Only valid for front vehicle.
|-
| vehicle_is_in_depot
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle is inside a depot
|}

===Variables that require an argument===

{| class="t"
! name
! Argument
! value range
! available in purchase list?
! comment
|-
| count_veh_id
| The vehicle ID to look for.
| 0..255
| No
| The number of vehicles in the current consist that have the given ID.
|-
| other_veh_curv_info
| Offset in the chain from the current vehicle.<ref name="offset">Value range is -128..127. Positive values are interpreted as towards the end, negative values as towards the front. If the offset is outside the vehicle chain, the result value will be 0.</ref>
| -4..4
| No
| Difference in direction between the other vehicle and this vehicle. Curvature to the right is positive. 1 unit is 45 degrees.
|-
| other_veh_is_hidden
| Offset in the chain from the current vehicle.<ref name="offset"/>
| [0 <nowiki>|</nowiki> 1]
| No
| 1 the other vehicle is hidden in a depot or tunnel, 0 otherwise
|-
| other_veh_x_offset
| Offset in the chain from the current vehicle.<ref name="offset"/>
| -128..127
| No
| Signed difference in X-position (top-right to bottom-left) between the other vehicle and this vehicle.
|-
| other_veh_x_offset
| Offset in the chain from the current vehicle.<ref name="offset"/>
| -128..127
| No
| Signed difference in Y-position (top-left to bottom-right) between the other vehicle and this vehicle.
|-
| other_veh_is_hidden
| Offset in the chain from the current vehicle.<ref name="offset"/>
| -128..127
| No
| Signed difference in Z-position (upwards) between the other vehicle and this vehicle.
|}
<references/>

==Vehicle callbacks==
The following table contains a list of available vehicle callbacks. Additionally, it's possible to provide cargo-specific graphics, using the identifier from the [[NML:Cargotable|cargo table]] as callback name. These callbacks will be used if the vehicle is refitted to the corresponding cargo type. If no cargo-specific graphics match the cargo that the vehicle is carrying, the <code style="color:darkgreen">default</code> callback is used instead. Cargo-specific graphics callbacks are never called from the purchase menu, refer to the <code style="color:darkgreen">purchase</code> callback below instead.

Note that the above affects '''graphics only''', other callbacks are unaffected.

{| class="t"
! Name
! Available for
! In purchase menu?
! value range
! comment
|-
| default
| All
| Yes, unless <code style="color:darkgreen">purchase</code> is set separately
| Sprite group
| 'Normal' vehicle graphics, if no cargo-specific graphics apply. See also the section on [[#Sprites in GUI|GUI sprites]].
|-
| purchase
| All
| Yes, only
| Sprite group
| Graphics to show in the buy menu (only the horizontal view is needed, except for dual-headed trains. With the <code>dual_headed</code> property set, special rules for the purchase menu sprite apply: two sprites are drawn (for front and back) as if the vehicle is normally constructed. If you supply one purchase menu sprite, it will be used for both vehicle parts in the purchase menu. Provide a set of 8 sprites, and the 7th resp. 3rd sprite will be drawn; provide a set of 8 blank sprites except the 7th if you want to fully control a single purchase menu sprite for a dual-headed engine. ) See also the section on [[#Sprites in GUI|GUI sprites]].
|-
| rotor
| Aircraft (helicopters)
| No
| Sprite group
| Graphics for the helicopter rotor (4 sprites; 1 stopped and 3 moving)
|-
| random_trigger
| All
| No
| N/A
| See [[NML:Random switch|random switch]] for more information.
|-
| cargo_subtype_text
| All
| No
| String, or CB_RESULT_NO_TEXT
| With this callback, you can display extra text after the cargo in the vehicle information window. This callback is called during refitting, with succesively increased values of the <code style="color:darkgreen">cargo_subtype</code> variable, until the callback returns CB_RESULT_NO_TEXT. All returned strings are then displayed as refit options. The chosen refit option is saved in the <code style="color:darkgreen">cargo_subtype</code> variable, so it can be used later for other things. In the HEQS grf for example, this mechanism is used to let the user choose between different capacities of the same vehicle.
|-
| additional_text
| All
| Yes, only
| String
| Additional text to show in the purchase list.
|-
| colour_mapping
| All
| Yes, unless <code style="color:darkgreen">purchase_colour_mapping</code> is set separately
| Recolour sprite number
|
With this callback, you can use a different recolour sprite instead of the standard 1cc / 2cc company colour remappings. See [[NML:List of default colour translation palettes|here]] for a list of default palettes. See the [[NML:Builtin functions|builtin function]] <code style="color:darkgreen">reserve_sprites()</code> for info on how to allocate your own sprite. For performance, the result is cached and only updated if the <code style="color:darkgreen"> every_32_days</code> callback requires so. Add CB_RESULT_COLOUR_MAPPING_ADD_CC to the result to add the company colour to the sprites, this requires 16 (1cc) or 256 (2cc) sprites in total.
|-
| start_stop
| All
| No
| String or CB_RESULT_NO_TEXT
| Called when starting or stopping a vehicle. Mainly useful to prevent vehicles from leaving the depot unless a certain condition is met. Return CB_RESULT_NO_TEXT to allow or a string (containing an error message) to disallow starting/stopping.
|-
| every_32_days
| All
| No
| bitmask(CB_RESULT_32_DAYS_XXX, ...)
| Called every 32 days. Set CB_RESULT_32_DAYS_TRIGGER in the bitmask to trigger TRIGGER_VEHICLE_32_CALLBACK. Set CB_RESULT_32_DAYS_COLOUR_MAPPING in the bitmask to update the colour mapping by re-running the <code style="color:darkgreen">colour_mapping</code> callback.
|-
| sound_effect
| All
| No
| SOUND_XXX, sound("sound.wav"), import_sound(grfid, number) or CB_RESULT_NO_SOUND
|
Called to play various vehicle sounds. <code style="color:darkgreen">extra_callback_info1</code> contains the sound event, see the [[#Sound events|table]] below. Return SOUND_XXX (see [[NML:List_of_sound_effects|here]]) to return a default sound. <code style="color:darkgreen">sound("soundfile")</code> imports a sound from a .wav file. <code style="color:darkgreen">import_sound(grfid, number)</code> imports a sound from another grf. A failed (or not implemented) callback will cause the default sound to be played. Return CB_RESULT_NO_SOUND to play no sound at all.
|-
| articulated_part
| Trains, Road Vehicles
| Yes (no separate callback)
| Vehicle ID, or CB_RESULT_NO_MORE_ARTICULATED_PARTS
| With this callback, you can add articulated parts (e.g. tenders) to your vehicle. Called repeatedly, until CB_RESULT_NO_MORE_ARTICULATED_PARTS is returned. After each call, the returned vehicleID is added to your vehicle. <code style="color:darkgreen">extra_callback_info1</code> contains 1 during the first call, 2 during the second, etc. Note that callback may be called from the purchase list, using vehicle variables is not possible. Or CB_RESULT_REVERSED_VEHICLE to the returned vehicle ID to display the vehicle backwards.

For NML 0.2 and lower the vehicle ID of the articulated part must be in the range 0 .. 127.
|-
| can_attach_wagon
| Trains
| No
| String or CB_RESULT_ATTACH_XXX
| Called when a wagon is being attached, to allow or disallow attaching. This callback has to be defined at the engine. However, variables in the <code style="color:darkgreen">SELF</code> scope refer to the wagon being attached, the <code style="color:darkgreen">PARENT</code> scope refers to the engine that the wagon is being attached to. Return a string to disallow with the string as error message. Return CB_RESULT_ATTACH_DISALLOW to disallow with standard message ("incompatible railtypes"), CB_RESULT_ATTACH_ALLOW to allow or CB_RESULT_ATTACH_ALLOW_IF_RAILTYPES to allow if the railtypes match (default).
|-
| refit_cost
| {{ottdp|1.2|no|ottdrev=r23089}} All
| Yes
| -8192 .. 8191 as refit cost. Add <code style="color:darkgreen">CB_RESULT_AUTOREFIT</code> if you want to allow autorefit.
| When returning a negative value, encode the cost as (cost & <code style="color:darkgreen">CB_RESULT_REFIT_COST_MASK</code>) before (possibly) adding <code style="color:darkgreen">CB_RESULT_AUTOREFIT</code>. To allow autorefitting, the corresponding bit in the <code style="color:darkgreen">misc_flags</code> must be set as well. Variable <code style="color:darkgreen">extra_callback_info1</code> contains information about the target cargo type in the format 0xccccsstt, with tt being the new cargo type, ss the new cargo subtype (see <code style="color:darkgreen">cargo_subtype_text</code>-callback) and cccc a bitmask of the [[NML:Cargos#Cargo_classes|cargo classes]] of the target cargo type. Note that this callback may also be called when the vehicle does not exist yet, so the available variables are limited.
|}

The following callbacks all have an equivalent property. The property description applies here also, except where otherwise noted.

{| class="t"
! Name
! Available for
! In purchase menu?
! comment
|-
| loading_speed
| All
| No
|
|-
| speed
| All
| Yes, unless <code style="color:darkgreen">purchase_speed</code> is set separately
| Units are not (yet) available
|-
| cost_factor
| All
| Yes, only
|
|-
| running_cost_factor
| All
| Yes, unless <code style="color:darkgreen">purchase_running_cost_factor</code> is set separately
|
|-
| cargo_age_period
| All
| No
|
|-
| cargo_capacity
| All except aircraft
| Yes, unless <code style="color:darkgreen">purchase_cargo_capacity</code> is set separately
|
|-
| passenger_capacity
| Aircraft
| Yes, unless <code style="color:darkgreen">purchase_passenger_capacity</code> is set separately
|
|-
| mail_capacity
| Aircraft
| Yes, unless <code style="color:darkgreen">purchase_mail_capacity</code> is set separately
|
|-
| range
| Aircraft
| Yes, unless <code style="color:darkgreen">purchase_range</code> is set separately
|
|-
| visual_effect_and_powered
| Trains
| No
|
|-
| visual_effect
| Road Vehicles, Ships
| No
|
|-
| power
| Trains, Road Vehicles
| Yes, unless <code style="color:darkgreen">purchase_power</code> is set separately
| Units are not (yet) available
|-
| weight
| Trains, Road Vehicles
| Yes, unless <code style="color:darkgreen">purchase_weight</code> is set separately
| Units are not (yet) available
|-
| length
| Trains, Road vehicles
| No
|
|-
| tractive_effort_coefficient
| Trains, Road Vehicles
| Yes, unless <code style="color:darkgreen">purchase_tractive_effort_coefficient</code> is set separately
| Value range is 0 .. 255 instead of 0 .. 1.
|-
| bitmask_vehicle_info
| Trains
| No
|
|}

===Sprites in GUI===
{{ottdp|1.2|no|ottdrev=r23080}} Since OpenTTD r23080 you can use variable <code style="color:darkgreen">extra_callback_info1</code> to display different sprites in the GUI and on the map. Currently these cases are available:
{| |-
! Lowest byte of extra_callback_info1 !! Meaning
|-
| 0x00 || Vehicle is drawn in a viewport, i.e. on the map.
|-
| 0x01..0x0F || reserved
|-
| 0x10 || Vehicle is drawn in the depot GUI. <ref>OpenTTD also uses this value with the purchase-list chain (cargotype FF) to determine the gridsize in ship and aircraft depots.</ref>
|-
| 0x11 || Vehicle is drawn in the vehicle details GUI. (This includes the refit GUI.)
|-
| 0x12 || Vehicle is drawn in the vehicle list.
|-
| 0x13..0x1F || reserved for other future GUIs.
|-
| 0x20 || Vehicle is drawn in the purchase list. (This includes the autoreplace GUI.)
|-
| 0x21 || Vehicle is drawn in the exclusive preview GUI or in the advertisement news.
|-
| 0x22..0x2F || reserved for other future GUIs with non-purchased vehicles.
|-
| 0x30..0xFF || reserved
|}
<references/>
The other bytes of variable <code style="color:darkgreen">extra_callback_info1</code> are reserved, and must be masked.
The cases 0x20..0x2F are called using the <code style="color:darkgreen">purchase</code>-callback, the other cases are called for the <code style="color:darkgreen">default</code>- or cargo-specific callbacks. Exception is the the special depot-gridsize call, which uses the <code style="color:darkgreen">purchase</code>-callback.

===Sound events===

{| class="t"
! Event
! Description
|-
| SOUND_EVENT_START
| Vehicle leaves station or depot, plane takes off
|-
| SOUND_EVENT_TUNNEL
| Vehicle enters tunnel
|-
| SOUND_EVENT_BREAKDOWN
| Vehicle breaks down (not for planes)
|-
| SOUND_EVENT_RUNNING
| Once per engine tick, but no more than once per vehicle motion
|-
| SOUND_EVENT_TOUCHDOWN
| Aircraft touches down
|-
| SOUND_EVENT_VISUAL_EFFECT
| Visual effect is generated (steam plume, diesel smoke, electric spark)
|-
| SOUND_EVENT_RUNNING_16
| Every 16 engine ticks if in motion
|-
| SOUND_EVENT_STOPPED
| Every 16 engine ticks if stopped
|-
| SOUND_EVENT_LOAD_UNLOAD
| Consist loads or unloads cargo
|}

NML:Item

2012-08-02T20:34:21Z

Hirundo: /* General */ Remove note about cargo slots, mention feature-specific pages instead

{{NMLNavBlocksyntax}}

== General ==

item (<expression> [, <ID> [, <expression>]]) {
(<property-block>|<graphics-block>|<livery_override-block>)+
}

The first argument is the feature of the item, the second (optional) argument is the name used to identify the object throughout the NML file and the third (optional) argument is the numerical id you want to use for this item. The meaning and relevance of this id differs per-feature, refer to the feature-specific pages for more information.

Example:

<pre style="color:blue">
item (FEAT_ROADVEHS, hereford_tram) {
property {
name: string(STR_NAME_HEREFORD_TRAM);
climates_available: ALL_CLIMATES;
introduction_date: date(1940,1,1);
speed: 60 km/h;
}
}
</pre>

== Property block ==

property {
(<ID>: (<string>|(<expression> [<unit>]));)+
}

This one looks a lot more complicated than it actually is. A property-block contains one or more assignments. Each assignment starts with the name of the property that is changed followed by a colon. After the colon follows the value and you end the line with a semicolon. The type of the value depends on the property, some properties require a string as value and some an expression. For some properties you can optionally specify a unit that is used to convert the value to the unit that is written to the output file. You can only use a unit if the expression is constant. [[NML:Units|List of valid units]]

== Graphics block ==

A graphics block must be placed in an item-block. It allows to define the graphics for a particular item, as well as various callbacks. Callbacks are used to define various things at run time, based on information (variables) of the item itself. This provides a much greater degree of flexibility than setting properties. An example (using fictional callback names):

<pre style="color:blue">
graphics {
callback_a: switch_a;
callback_b: return 42 + some_var;
default: some_spritegroup;
}
</pre>

The callbacks that are available differ per feature, refer to the feature-specific pages for more information. The 'default'-callback is usually used to resolve the graphics. For each callback a return value may be specified, in the same way as for [[NML:Switch| switch-blocks]]. Note that all callbacks have to be defined in a '''single''' graphics-block.

For vehicles and stations, a cargo type (identifier from the [[NML:Cargotable|cargo table]]) may be used as callback name, to provide cargo-specific graphics.

== Livery override ==

[[Image:NML liveryoverride.png|frame|left|Same cars, different engine, different car sprites]]

A livery override block offers the option to change the look and behaviour of a wagon depending on the engine it is attached to. It is basically the same as a graphics-block and its syntax is the same. The difference is that it only applies to a particular combination of an engine and a wagon. E.g. passenger wagons could adapt their livery to match the engine, to make the consist look like a multiple-unit train. The spritegroup needs to be defined before it can be used in a livery override. A livery override block is always part of the '''engine''' definition and looks like

livery_override (vehicleID) {
callback_name: switch_name;
callback_name2: return value;
default: spritegroup_name;
}

For an example see the [[NML:Spritegroup|spritegroup]]

NML:Railtypes

2012-08-02T20:24:38Z

Hirundo: Add note about item IDs

{{NMLNavPropVarCB}}

Railtypes can only be defined in OpenTTD {{ottd|1.0|r18969}} or later.

==Railtype IDs==
Railtype IDs are limited to 16 in total. NewGRF-local IDs may freely be chosen, but must be in the 0..15 range. If other railtype GRFs are loaded, it may be that there are not enough railtype slots available. To prevent your entire NewGRF from being deactivated with the 'Attempt to use invalid ID'-error, you can use the following code:

if (railtype_available("LABL") || loading_stage == LOADING_STAGE_RESERVE)
... item definition ...
} else if (loading_stage == LOADING_STAGE_ACTIVATE) {
... warning / error ...
}
The warning / error is optional, but can be used to inform the user about the missing railtypes.

==Railtype properties==

{| class="t"
! property
! value range
! comment
|-
| label
| 4-byte string
| names of default rail types: "RAIL", "ELRL", "MONO", "MGLV". See the [[RailtypeLabels|List of railtype labels]] in the NewGRF Specs for currently defined custom labels.
|-
| introduction_date
| date(yyyy,mm,dd)
|
{{ottd|1.1|r21842}} Valid range for yyyy is 0 ... 5000000.
|-
| name
| string
| Name of this railtype
|-
| toolbar_caption
| string
| {{ottdp|1.2|no|ottdrev=23129}} Caption of the build rail toolbar. In earlier versions this is the same as the 'name'
|-
| menu_text
| string
| Shown in the dropdown menu for all railtypes
|-
| build_window_caption
| string
| Caption of the build vehicle window
|-
| autoreplace_text
| string
| String for the autoreplace window
|-
| new_engine_text
| string
| String for the "We have invented a new <rail type> engine" news message
|-
| compatible_railtype_list
| list of railtype labels
| Provide a list of rail types that trains of this type can also run on. e.g. ["RAIL", "ELRL", "MONO"]
|-
| powered_railtype_list
| list of railtype labels
| Provide a list of rail types that trains of this type are powered on.
|-
| railtype_flags
| bitmask(RAILTYPE_FLAG_XXX, ...)
| XXX = [CATENARY <nowiki>|</nowiki> NO_LEVEL_CROSSING] Flags enable catenary and/or disable level crossings.
|-
| curve_speed_multiplier
| 0...65525
| max curve speed is defined as multiple of the base curve speed (see below)
|-
| station_graphics
| RAILTYPE_STATION_NORMAL, RAILTYPE_STATION_MONORAIL, RAILTYPE_STATION_MAGLEV
| Type of station graphics to use for the default stations
|-
| construction_cost
| 0 ... 65525
|
{{ottd|1.1|r19307}} per piece of track as multiplier to PR_BUILD_RAIL base cost. Default cost factors are 8, 12, 16 and 24 for RAIL, ELRL, MONO and MGLV.
|-
| speed_limit
| 0 ... 65525 km/h (speed units)
| A speed limit of 0 means unlimited speed
|-
| acceleration_model
| ACC_MODEL_RAIL, ACC_MODEL_MONORAIL, ACC_MODEL_MAGLEV
| ACC_MODEL_RAIL and ACC_MODEL_MONORAIL behave the same currently
|-
| map_colour
| 0 ... 255
|
{{ottd|1.1|r19307}} entry in the colour palette.
|-
| requires_railtype_list
| list of railtype labels
|
{{ottd|1.1|r21842}} List of rail types on that need to be available to the company of the player for this rail type to be introduced at (or after) the introduction date. This limit does not apply when the rail type is introduced by the introduction of a vehicle.
|-
| introduces_railtype_list
| list of railtype labels
|
{{ottd|1.1|r21841}} List of rail types that get introduced when this rail type is introduced. For example, to make sure that when a fast rail type is introduced the slow variant exists.
|-
| sort_order
| 0 ... 255
|
{{ottd|1.1|r21866}} number which defines the sort order among rail types. If this entry is not defined, it gets assigned sort order n*10+7 for the n-th railtype.
|-
| maintenance_cost
|
|
{{ottd|1.2|r23415}} Maintenance cost factor for each piece of tracks of this railtype. Default cost factors are 8, 12, 16 and 24 for RAIL, ELRL, MONO and MGLV.
|-
| alternative_railtype_list
| list of railtype labels
|
{{ottd|1.2|r23758}} List or rail types which this rail type will act as fallback for, if the corresponding rail type is not defined separately
|}

===Sort order===

The sort_order influences the sort order of the drop down lists with rail types. Default values are as follows:

{| class="t"
! Value
! Meaning
|-
| 07
| normal rail
|-
| 17
| electrified rail
|-
| 27
| monorail
|-
| 37
| maglev
|-
| n7
| railtype #n
|}

Thus the rail type that (internally) gets index 8 will get a default value of 87. These defaults are to keep the ordering when this property is not supported as they were.

===Base speeds for curves===

The base speeds relevant for the curve_speed_multiplier are:

{| class="t"
! curve length
! base speed [km/h]
|-
| 0 (90 degree turn)
| 30
|-
| 1
| 44
|-
| 2
| 55
|-
| 3
| 66
|-
| 4
| 75
|-
| 5
| 84
|-
| 6
| 91
|-
| 7
| 98
|-
| 8
| 103
|-
| 9
| 108
|-
| 10
| 111
|-
| 11
| 114
|-
| 12+
| 115
|}

==Railtype variables==

{| class="t"
! name
! value range
! comment
|-
| terrain_type
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|
|-
| enhanced_tunnels
| 0
| should custom tunnel entrances be modified other values than 0 might be returned
|-
| level_crossing_status
| LEVEL_CROSSING_CLOSED, LEVEL_CROSSING_OPEN
|
|-
| build_date
| 0 .. 5000000
| for depots only: build date of the depot in days since 0
|}

==Railtype callbacks==

For rail types a number of callbacks are used to define rail type graphics. Each should refer to a sprite set containing the relevant sprites. Refer to the [[#Example sprites|example sprites]] or the example railtype grf in the NML repository, for an example on what sprites are needed in what order.

{| class="t"
! callbacks
! number of sprites
! meaning
|-
| gui
| 16
| 4 rail directions, autorail, depot, tunnel and convert rail sprites for rail menu
|-
| track_overlay<ref name=leftout>Either all or none of these sprites should be provided.</ref>
| 10
| 6 flat and 4 slope sprites. Track without landscape
|-
| underlay<ref name=leftout />
| 16
| 6 flat and 4 slope, one crossing WITH track, 5 junction pieces without track. Tracks with ballast but without landscape
|-
| tunnels<ref name=leftout />
| 4
| 1 sprite for each direction. Sprite is overlay for track in existing tunnel graphics. The original ground sprite is drawn, then the overlay, then possibly a train and the original tunnel head is drawn over the top. This keeps compatibility with different landscape types. Sprite order: SW, NW, NE, SE.
|-
| catenary_wire
| 28
|
|-
| catenary_pylons
| 8
|
|-
| bridge_surfaces<ref name=leftout />
| 6
|
|-
| level_crossings<ref name=leftout />
| 10
| For each direction: one track sprite and 4 sprites for road lights etc
|-
| depots<ref name=depotr22854>{{ottd|1.2|r22854}} In OpenTTD prior to r22854, depot sprites would not be used if the above 'all or none' sprites were not supplied.</ref>
| 6
| 2 sprites for each south-ish, 1 sprite for each north-ish depot. Like original depots.
|-
| fences
| 8
| x, y, vertical, horizontal, SW, SE, NE and NW slopes like original fences at sprite 1301
|-
| tunnel_overlay<ref name=tunnel_overlay>Above 'all or none' sprites must be supplied, if these sprites are to be used.</ref>
| 4
| If this callback is defined, tunnels for this railtype will be drawn differently. First, a grass underlay base sprite is drawn, then the 'tunnels'-sprite. Next, train sprites if applicable and then a grass overlay and finally the sprite from this type (tunnel_overlay). The grass sprites are defined in the base set and do not contain any parts of the tracks or portal, so these have to be fully provided by the railtype sprites. <code style:darkgreen>extra_callback_info1</code> contains 0 for normal tunnels, without any extra features (like tracks above). All other values are reserved for future extensions.
|-
| signals
| 8
| {{ottd|1.3|r24367}} 1 sprite for each direction, order is SW(-facing), NE, SE, NW, E, W, S, N. For more information, see [[#signals|below]]
|}

<references />
If a callback is not implemented or fails, graphics from the fallback railtype (picked via the <code style="color:darkgreen">station_graphics</code> property) will be used instead. 
Note that there is no "default graphics"-callback.

===Example sprites===
==== gui ====

[[File:railtype_gui.png]]

==== track_overlay ====

[[File:railtype_overlay.png]]

==== underlay ====

[[File:railtype_underlay.png]]

==== level_crossings ====

You can define a special track piece which crosses the road and for each of two directions and each of the corners of the tile a separate sprite for a light, sign, or whatever should go there.

{| class="wikitable"
|-
!Sprite number for X
!Sprite number for Y
!Useage
|-
|0
|    1
|    Rail overlay
|-
|2
|    3
|    North light
|-
|4
|    5
|    East light
|-
|6
|    7
|    West light
|-
|8
|    9
|    South light
|}

[[File:railtype_levelcrossing.png]]

==== depots ====

{| class="wikitable
|-
!Sprite Number
!Usage
|-
|0
|    NE wall for SE-entry depot.
|-
|1
|    Depot building for SE-entry depot.
|-
|2
|    NW wall for SW-entry depot.
|-
|3
|    Depot building for SW-entry depot.
|-
|4
|    Depot building for NE-entry depot.
|-
|5
|    Depot building for NW-entry depot.
|}

==== fences ====

[[File:railtype_fences.png]]

==== tunnel_overlay ====

If this callback is defined, tunnels for this railtype will be drawn differently.

First, a grass underlay base sprite is drawn, then the 'tunnels'-sprite. Next, train sprites if applicable and then a grass overlay and finally the sprite from this callback. The grass sprites are defined in the base set and do not contain any parts of the tracks or portal, so these have to be fully provided by the railtype sprites.

Illustration: [[File:RailtypeTunnelExample.png]]

==== signals ====

This callback can be used to supply custom signal graphics.

The resulting sprite set must consist of 8 sprites, corresponding to the following signal directions: SW-facing, NE-facing, NW-facing, SE-facing, E-facing, W-facing, S-facing, N-facing. Variable <code style:darkgreen>extra_callback_info2</code> contains information about the kind of signal to be drawn. If resolving fails or results in an empty sprite group, the matching base set sprite will be used instead.

'''Format of extra_callback_info2:''' 0xRRTTVVSS

{| |-
! TT: Signal type !! Meaning
|-
| 0 || Normal block signal
|-
| 1 || Entry pre-signal
|-
| 2 || Exit pre-signal
|-
| 3 || Combo pre-signal
|-
| 4 || Two-way path signal
|-
| 5 || One-way path signal
|-
| all other values || Reserved
|}

{| |-
! VV: Signal variant !! Meaning
|-
| 0 || Light (electric) signal
|-
| 1 || Semaphore
|-
| all other values || Reserved
|}

{| |-
! SS: Signal state !! Meaning
|-
| 0 || Red signal
|-
| 1 || Green signal
|-
| all other values || Reserved
|}

The most significant byte (RR) is reserved and must be and-masked out.

<code style:darkgreen>extra_callback_info1</code> can be used to distinguish between map and GUI sprites:
{| |-
! Lowest byte of [[GlobalVariables#Extra_callback_info_.2810_.2F_-.29_and_.2818_.2F_-.29|variable 10]] !! Meaning
|-
| 0 || Signal is drawn in a viewport, i.e. on the map.
|-
| 0x10 || Signal is drawn in the signal GUI. The returned sprite set must still have 8 sprites, but OpenTTD will only use the 7th sprite, so all other sprites can be empty.
|-
| all other values || Reserved
|}
The other bytes of <code style:darkgreen>extra_callback_info1</code> are reserved, and must be masked.

===Example code===

A typical implementation for railtypes can look like:

<pre style="color:blue">
item(FEAT_RAILTYPES, elrail, 0x01) {
property {
label: "SHIN";
name: string(STR_EL_RAIL);
menu_text: string(STR_EL_RAIL);
build_window_caption: string(STR_BUILD_CAPTION);
autoreplace_text: string(STR_AUTOREPLACE);
new_engine_text: string(STR_NEW_ENGINE);
compatile_railtype_list: ["SHIN","RAIL","ELRL"]; // Tracks of rail and electrified rail are compatible
powered_railtype_list: ["ELRL","SHIN"]; // But we got only power when we have electricity
railtype_flags: bitmask(RAILTYPE_FLAG_NO_LEVEL_CROSSING); // High speed tracks should not have level crossings
curve_speed_multiplier: 1;
station_graphics: RAILTYPE_STATION_MAGLEV; // We want the most modern stations
construction_cost: 32; // should be pretty steep
speed_limit: 500 km/h;
acceleration_model: ACC_MODEL_RAIL; // This is still rail, though
}
graphics {
track_overlay: ground_switch_overlay; // defines the sprites drawn as overlay for junctions and highlight
underlay: ground_switch_underlay; // defines the usual tracks and the underlay for junctions
level_crossings: level_crossing_switch; // defines level crossings including traffic lights and blocking bars
tunnels: tunnel_switch; // defines the tracks drawn on a funnel tile
depots: depot_switch_electric; // defines the depot sprites
bridge_surfaces: bridge_terrain_switch; // defines the overlay drawn over bridges
fences: fences_set; // defines the look of fences
// we don't define catenery wire and pylons, thus we use the default which comes with the base graphics.
}
}
</pre>

The switches and graphics blocks are defined in the usual way as described in sections [[NML:Switch|switches]], [[NML:Random switch|random switches]] and [[NML:Graphics|graphics block]] sections.

NML:Airports

2012-08-02T20:16:49Z

Hirundo: Add note about substitute/override

{{NMLNavPropVarCB}}

Airports and airport tiles can only be defined in OpenTTD {{ottd|1.1|r19459}} or later.

==Airport (tile) IDs==
Airport and airport tile IDs are local to the NewGRF, you are free to choose any ID in the 0..255-range. For airport tiles, you should start your item definition with the 'substitute'-property, which allocates a new airport tile. The value of this property should be the ID of a [[AirportTileDefaultProps|default airport 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 airport tile to be replaced with your item. For airports, there only is an 'override'-property, which acts as a combined substitute and override.

==Airport properties==

{| class="t"
! name
! value range
! comment
|-
| name
| string
|
{{ottd|1.1|r19459}} Name of the airport
|-
| override
|
|
{{ottd|1.1|r19459}} The id of airport to replace / override, see [[AirportTypes]].
|-
| layouts
| list of layouts
|
{{ottd|1.1|r20377}}
|-
| years_available
| [start year, last year]
|
{{ottd|1.1|r19459}} List of the availablility years: first and last year it can be built
|-
| ttd_airport-type
| 0 ... 3
|
{{ottd|1.1|r19459}} Substitute TTDPatch airport type
|-
| catchment_area
|
|
{{ottd|1.1|r19459}} Catchment area of the airport in tiles around its perimeter
|-
| noise_level
|
|
{{ottd|1.1|r19459}} Noise generation of this airport
|-
| maintenance_cost
|
|
{{ottd|1.2|r23415}} Maintenance cost factor for this airport
|}

==Airport tile properties==

{| class="t"
! name
! value range
! comment
|-
| override
|
|
{{ottd|1.1|r19204}} The id of airport tile to override, see [[AirportTypes]].
|-
| substitute
|
|
{{ottd|1.1|r19204}} The id of airport tile to replace
|-
| callback_flags
| bitmask
|
{{ottd|1.1|r19204}} Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| animation_info
|
|
{{ottd|1.1|r19204}}
|-
| animation_speed
|
|
{{ottd|1.1|r19204}} See [[NML:Animation speed|speed settings]]
|-
| animation_triggers
| bitmask(ANIM_TRIGGER_APT_XXX, ... )
|
{{ottd|1.1|r19204}} Bitmask of triggers that will trigger the <code style="color:darkgreen">anim_control</code> callback, see the [[#Animation triggers|table]] below.
|}

==Airport variables==

{| class="t"
! name
! value range
! comment
|-
| layout
| 0 .. (number of layouts - 1)
|
{{ottd|1.1|r20364}} Layout number of the airport (index in the layouts array)
|}

==Airport tile variables==

{| class="t"
! name
! value range
! comment
|-
| terrain_type
|
|
|-
| town_radius_group
|
|
|-
| 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 [[NML:Builtin functions|builtin function]] relative_coord(x, y) may be useful when making comparisons.
|-
| animation_frame
|
|
|}

The following variables require a signed x,y offset as parameters. The offset is relative to the current tile. Offset 0,0 means the current tile.

{| class="t"
! name
! value range
! comment
|-
| nearby_tile_slope
| SLOPE_XXX
|
See [[NML:List of tile slopes|tile slopes]] for an overview of possible values
|-
| nearby_tile_is_same_airport
| 1 if the tile is part of the same airport, 0 otherwise
|
|-
| 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 <nowiki>|</nowiki> SEA <nowiki>|</nowiki> CANAL <nowiki>|</nowiki> RIVER] Note that tiles for which <code style="color:darkgreen">nearby_tile_is_water</code> 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
|
[[NML:List of tile classes|Tile class]]
|
|-
| nearby_tile_animation_frame
| 0..255
| Animation frame of the given tile
|-
| nearby_tile_airporttile_id
| 0x00aa, 0xFFbb, 0xFFFE or 0xFFFF
| 0x00aa: The tile is an airport tile that is part of this GRF, the tile id is aa. 0xFFbb: The tile is an original airport tile with id bb. 0xFFFE: The tile is an airport tile defined in another GRF. 0xFFFF: The tile is not an airport tile or it belongs to another GRF.
|}

==Airport callbacks==

{| class="t"
! callback
! return value
! comment
|-
| default
| Sprite set (with 1 sprite)
| Preview graphics to use in the build menu. One sprite per layout may be given, use the <code style="color:darkgreen">layout</code> to distinguish between layouts.
|-
| additional_text
| String
| Additional text to show in the buy menu. String may differ per layout, use the <code style="color:darkgreen">layout</code> variable for this.
|-
| layout_name
| String
| Name of the airport layout in the variable <code style="color:darkgreen">layout</code>
|}

Note that, although the airport isn't built yet, the <code style="color:darkgreen">layout</code> variable is always available and set to the layout the user has selected in the GUI.

==Airport tile callbacks==

{| class="t"
! callback
! return value
! comment
|-
| default
| Sprite layout
| Graphics for an airport tile
|-
| 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. <code style="color:darkgreen">extra_callback_info1</code> contains random bits. Returning a sound effect in the high byte will cause that sound effect to be played.
|-
| 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 <nowiki>|</nowiki> STOP_ANIMATION <nowiki>|</nowiki> DO_NOTHING] to respectively start the animation in its current frame, stop the animation or do nothing. <code style="color:darkgreen">extra_callback_info1</code> contains random bits. Returning a sound effect in the high byte will cause that sound effect to be played. <code style="color:darkgreen">extra_callback_info2</code> contains the reason to trigger the animation, see the [[#Animation triggers|table]] below. Note that you need to enable the wanted triggers in the <code style="color:darkgreen">animation_triggers</code> property.
|-
| 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.
|-
| foundations
| CB_RESULT[_NO]_FOUNDATIONS
| Return CB_RESULT_FOUNDATIONS to draw standard foundations (default) or CB_RESULT_NO_FOUNDATIONS to not draw them.
|}

===Animation triggers===

{| class="t"
! Animation trigger
! Description
|-
| ANIM_TRIGGER_APT_BUILT
| Airport is built (all tiles at the same time)
|-
| ANIM_TRIGGER_APT_TILELOOP
| Airport tile is processed in the tileloop (at different times for different tiles)
|-
| ANIM_TRIGGER_APT_NEW_CARGO
| New cargo arrives at the airport (all tiles at the same time)
|-
| ANIM_TRIGGER_APT_CARGO_TAKEN
| All cargo of a cargo type is removed from the airport (all tiles at the same time)
|-
| ANIM_TRIGGER_APT_250_TICKS
| Every 250 ticks (all tiles at the same time)
|}

NML:Objects

2012-08-02T20:11:35Z

Hirundo: Add note about object IDs

{{NMLNavPropVarCB}}

==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==

{| class="t"
! 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 object classes|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 <nowiki>|</nowiki> ARCTIC <nowiki>|</nowiki> TROPICAL <nowiki>|</nowiki> 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|list of object flags]]
|-
| animation_info
| Array [ANIMATION_XXX, frame-count]
| XXX = [LOOPING <nowiki>|</nowiki> NON_LOOPING], 1..253 frames
|-
| animation_speed
| 0..16
|
Speed of animation, see [[NML:Animation speed|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 [[NML:Old style callbacks|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 <code style="color:darkgreen">view</code> to determine the view of a built object.
|}

===Default object classes===

Please refer to the [[ObjectLabels|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===

{| class="t"
! 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==

{| class="t"
! 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 [[NML:Builtin functions|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 [[NML:List of tile slopes|tile slopes]] for an overview of possible values
|-
| build_date
|
| The date this object was build.
|-
| animation_frame
| 0..255
| Current animation frame
|-
| company_colour
| COLOUR_XXX
|
Colour used for the company colour mask. Refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|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
|
[[NML:List of town zones|town zone]]
| The town zone of the current tile. The town zone from the closest town (measured in manhattan distance) is used.
|-
| view
| 0 .. <code style="color:darkgreen">num_views</code> - 1
|
{{ottd|1.1|r21455}} The view of the particular object. See also the <code style="color:darkgreen">num_views</code> property.
|}

Variables that require one or more parameters:

{| class="t"
! 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 <nowiki>|</nowiki> SEA <nowiki>|</nowiki> CANAL <nowiki>|</nowiki> RIVER] Note that tiles for which <code style="color:darkgreen">nearby_tile_is_water</code> 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)
|
[[NML:List of tile classes|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 [[NML:Builtin functions|builtin function]] <code style="color:darkgreen">str2number()</code> 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 [[NML:Builtin functions|builtin function]] <code style="color:darkgreen">str2number()</code> to convert a grfid to its numeric representation. If the given object type is not yet built, this will return 0xFFFF
|}

==Object callbacks==

{| class="t"
! 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. <code style="color:darkgreen">extra_callback_info1</code> 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. <code>return (sound("mysound.wav") << 8) <nowiki>|</nowiki> CB_RESULT_NEXT_FRAME;</code>).
|-
| 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 <nowiki>|</nowiki> STOP_ANIMATION <nowiki>|</nowiki> DO_NOTHING] to respectively start the animation in its current frame, stop the animation or do nothing. <code style="color:darkgreen">extra_callback_info1</code> contains random bits if the object flag OBJ_FLAG_RANDOM_ANIMATION is set. <code style="color:darkgreen">extra_callback_info2</code> contains the reason to trigger the animation, see the [[#Animation triggers| 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 <code style="color:darkgreen">extra_callback_info1</code> 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 [[NML:List of default colour translation palettes#Company colour helper functions|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 [[NML:Industries#Location check results|location_check]] industry callback
| Parameters: <code style="color:darkgreen">extra_callback_info1</code> contains the slope in bits 0..4 (see below), all other bits are reserved and should be and-masked out. <code style="color:darkgreen">extra_callback_info2</code> 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
|}

<nowiki>* 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.</nowiki>

===Animation triggers===

{| class="t"
! 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)
|}

NML:Cargos

2012-08-02T20:07:49Z

Hirundo: Add note about cargo IDs corresponding to cargo slots

{{NMLNavPropVarCB}}

==Cargo IDs==
For cargos, the item ID corresponds to the cargo type slot of the cargo. TTD default cargos occupy slots 0-11, so if you want to define a new cargo be sure to set this ID to 12 or higher. It is recommended to set the 'number'-property to the same value as the item ID.

==Cargo properties==

{| class="t"
! name
! value range
! comment
|-
| number
| 0..31
| Number of the cargo for bitmasks. This mostly affects old NewGRFs that don't have a cargo translation table.
|-
| type_name
| string
| TextID for the cargo type name. Example string: "Passengers"
|-
| unit_name
| string
| TextID for the name of one unit from the cargo type. Currently used for subsidies only (First Passenger service to..). Example string: "Passenger"
|-
| single_unit_text
| string
| TextID to be displayed for 1 unit of cargo. Example string: "{WORD_S} ton of Stuff"
|-
| multiple_units_text
| string
| TextID to be displayed for multiple units of cargo. Example string: "{WORD_S} tonnes of Stuff"
|-
| type_abbreviation
| string
| TextID for cargo type abbreviation. Example string: "{TINYFONT}XX"
|-
| sprite
| sprite
| TTD sprite number for the icon of the cargo. Alternatively, set to NEW_CARGO_SPRITE and use a graphics block to define a custom sprite.
|-
| weight
| float 0..255
| Weight of one unit of the cargo (in tons)
|-
| penalty_lowerbound
| 0..255
| Delivery time until penalty is applied
|-
| single_penalty_length
| 0..255
| Length of the interval where a single penalty is applied
|-
| price_factor
| float
| Payment for delivering 10 units of cargo across a distance of 20 squares (in British Pounds).
|-
| station_list_colour
| 0..255
|
Colour for the station list window (index from the [[NML:Graphic files|DOS palette]])
|-
| cargo_payment_list_colour
| 0..255
|
Colour for the cargo payment list window (index from the [[NML:Graphic files|DOS palette]])
|-
| is_freight
| 0 or 1
| Freight status (for the freighttrains switch); 0=not freight, 1=is freight
|-
| cargo_classes
|
bitmask([[#Cargo classes|cargo classes]])
| Cargo classes
|-
| cargo_label
| 4 letters
| Cargo label, as used in the cargo table
|-
| town_growth_effect
| TOWNGROWTH_XXX
|
Effect for town growth, see [[#Cargo effects on town growth|Cargo effects on town growth]]
|-
| town_growth_multiplier
| float 0..255
| Multiplier for town growth. To be used in conjuction with town_growth_effect, when that is not TOWNGROWTH_NONE. For example, a value of 4 makes your cargo have the same effect on town growth as 4 units of food/goods/etc.
|-
| callback_flags
| bitmask(flags)
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| capacity_multiplier
| float 0 .. 255
| {{ottd|1.2|r22860}} This defines the capacity of vehicles carrying this cargo type, if the vehicle sets no specific capacity to this specific cargo type. Set this property to the amount of cargo a vehicle shall carry, which can carry 1 ton of coal or 1000 thousand litres of water (whatever comparison is more suitable for your cargotype). Depending on whether your cargo type is light or heavy you should set this property either comparing the weight or the volume. Default values are 4 for passengers, 2 for mail, goods and sweets and 1 for all other cargos.
|}

Cargo payment is computed from <code style="color:darkgreen">price_factor</code>, amount of cargo transported, distance, and a time delivery factor. Unit of the delivery time is 185 ticks, roughly 2.5 days. The factor is constant (with value 255) if delivery time is less than <code style="color:darkgreen">penalty_lowerbound</code>. It goes down with rate 1 between <code style="color:darkgreen">penalty_lowerbound + single_penalty_length</code>, and goes down with rate 2 if the delivery time is even longer. Time delivery factor is never less than 31.

===Cargo classes===

Available cargo classes are listed in the following table. Cargos may be in more than one class. Cargo classes are always used as a bitmask, use the built-in function <code>bitmask()</code>. For example, <code style="color:darkgreen">bitmask(CC_EXPRESS, CC_REFRIGERATED)</code> is used for food.

{| class="t"
! name
! type of cargo
|-
| CC_PASSENGERS
| passengers, also tourists (ECS)
|-
| CC_MAIL
| mail
|-
| CC_EXPRESS
| express goods, also tourists (ECS)
|-
| CC_ARMOURED
| valuables, diamonds, gold and alike
|-
| CC_BULK
| coal, ore, grain,...
|-
| CC_PIECE_GOODS
| containers, crates, livestock
|-
| CC_LIQUID
| oil, milk, water, ...
|-
| CC_REFRIGERATED
| food, milk, ...
|-
| CC_HAZARDOUS
| chemicals?, uranium, ...
|-
| CC_COVERED
| grain, cement, fruit, ...
|-
| CC_OVERSIZED
| vehicles, ...
|-
| CC_POWDERIZED
| cement, ...
|-
| CC_NON_POURABLE CC_NEO_BULK
| sugar cane, wool or straw bales, ...
|-
| CC_SPECIAL
| Special cargo, used for refit tricks. (e.g. regearing in NARS)
|-
| NO_CARGO_CLASS
| Special value that you can used to instead of 0.
|-
| ALL_NORMAL_CARGO_CLASSES
| Bitmask of all cargo classes except CC_SPECIAL. This is the same as <code style="color:darkgreen">bitmask(CC_PASSENGERS, CC_MAIL, ..., CC_OVERSIZED)</code>. Note: This is already a bitmask, don't use the <code style="color:darkgreen">bitmask(..)</code> function with this.
|-
| ALL_CARGO_CLASSES
| Bitmask of all cargo classes. Same as <code style="color:darkgreen">ALL_NORMAL_CARGO_CLASSES | bitmask(CC_SPECIAL)</code> Note: This is already a bitmask, don't use the <code style="color:darkgreen">bitmask(..)</code> function with this.
|}

===Cargo effects on town growth===

{| class="t"
! value
! effect
|-
| TOWNGROWTH_PASSENGERS
| Affect towns as passengers do
|-
| TOWNGROWTH_MAIL
| Affect towns as mail does
|-
| TOWNGROWTH_GOODS
| Affect towns as goods/candy does
|-
| TOWNGROWTH_WATER
| Affect towns as water does (second required cargo for towngrowth in the desert)
|-
| TOWNGROWTH_FOOD
| Affect towns as food/fizzy drinks do (first required cargo for towngrowth in desert/above snowline)
|-
| TOWNGROWTH_NONE
| Don't affect town growth (default)
|}

==Cargo variables==

Cargos have no variables (yet).

==Cargo callbacks==

{| class="t"
! callback
! return value
! comment
|-
| default
| Sprite set (with 1 sprite)
| Graphics for the cargo icon (only if property <code style="color:darkgreen">sprite</code> is set to NEW_CARGO_SPRITE)
|-
| station_rating
| -16384 .. 16383
| See detailed explanation below
|-
| profit
| -12748 .. 12748
| Called whenever cargo is delivered. <code style="color:darkgreen">extra_callback_info2</code> contains <code style="color:darkgreen">0xttaadddd</code> with <code style="color:darkgreen">tt</code> being the time spent en-route (1 unit = 2.5 days), <code style="color:darkgreen">aa</code> the amount of cargo delivered and <code style="color:darkgreen">dddd</code> the manhattan distance it was transported. The returned value is multiplied by the amount and the <code style="color:darkgreen">price_factor</code> and then divided by 256 to determine the income the player receives. Returning negative values is possible, it makes players pay for the delivery.
|}

===Station rating callback===

The station rating callback is quite complicated and deserves some detailed explanation. The default station rating calculation works as follows:

Internally, station rating is byte with values 0 .. 255, representing respectively 0% and 100%. Every 2.5 days, the transportation 'performance' is calculated using some factors outlined below. The station rating is then set to this performance value, with the caveat that the rating change cannot exceed 2 points. Therefore, rating changes are always slow, this callback cannot change this. The initial rating is 175 points (69%). The following factors are parts of the performance, their effects are summed.

====Time since the cargo was last picked up====

{| class="t"
! Time units (days)
! Score (%, rounded)
|-
| >21 (>52.5 days)
| 0 (0%)
|-
| 13 .. 21 (32.5 days .. 52.5 days)
| 25 (10%)
|-
| 7 .. 12 (17.5 days .. 32.5 days)
| 50 (20%)
|-
| 4 .. 6 (10 days .. 17.5 days)
| 95 (37%)
|-
| 0..3 (0 days..10 days)
| 130 (51%)
|}

The time unit used equals 185 engine ticks, or 2.5 TTD days. For ships, the time units are divided by 4 before calculating this component, so ships have four times more time before the ratings start dropping.

====Amount of cargo waiting====

{| class="t"
! Amount of cargo
! Score (%, rounded)
|-
| >1500
| -90 (-35%)
|-
| 1001..1500
| -35 (-14%)
|-
| 601..1000
| 0 (0%)
|-
| 301..600
| 10 (4%)
|-
| 101..300
| 30 (12%)
|-
| 0..100
| 40 (16%)
|}

====Max. speed of the last vehicle picking up the cargo====

This calculation is somewhat complicated. The maximum speed of the vehicle is expressed in "speed units". For trains and road vehicles, the speed unit is 1 km/h; for ships, it's 0.5 km/h; for aircraft, it's 8 mph. If the max. speed is above 255 speed units, 255 is used instead. If the vehicle is slower than 85 units, no points are awarded; otherwise, you get (speed_units-85)/4 points. Therefore, the maximum you can get is 42 points, or 16%.

====Age of the last carrier picking up the cargo====

{| class="t"
! Age of vehicle (years)
! Score (%, rounded)
|-
| 2
| 10 (4%)
|-
| 1
| 20 (8%)
|-
| 0
| 33 (13%)
|}

In TTDPatch this changes when the 'newagerating' switch is enabled

====Bonus for AI companies (TTDPatch only)====

{| class="t"
! AI intelligence setting
! Score (%, rounded)
|-
| Low
| 0 (0%)
|-
| Medium
| 31 (12%)
|-
| High
| 63 (25%)
|}

====Bonus for statue in nearest town====

If your company has erected a statue in the nearest town, you get 26 points (10%) bonus to all cargo ratings.

====Callback parameters====

During the callback, <code style="color:darkgreen">extra_callback_info1</code> contains one of the following values in the lowest byte:

{| |-
!value!!meaning
|-
|0x10||the last vehicle entering the station was a train
|-
|0x11||the last vehicle entering the station was a road vehicle
|-
|0x12||the last vehicle entering the station was a ship
|-
|0x13||the last vehicle entering the station was an aircraft
|-
|0||no vehicle entered the station yet, or (TTDPatch) the last one entering was sold
|}

Please note that there's only one "last vehicle type" field per station, so the vehicle this refers to may not have picked up any of your cargo.

<code style="color:darkgreen">extra_callback_info2</code> has the value <code style="color:darkgreen">0xssaaaatt</code>, where
* <code style="color:darkgreen">tt</code> is the time since the cargo was last picked up, in the time units described above (1 unit = 2.5 days independent of vehicle type)
* <code style="color:darkgreen">aaaa</code> is the amount of cargo waiting
* <code style="color:darkgreen">ss</code> is the speed of the last vehicle picking the cargo up, in the speed units described above (if no vehicle entered the station yet, the value is 0xFF)

====Effect of callback====

The return value of the callback replaces the first three components (time since pickup, amount of cargo, max speed) of the calculation. The bonus for statues, TTDPatch AIs and new vehicles is always in effect, you cannot (yet) change this.

NML:Industries

2012-08-02T19:22:24Z

Hirundo: Add note about industry substitute/overrides

{{NMLNavPropVarCB}}

This page contains information on both industry and industry tile properties, variables and callbacks.

== Industry (tile) ID allocation ==
Industry and 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 [[IndustryDefaultProps|default industry]] or [[IndustryTileDefaultProps|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 properties==

Industry properties. Default industry type numbers can be found at [[NML:Default industries|default industries]].

{| class="t"
! property
! value range
! comment
|-
| substitute
| industry type
| Number of the original industry type that replaces this one, should it not be available for some reason (e.g. missing NewGRF). This ''must'' be the first property to be set, before any other properties or graphics. All properties of the old type are copied to your new industry.
|-
| override
| industry type
| Number of the original industry type overridden. This will cause other grfs / industries to consider your industry type the same as the old type. Only set this property if your type is (more or less) the same as the old type.
|-
| layouts
| Array of tilelayouts
|
See [[NML:Tilelayout|Tilelayout]] syntax.
|-
| life_type
| One of IND_LIFE_TYPE_XXX, XXX = BLACK_HOLE <nowiki>|</nowiki> EXTRACTIVE <nowiki>|</nowiki> ORGANIC <nowiki>|</nowiki> PROCESSING
| The generic type of industry. This determines the production changes that occur by default (when not using the callback). Examples are respectively power plants, coal mines, forests en steel mills.
|-
| closure_msg
| string
|
Message displayed when the industry announces closure. Use a custom string or one of the [[NML:Default TTD strings|default TTD strings]].
|-
| prod_increase_msg
| string
|
Message displayed when industry increases production. Use a custom string or one of the [[NML:Default TTD strings|default TTD strings]].
|-
| prod_decrease_msg
| string
|
Message displayed when industry decreases production. Use a custom string or one of the [[NML:Default TTD strings|default TTD strings]].
|-
| fund_cost_multiplier
| 0..255
| Fund cost multiplier. Note that in OpenTTD the unmodified base cost is 8x higher for building (not prospecting) raw (=extractive / organic, see life_type) industries.
|-
| prod_cargo_types
| array of up to 2 ints
| Types of cargo produced. Use the cargotype(<label>) built-in function to specify a label from the cargotable.
|-
| accept_cargo_types
| array of up to 3 ints
| Types of cargo accepted. Use the cargotype(<label>) built-in function to specify a label from the cargotable
|-
| prod_multiplier
| array of up to 2 ints (0..255)
| Amount of each output cargo to produce every 256 ticks (8 or 9 times a month)
|-
| min_cargo_distr
| 0..255
| Minimal amount of cargo before transporting to stations.
|-
| random_sound_effects
| array of ints
| Sound effect numbers that are played some times.
|-
| conflicting_ind_types
| array of up to 3x industry_type(IND_TYPE_OLD <nowiki>|</nowiki> IND_TYPE_NEW, id)
|
Three industry types that should not be nearby. Use the [[NML:Builtin functions|builtin function]] <code style="color:darkgreen">industry_type(..)</code> to define either an old industry (using the global ID) or a new industry from your grf (using the grf-local ID).
|-
| prob_random
| 0..255
| Probability of occurring while generating initial industries.
|-
| prob_in_game
| 0..255
| Probability of occurring while creating industries during the game.
|-
| map_colour
| 0..255
|
Colour index from the [[NML:Graphic files|DOS palette]] to use on the minimap for this industry.
|-
| spec_flags
| bitmask(flags)
|
for flag values see [[#industry_special_flags|Industry special flags]]
|-
| new_ind_msg
| string
| Message displayed when industry gets built during game play.
|-
| input_multiplier_1
| array of up to 2 floats (0..255)
| Output cargo multiplication factors for getting a unit of the first accepted cargo.
|-
| input_multiplier_2
| array of up to 2 floats (0..255)
| Output cargo multiplication factors for getting a unit of the second accepted cargo.
|-
| input_multiplier_3
| array of up to 2 floats (0..255)
| Output cargo multiplication factors for getting a unit of the third accepted cargo.
|-
| name
| string
|
Name of the industry, use a custom string or one of the [[NML:Default TTD strings|default TTD strings]].
|-
| prospect_chance
| 0 .. 1 (float)
| Chance of successful prospecting.
|-
| callback_flags
| bitmask(flags)
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| remove_cost_multiplier
| int
| Cost multiplier for removing the industry (currently only possible with magic bulldozer).
|-
| nearby_station_name
| string
| Default additional name for a nearby station
|}

===Industry special flags===

{| class="t"
! flag
! meaning
|-
| IND_FLAG_PLANT_FIELDS_PERIODICALLY
| The industry periodically plants fields around itself (temperate and arctic farms)
|-
| IND_FLAG_CUT_TREES
| The industry cuts trees around itself and produces its first output cargo from them (lumber mill)
|-
| IND_FLAG_BUILT_ON_WATER
| The industry is built on water (oil rig)
|-
| IND_FLAG_ONLY_IN_LARGE_TOWNS
| The industry can only be built in towns (i.e. it has to replace houses) with population larger than 1200 (temperate bank)
|-
| IND_FLAG_ONLY_IN_TOWNS
| The industry can only be built in towns (i.e. it has to replace houses) (arctic and tropic banks, water tower)
|-
| IND_FLAG_BUILT_NEAR_TOWN
| The industry is always built near towns (i.e. near town sign; additionally the industry is allowed to replace houses) (toy shop)
|-
| IND_FLAG_PLANT_FIELDS_WHEN_BUILT
| Fields are planted around the industry when it's built (all farms)
|-
| IND_FLAG_NO_PRODUCTION_INCREASE
| The industry cannot increase its production on the temperate climate (oil wells)
|-
| IND_FLAG_BUILT_ONLY_BEFORE_1950
| The industry is built only before 1950 (oil wells)
|-
| IND_FLAG_BUILT_ONLY_AFTER_1960
| The industry is built only after 1960 (oil rig)
|-
| IND_FLAG_AI_CREATES_AIR_AND_SHIP_ROUTES
| AI players will attempt to establish air and ship routes going to this industry (oil rig)
|-
| IND_FLAG_MILITARY_AIRPLANE_CAN_EXPLODE
| The industry can be exploded by a military airplane (oil refinery)
|-
| IND_FLAG_MILITARY_HELICOPTER_CAN_EXPLODE
| The industry can be exploded by a military helicopter (factory)
|-
| IND_FLAG_CAN_CAUSE_SUBSIDENCE
| The industry can cause a subsidence (coal mine)
|-
| IND_FLAG_AUTOMATIC_PRODUCTION_MULTIPLIER
| Automatic production multiplier handing (No industry has this bit set by default.).
|-
| IND_FLAG_RANDOM_BITS_IN_PRODUCTION_CALLBACK
| The production callback needs random bits in var. 10 (No industry has this bit set by default.)
|-
| IND_FLAG_DO_NOT_FORCE_INSTANCE_AT_MAP_GENERATION
| Do not force one instance of this type to appear during initial map generation (No industry has this bit set by default.)
|-
| IND_FLAG_ALLOW_CLOSING_LAST_INSTANCE
| Allow closing down the last instance of this type (No industry has this bit set by default.)
|}

==Industry tile properties==

{| class="t"
! property
! value range
! comment
|-
| substitute
|
[[NML:Default industry tiles|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
|
[[NML:Default industry tiles|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.
| 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: <code style="color:darkgreen"><nowiki>accepted_cargos: [[COAL, 8], [IORE, 8]];</nowiki></code> Example: for a tile that doesn't any cargos at all you'd use: <code style="color:darkgreen">accepted_cargos: [];</code>
|-
| land_shape_flags
|
bitmask([[#Land shape flags|Land shape flags]])
|
|-
| callback_flags
| bitmask(INDTILE_CBF_XXX, INDTILE_CBF_YYY)
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| animation_info
| Array [ANIMATION_XXX, frame-count]
| XXX = [LOOPING <nowiki>|</nowiki> NON_LOOPING], 1..253 frames
|-
| animation_speed
| 0..16
|
Speed of animation, see [[NML:Animation speed|animation speed table]] for the meaning of the values.
|-
| animation_triggers
| bitmask(ANIM_TRIGGER_INDTILE_XXX, ... )
|
Bitmask of triggers that will trigger the <code style="color:darkgreen">anim_control</code> callback, see the [[#Animation triggers|table]] below.
|-
| special_flags
| bitmask(INDTILE_FLAG_XXX)
| XXX is a special flag description. Currently there's only one flag defined: set INDTILE_FLAG_RANDOM_ANIMATION if the decision in anim_control callback needs random bits via extra_callback_info1
|}

===Land shape flags===

{| class="t"
! 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 0x2F.
|}

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

{| class="t"
! name
! value range
! comment
|-
| nearby_tile_slope
| SLOPE_XXX
|
See [[NML:List of tile slopes|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 <nowiki>|</nowiki> SEA <nowiki>|</nowiki> CANAL <nowiki>|</nowiki> RIVER] Note that tiles for which <code style="color:darkgreen">nearby_tile_is_water</code> 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
|
[[NML:List of tile classes|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 that is part of this GRF, the tile id is 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 GRF.
|}

==Industry variables==

{| class="t"
! name
! value range
! comment
|-
| production_level
| 0, or 4 .. 128
| Current production level of the industry. Usually in range 4 .. 128, default starting level is 16. A level of 0 indicates imminent closure.
|-
| waiting_cargo_1
| 0..65535
| If any of the production callbacks is enabled, this variable will contain the amount of the first cargo type awaiting to be processed.
|-
| waiting_cargo_2
| 0..65535
| If any of the production callbacks is enabled, this variable will contain the amount of the second cargo type awaiting to be processed.
|-
| waiting_cargo_3
| 0..65535
| If any of the production callbacks is enabled, this variable will contain the amount of the third cargo type awaiting to be processed.
|-
| produced_cargo_waiting_1
| 0..65535
| The amount of produced 'output cargo type 1' that this waiting to be transported.
|-
| produced_cargo_waiting_2
| 0..65535
| The amount of produced 'output cargo type 2' that this waiting to be transported.
|-
| produced_this_month_1
| 0..65535
| The amount of 'output cargo type 1' that was produced this month.
|-
| produced_this_month_2
| 0..65535
| The amount of 'output cargo type 2' that was produced this month.
|-
| produced_last_month_1
| 0..65535
| The amount of 'output cargo type 1' that was produced last month.
|-
| produced_last_month_2
| 0..65535
| The amount of 'output cargo type 2' that was produced last month.
|-
| transported_this_month_1
| 0..65535
| The amount of 'output cargo type 1' that was transported this month.
|-
| transported_this_month_2
| 0..65535
| The amount of 'output cargo type 2' that was transported this month.
|-
| transported_last_month_1
| 0..65535
| The amount of 'output cargo type 1' that was produced last month.
|-
| transported_last_month_2
| 0..65535
| The amount of 'output cargo type 2' that was produced last month.
|-
| transported_last_month_pct_1
| 0..100
| Percentage of produced 'output cargo type 1' that was transported last month.
|-
| transported_last_month_pct_2
| 0..100
| Percentage of produced 'output cargo type 2' that was transported last month.
|-
| water_distance
| Distance to the tile
| If the industry is built on water, this variable gives the distance of the closest dry land tile, otherwise it gives the distance of the closest water tile.
|-
| layout_num
| 1..255
| Number of the layout being used by the industry.
|-
| founder
| 0..16
| Company number of the industry founder. It will be FOUNDER_GAME (=16) if the industry was generated randomly. TTDPatch only supports up to 8 companies (0..7).
|-
| founder_type
| PLAYERTYPE_XX
| PLAYERTYPE_HUMAN, PLAYERTYPE_AI, PLAYERTYPE_HUMAN_IN_AI (human managing AI company) or PLAYERTYPE_AI_IN_HUMAN (AI managing human company). OpenTTD only uses PLAYERTYPE_HUMAN and PLAYERTYPE_AI. If you cheat yourself to be part of an AI company OpenTTD will still report PLAYERTYPE_AI for the company with yourself and the AI and it'll report PLAYERTYPE_HUMAN for the now uncontrolled company.
|-
| founder_colour1
| COLOUR_XXX
|
Index of founding company's first colour. 0 if not founded by a company. Refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for possible values.
|-
| founder_colour2
| COLOUR_XXX
|
Index of founding company's second colour. It's the same as company_colour1, if no second company colour is chosen. 0 if not founded by a company. Refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for possible values.
|-
| colour
| COLOUR_XXX
|
Random colour for this industry. Refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for possible values.
|-
| build_date
| 0..1826212865
| Date of the industry foundation in days since year 0.
|-
| build_type
| BUILDTYPE_XX
| BUILDTYPE_UNKNOWN (if created in an old version or with newindustries disabled), BUILDTYPE_GAMEPLAY (if founded or created by the in-game random industry generator), BUILDTYPE_GENERATION (if created during random map generation) or BUILDTYPE_EDITOR (if created with the scenario editor).
|-
| counter
| 0..65535
| Decremented every tick, used to time primary industry production in TTD.
|-
| last_accept_date
| date(year, month, day)
| Date when cargo was accepted for the last time. Not valid before 1920 and after 2090.
|-
| random_bits
| 0 ... 65535
| Random data that can be used to randomize certain descisions. (see [[NML:Random_switch|Random switch]]) (NML r1666)
|}

 Variables that require some parameters.

{| class="t"
! name
! arguments
! comment
|-
| industry_count
| industry_type, grfid = -1
|
The value of this variable is the number of industries of a given type that are currently on the map. industry_type is either the ID of an industry. GRFid is the grf in which the industry was defined. The default value is -1, which means current newgrf. A grfid of 0 lets you check the number of default industries of a given type. Use the [[NML:Builtin functions|builtin function]] <code style="color:darkgreen">str2number()</code> to convert a grfid to its numeric representation. ''Warning: using this variable trashes the contents of temporary storage register 0x100''
|-
| industry_distance
| industry_type, grfid = -1
| The value of this variable is the manhattan distance the closest instance of the given industry or 0xFFFF if not applicable. See industry_count for a description of the parameters. ''Warning: using this variable trashes the contents of temporary storage register 0x100.''
|-
| industry_layout_count / industry_layout_distance
| industry_type, layout, grfid = -1.
| See industry_count / industry_distance for description of industry_type, grfid and return value. The results are filtered to industries that have the given layout number. ''Warning: using this variable trashes the contents of temporary storage registers 0x100 and 0x101.''
|-
| industry_town_count
| industry_type, grfid = -1.
| See industry_count / industry_distance for description of industry_type, grfid and return value. The results are filtered to industries that have the same town than the current industry. ''Warning: using this variable trashes the contents of temporary storage registers 0x100 and 0x101.''
|-
| town_manhattan_dist
| x, y
| Parameters indicate a signed offset relative to the northern tile. Returns the Manhattan distance (dx + dy) from the selected tile to the closest town
|-
| town_euclidean_dist
| x, y
| Parameters indicate a signed offset relative to the northern tile. Returns the squared Eucleidean distance (dx^2 + dy^2) from the selected tile to the closest town.
|-
| town_zone
| x, y
|
Parameters indicate a signed offset relative to the northern tile. Returns the [[NML:List of town zones|town zone]] that the selected tile is in.
|-
| nearby_tile_random_bits
| x, y
| Parameters indicate an unsigned offset relative to the northern tile. Returns the random bits of the selected industry tile, or 0 if it is not an industry tile that's part of this industry.
|}

==Industry tile variables==

{| class="t"
! 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
|
[[NML:List of town zones|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 [[NML:Builtin functions|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|common variables]] described above. Additionally, they have access to the following:

{| class="t"
! 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 callbacks==

{| class="t"
! callback
! return value
! comment
|-
| default
| varies
| Any unhandled callbacks. Generally this doesn't need to be used, except for old-style callbacks.
|-
| produce_cargo_arrival
| Produce-block
| Called to produce cargo when it arrives.
|-
| produce_256_ticks
| Produce-block
| Called to produce cargo every 256 ticks.
|-
| availability
| CB_RESULT_IND_ALLOW or CB_RESULT_IND_DISALLOW
|
{{nml|0.2}} Only available in NML 0.2 or earlier. Called when the game needs to know if the industry type is available. It is limited to the type as a whole, so you can't access industry-specific variables. <code style="color:darkgreen">extra_callback_info2</code> contains the [[#Industry creation types|creation type]].
|-
| construction_probability
| CB_RESULT_IND_NO_CONSTRUCTION, CB_RESULT_IND_PROBABILITY_FROM_PROPERTY or a relative probability 0..255
|
{{nml|0.3}}. Called when the game needs to know if the industry type is available. It is limited to the type as a whole, so you can't access industry-specific variables. <code style="color:darkgreen">extra_callback_info2</code> contains the [[#Industry creation types|creation type]]. If you return CB_RESULT_IND_NO_CONSTRUCTION or 0 the industry won't be build. If you return CB_RESULT_IND_PROBABILITY_FROM_PROPERTY it'll be build according to the relative probability as defined in the <code style="color:darkgreen">prob_random</code> or <code style="color:darkgreen">prob_in_game</code> properties, otherwise it'll use the value as returned as relative probability.
|-
| location_check
|
See the [[#Location check results|table]] below.
|
Called to check if a location is suitable. <code style="color:darkgreen">extra_callback_info2</code> contains the [[#Industry creation types|creation type]]. Since the industry isn't built yet, industry variables aren't available. If this callback is not implemented or fails, constructing the industry will be allowed. Construction might also be prevented via the <code style="color:darkgreen">tile_check</code> industry tile callback, though.
|-
| monthly_prod_change
|
See [[#Production change callback results|below]]
| Called each month to (possibly) change the industry production. <code style="color:darkgreen">extra_callback_info2</code> contains random bits.
|-
| random_prod_change
|
See [[#Production change callback results|below]]
| Works exactly the same as <code style="color:darkgreen">monthly_prod_change</code>, except that it's only called when TTD selects this industry for a random production change.
|-
| build_prod_change
| Value in range 4-128
| Called when an industry is constructed. Return value is production level (default 16). Can also be used to initialise permanent storage when an industry is constructed. Requires OpenTTD > r24186 and nml > 1886.
|-
| cargo_subtype_display
| String or CB_RESULT_NO_TEXT
| This callback allows displaying some text after a cargo name. Returning CB_RESULT_NO_TEXT displays nothing. The lowest byte of <code style="color:darkgreen">extra_callback_info2</code> contains 0 .. 2 to get texts for the first .. third accepted cargo type, and 3 .. 4 for the first ... second produced cargo type. The second byte contains 0 when getting a string for the buy menu (no industry variables available!), 1 when for the industry window and 2 for the industry directory window.
|-
| extra_text_industry
| String
| Show extra text in the industry window.
|-
| extra_text_fund
| String
| Show extra text in the fund window. Since the industry isn't built, no industry variables are available.
|-
| control_special
| 0 or 1
| Called to control various effects from the <code style="color:darkgreen">spec_flags</code> property. Currently only works for the first two (plant fields / cut trees). Return 1 to execute the action or 0 to not do so. The relevant flag is given in <code style="color:darkgreen">extra_callback_info2</code>. The default (if the flag is enabled, of course) is to plant fields with 1/8th chance every 256 ticks, and to cut trees every 512 ticks. Random bits are supplied in <code style="color:darkgreen">extra_callback_info1</code>.
|-
| stop_accept_cargo
| 0 or 1
| With this callback, you can temporarily refuse accepting a certain cargo, for example because the stockpile is full. Return 1 to accept or 0 to refuse. Make sure to synchronize this callback with the <code style="color:darkgreen">cargo_amount_accept</code> callback for industry tiles. <code style="color:darkgreen">extra_callback_info2</code> contains the cargo type to accept or not.
|-
| colour
| COLOUR_XXX
| Called after constructing the industry. The <code style="color:darkgreen">colour</code> variable is set to a random value at this point, you can use this callback to change this.
|-
| cargo_input
| Cargo type, or 0xFF
| Decide the input cargo types. Called repeatedly until 0xFF is returned, although currently not more than three times. Do not rely on this limitation, though. <code style="color:darkgreen">extra_callback_info1</code> starts at 0 and is incremented for every iteration. Return a cargo type (from the table) or 0xFF to stop.
|-
| cargo_output
| Cargo type, or 0xFF
| Same as <code style="color:darkgreen">cargo_input</code> above, except that it is applied to the output cargo types and currently not called more than twice.
|}

===Location check results===

The following values can be used as return values for the <code style="color:darkgreen">location_check</code> callback for industries
and the <code style="color:darkgreen">tile_check</code> callback for industry tiles and objects.

{| class="t"
! 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.
|}

===Production change callback results===

{| class="t"
! value
! meaning
|-
| CB_RESULT_IND_PROD_NO_CHANGE
| Do not change industry production
|-
| CB_RESULT_IND_PROD_HALF
| Half industry production. If production goes below a quarter of default, the industry closes.
|-
| CB_RESULT_IND_PROD_DOUBLE
| Double production if it's not 8x default yet.
|-
| CB_RESULT_IND_PROD_CLOSE
| Announce closure and remove the industry next month.
|-
| CB_RESULT_IND_PROD_RANDOM
| Do a random production change, as if the industry is a primary one.
|-
| CB_RESULT_IND_PROD_DIVIDE_BY_4
| Divide production by 4
|-
| CB_RESULT_IND_PROD_DIVIDE_BY_8
| Divide production by 8
|-
| CB_RESULT_IND_PROD_DIVIDE_BY_16
| Divide production by 16
|-
| CB_RESULT_IND_PROD_DIVIDE_BY_32
| Divide production by 32
|-
| CB_RESULT_IND_PROD_MULTIPLY_BY_4
| Multiply production by 4
|-
| CB_RESULT_IND_PROD_MULTIPLY_BY_8
| Multiply production by 8
|-
| CB_RESULT_IND_PROD_MULTIPLY_BY_16
| Multiply production by 16
|-
| CB_RESULT_IND_PROD_MULTIPLY_BY_32
| Multiply production by 32
|-
| CB_RESULT_IND_PROD_DECREMENT_BY_1
| Decrement production by 1
|-
| CB_RESULT_IND_PROD_INCREMENT_BY_1
| Increment production by 1
|-
| CB_RESULT_IND_PROD_SET_BY_0x100
| Set the production level to the value in bits 16 .. 23 of register 0x100.
|}

Setting bit 7 of the result disables the associated news message. Setting bit 8 replaces the news message with a custom message, read from register 0x100 bits 0 .. 15.

===Industry creation types===

{| class="t"
! value
! meaning
|-
| IND_CREATION_GENERATION
| Industry is created during map generation, or when building 'many random industries' in the scenario editor.
|-
| IND_CREATION_RANDOM
| Industry is randomly generated during gameplay
|-
| IND_CREATION_FUND
| Industry is funded by the player (in game or scenario editor)
|-
| IND_CREATION_PROSPECT
| Industry is prospected by the player
|}

==Industry tile callbacks==

{| class="t"
! callback
! return value
! comment
|-
| default
| Sprite layout
| Graphics for the industry tile
|-
| random_trigger
| N/A
|
See [[NML:Random switch|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. <code style="color:darkgreen">extra_callback_info1</code> contains random bits, if enabled in the <code style="color:darkgreen">special_flags</code> property. Returning a sound effect in the high byte will cause that sound effect to be played.
|-
| 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 <nowiki>|</nowiki> STOP_ANIMATION <nowiki>|</nowiki> DO_NOTHING] to respectively start the animation in its current frame, stop the animation or do nothing. <code style="color:darkgreen">extra_callback_info1</code> contains random bits, if enabled in the <code style="color:darkgreen">special_flags</code> property. Returning a sound effect in the high byte will cause that sound effect to be played. <code style="color:darkgreen">extra_callback_info2</code> contains the reason to trigger the animation, see the [[#Animation triggers|table]] below. Note that you need to enable the wanted triggers in the <code style="color:darkgreen">animation_triggers</code> property.
|-
| 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 <code style="color:darkgreen">accepted_cargos</code> 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 <code style="color:darkgreen">accepted_cargos</code> are used instead. Cargo types are from the <code style="color:darkgreen">cargo_type_accept</code> callback, or the <code style="color:darkgreen">accepted_cargos</code> 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 results|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. <code style="color:darkgreen">extra_callback_info2</code> contains the industry layout number in the lowest (first) byte and the [[#Industry creation types|creation type]] in the second byte. If this callback is not implemented or fails, the <code style="color:darkgreen">land_shape_flags</code> 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.
|}

===Animation triggers===

{| class="t"
! 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)
|}

NML:Canals

2012-08-02T19:08:30Z

Hirundo: Move ID section to the top, add some usage notes

{{NMLNavPropVarCB}}

== Canal ids ==
The used item ID defines what sprites this item provides. Item IDs should be picked from the following table (WF_XXX).

The 'normal sprites' column contains the amount of sprites that should be provided for this feature. If the appropriate bit in the graphics_flags-property (see below) the amount of sprites stated in the 'alternative sprites' column must be provided instead.
{| class="t"
!name
!use
!normal sprites
!alternative sprites
|-
|WF_WATERCLIFFS
|{{ottdp|1.1|2.6|ottdrev=r20352|ttdprev=r1573}} water for canals / locks
|4 slope sprites
|1 flat ground sprite followed by 4 slope sprites
|-
|WF_LOCKS
|{{ottdp|0.6|2.5}} Locks
|24
|undefined
|-
|WF_DIKES
|{{ottdp|0.6|2.5}} Dikes
|12
|undefined
|-
|WF_CANAL_GUI
|{{ottdp|no|2.5}} Canal GUI
|1
|undefined
|-
|WF_FLAT_DOCKS
|{{ottdp|no|2.5}} Flat docks
|4
|undefined
|-
|WF_RIVER_SLOPE
|{{ottdp|1.1|2.6|ottdrev=r20352|ttdprev=r1573}} River water
|4
|1 flat ground sprite followed by 4 slope sprites
|-
|WF_RIVERBANKS
|{{ottdp|0.6|2.6}} Riverbanks
|12*5 (Last 4 for slopes)
|undefined
|-
|WF_RIVER_GUI
|{{ottdp|no|2.6}} River GUI
|2
|undefined
|-
|WF_BUOY
|{{ottdp|1.2|no|ottdrev=r22973}} Buoy
|1
|undefined
|}

==Canal properties==

item (FEAT_CANAL, item_name, id) { ... }

{| class="t"
! name
! value range
! comment
|-
| graphic_flags
| bitmask(flags)
| There is currently only one possible bit: <code style="color:darkgreen">WATERFEATURE_ALTERNATIVE_SPRITES</code>
|}

== Canal variables ==

{| class="t"
! name
! value range
! comment
|-
|tile_height
|0 .. max_tile_height
| {{nml|0.2}} Tile height in pixels (=tiles * 8).
{{nml|0.3}} Tile height in tiles.
|-
|terrain_type
| TILETYPE_XXX
|
;TILETYPE_NORMAL
:Normal grass in all climates
;TILETYPE_DESERT
;TILETYPE_RAIN_FOREST
:In tropical climate only: some tiles in the mountains, distant from desert and sea
;TILETYPE_SNOW
|-
|random_bits
|0 .. 255
|random bits of that tile
|}

== Canal callbacks ==

{| class="t"
! callback
! return value
! comment
|-
|default
|spriteset
|graphics for the canal id
|-
|sprite_offset
|
|numeric offset into the spriteset for the canal id
|}

NML:Vehicles

2012-08-02T18:58:18Z

Hirundo: Add note about item IDs

{{NMLNavPropVarCB}}
== Item IDs ==
Picking an item ID requires keeping two cases in mind: OpenTTD with the engine pool enabled and OpenTTD with engine pool disabled / TTDPatch. The status of the engine pool may be checked with the global variable [[NML:General#General_variables|dynamic_engines]].

=== Engine pool enabled ===
With the engine pool enabled, each NewGRF has its own ID range, NewGRFs don't influence each other. IDs may freely be chosen between 0 and 65535. If the chosen ID belongs to an existing vehicle, this vehicle is overridden by your vehicle. If another NewGRF is already overriding that vehicle, a new vehicle will be allocated, but all the properties will be copied from the old vehicle. If you define an ID for which no original vehicle exists, a new (blank) vehicle is allocated.

This behaviour can be modified using an [[NML:Overriding_vehicles_in_other_NewGRFs|engine_override]], this allows changing the properties of vehicles defined in other NewGRFs instead of allocating a new vehicle.

=== TTDPatch / Engine pool disabled ===
Each new vehicle has to replace an existing vehicle. If multiple NewGRFs try to replace the same vehicle, the last NewGRF loaded 'wins'. [[VehicleIDs|This page]] contains a list of valid vehicle IDs for each vehicle type, look in the 'NML ID' column. Note that IDs are not bound to a specific sort of vehicle (e.g. monorail wagons) but to a feature (e.g. trains, road vehicles).

In general, you should take the following steps:
* If your NewGRF is intended as a complete replacement for the default vehicles, disable the relevant default vehicles using [[NML:Disable_items|disable_item]].
* Re-use IDs of existing vehicles as much as possible.
* If your NewGRF uses IDs outside of the normal range (for example, because you there are more vehicles than slots available), let your code check if dynamic_engies is enabled. If not, skip the vehicles outside the normal range (using an if-statement) and make sure that the remaining vehicles allow for reasonable gameplay. It is recommended to issue a warning to the user about this. Alternatively, it is also possible to disable your entire NewGRF. If you don't do this check and dynamic_engines is off, OpenTTD may disable your NewGRF with the somewhat cryptic message 'Attempt to use invalid ID', which will likely lead to bug reports about your NewGRF and/or your OpenTTD.

==Properties common to all vehicle types==

{| class="t"
! property
! value range
! available for articulated vehicle
! comment
|-
| <code style="color:green">name</code>
| (string)
| yes
| for example <code style="color:darkgreen">string(STR_NAME_HEREFORD_TRAM)</code>
|-
| <code style="color:green">climates_available</code>
| bitmask(CLIMATE_XXX, CLIMATE_YYY, ...)
| set to <code style="color:green">NO_CLIMATE</code>
|
;CLIMATE_TEMPERATE
;CLIMATE_ARCTIC
;CLIMATE_TROPICAL
;CLIMATE_TOYLAND
;NO_CLIMATE
:Vehicle is availble in no climate (e.g. for articulated parts)
;ALL_CLIMATES
:Vehicle is available irrespective of climate

To make a vehicle available in all climates except toyland you could use: <code style="color:green">ALL_CLIMATES & ~bitmask(CLIMATE_TOYLAND)</code>.
|-
| <code style="color:green">introduction_date</code>
| <code style="color:green">date</code>(yyyy,mm,dd)
| no
| Valid range for yyyy is 0 ... 5000000. In TTDPatch, dates after 2044 will be limited to 2044. Unless the engine is introduced within two years after game-start (always 1920 in TTDPatch), a random number of days between 0 and 511 will be added to this.
|-
| <code style="color:green">model_life</code>
| 0 ... 254 (years) or <code style="color:green">VEHICLE_NEVER_EXPIRES</code>
| no
|
Number of years a model is "supported" by the manufacturer, see [[#Engine life cycle|below]].
|-
| <code style="color:green">retire_early</code>
| -128 ... 127 (years)
| no
|
Retire the vehicle (make it unavailable in the purchase menu) this many years before reliability starts dropping, see [[#Engine life cycle|below]]. May be negative.
|-
| <code style="color:green">vehicle_life</code>
| 0 ... 255 (years)
| no
| Life length of an individual vehicle, before it is considered too old and in need of replacement.
|-
| <code style="color:green">reliability_decay</code>
| 0 ... 255
| no
| Default vehicles use 20. The higher the value the faster reliability decays, the more frequent service is needed. 0 means reliability never decreases if the vehicle is not too old
|-
| <code style="color:green">refittable_cargo_classes</code>
|
bit set of [[NML:Cargos#Cargo classes|cargo classes]]
| yes
| for example: <code style="color:darkgreen">bitmask(CC_BULK, CC_COVERED)</code>
|-
| <code style="color:green">non_refittable_cargo_classes</code>
|
bit set of [[NML:Cargos#Cargo classes|cargo classes]]
| yes
| for example: <code style="color:darkgreen">bitmask(CC_OVERSIZED, CC_SPECIAL)</code>
|-
| <code style="color:green">refittable_cargo_types</code>
| bit mask of entries into the cargo translation table
| yes
| As of NML 0.3, do not use this. Use cargo_[dis]allow_refit (see below) instead.
|-
| <code style="color:green">cargo_allow_refit</code>
| Array of cargo labels from the [[NML:Cargotable|cargotable]]
| Yes
| {{ottdp|1.2|no|ottdrev=r23291}} A list of cargo types to allow refitting to, irrespective of cargo classes. Example: <code style="color:darkgreen">[COAL, IORE]</code>
|-
| <code style="color:green">cargo_disallow_refit</code>
| Array of cargo labels from the [[NML:Cargotable|cargotable]]
| Yes
| {{ottdp|1.2|no|ottdrev=r23291}} A list of cargo types to disallow refitting to, irrespective of cargo classes. Example: <code style="color:darkgreen">[MAIL]</code>
|-
| <code style="color:green">loading_speed</code>
| 0 ... 255 (cargo units)
| yes
| Units of cargo loaded per time unit. Default vehicles use 5 for trains and road vehicles, 10 for ships and 20 for aircraft. This amount of cargo is loaded to or unloaded from the vehicle every 40 ticks for trains, every 20 ticks for road vehicles and aircraft and every 10 ticks for ships.
|-
| <code style="color:green">cost_factor</code>
| 0 ... 255
| Set to 0
| multiplier to the base purchase cost
|-
| <code style="color:green">running_cost_factor</code>
| 0 ... 255
| Set to 0
| multiplier to the base running costs
|-
| <code style="color:green">cargo_age_period</code>
| 0 ... 65535
| yes
|
{{ottd|1.2|r22713}} This property specifies after how many ticks cargo is aged. Default value is 185. 74 ticks is equal to 1 day.
|}

===Refittability===

To determine whether your vehicle can be refitted to a certain cargo, OpenTTD uses the following table

{| class="t"
! Cargo matches refittable_cargo_classes
! Cargo matches non_refittable_cargo_classes
! Cargo in cargo_allow_refit
! Cargo in cargo_disallow_refit
! Result
|-
| Yes
| No
| Doesn't matter
| No
| Refittable
|-
| No
| Doesn't matter
| No
| Doesn't matter
| Not refittable
|-
| Doesn't matter
| Doesn't matter
| Yes
| No
| Refittable
|-
| Doesn't matter
| Doesn't matter
| Doesn't matter
| Yes
| Not refittable
|}

For those that prefer boolean logic, the formula is as follows:

refittable = ((cargo classes in refittable_cargo_classes AND NOT cargo classes in non_refittable_cargo_classes) OR cargo in cargo_allow_refit) AND NOT (cargo in cargo_disallow_refit)

In general, you should use refittable_cargo_classes and non_refittable_cargo_classes to decide to which cargos your vehicle is refittable, and only then use cargo_allow_refit and cargo_disallow_refit to allow/disallow specific cargos.

===Engine life cycle===

The life cycle of a vehicle model consists of three phases, as outlined in the following table.

{| class="t"
! phase
! duration
! reliability
|-
| 1
| 7 to 38 months
| increases from 48-73% to 75-100%
|-
| 2
| <code style="color:darkgreen">model_life</code> - 8 years
| stays constant at peak, 75-100%
|-
| 3
| 10 to 20.5 years
| decreases from peak to 25-50%
|}

If <code style="color:darkgreen">model_life</code> is set to <code style="color:darkgreen">VEHICLE_NEVER_EXPIRES</code>, the engine remains in phase 2 forever.

Normally, the vehicle is removed from the purchase menu at the and of phase 3. However if you set the <code style="color:darkgreen">retire_early</code> property, it will be retired this many years before (or after, if the value is negative) the end of phase 2.

==Sorting vehicles in the purchase list==
This is a special property that is not encoded in an item/property-block like most other properties but it has it's own block instead. The syntax is as follows:

sort(<feature>, [<ID>, <ID>, <ID>...]);

The engines will be sorted in the given order on the position where originally the first element was. Say the original engine sorting is this: A B C D E and you use this code <code style="color:darkgreen">sort(FEAT_TRAINS, [D, B, A]);</code> the final sorting will be this: C D B A E

==Train properties==

{| class="t"
! property
! value range
! available for articulated vehicle
! comment
|-
| <code style="color:green">sprite_id</code>
| <code style="color:green">SPRITE_ID_NEW_TRAIN</code>
| yes
| Set this property to enable new graphics
|-
| <code style="color:green">speed</code>
| 0 ... 65000 (float, speed units)
| no
| Max speed for engines, speed limit for wagons
|-
| <code style="color:green">misc_flags</code>
| bitmask(TRAIN_FLAG_XXX, ...)
| FLIP should not be set, TILT and MU TO the same value as the 1st part
|
;TRAIN_FLAG_TILT
: enable the tilt bonus (20% speed in curves, if all vehicles in consist have it set)
;TRAIN_FLAG_2CC
:Enable use of the 2nd company colour
;TRAIN_FLAG_MU
:act as multiple unit (used for livery selection only)
;TRAIN_FLAG_FLIP
:Allow vehicle to be flipped (reversed) in depot
;TRAIN_FLAG_AUTOREFIT
:Allow autoreffitting. To enable autorefit, furthermore the [[#Vehicle callbacks|refit_cost]]-callback has to allow it, or else (if this callback is not implemented or fails) the <code style="color:green">refit_cost</code>-property (see below) must be set to 0.
;TRAIN_FLAG_NO_BREAKDOWN_SMOKE
:{{nml|0.3}} {{ottdp|1.3|no|ottdrev=r24124}} Disable breakdown smoke effect
|-
| <code style="color:green">refit_cost</code>
| 0 ... 255
| yes
| in 50% units of the purchase price cost base
|-
| <code style="color:green">callback_flags</code>
| bitmask(VEH_CBF_XXX, ...)
| yes
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| <code style="color:green">track_type</code>
| item from railtypetable
| must be the same as front
| Default railtype table: RAIL, MONO, MGLV. If you install a railtypetable yourself you'll always get the railtype you specified. If you want a vehicle to run on electric rail and you don't have a railtypetable, set <code style="color:green">track_type</code> to RAIL and make sure that you set <code style="color:green">engine_class</code> to <code style="color:green">ENGINE_CLASS_ELECTRIC</code>.
|-
| <code style="color:green">ai_special_flag</code>
| [<code style="color:green">AI_FLAG_PASSENGER</code> <nowiki>|</nowiki> <code style="color:green">AI_FLAG_CARGO</code>]
| no
|
;<code style="color:green">AI_FLAG_PASSENGER</code>
:Tell computer players that it's an engine that should only be used for passenger service.
|-
| <code style="color:green">power</code>
| 0 ... 65000 hp (float, power units)
| Set to 0
|
|-
| <code style="color:green">running_cost_base</code>
| RUNNING_COST_XXX
| Set to RUNNING_COST_NONE
|
;RUNNING_COST_STEAM
;RUNNING_COST_DIESEL
;RUNNING_COST_ELECTRIC
;RUNNING_COST_ROADVEH
;RUNNING_COST_NONE
:no running costs
|-
| <code style="color:green">dual_headed</code>
| [0 <nowiki>|</nowiki> 1]
| Set to 0 for all parts of an articulated vehicle
| 1 = dual_headed, otherwise normal engine
|-
| <code style="color:green">default_cargo_type</code>
| An identifier from the [[NML:Cargotable|cargo table]], or DEFAULT_CARGO_FIRST_REFITTABLE
| Yes
| If the vehicle is refittable to at least one cargo, but the chosen default cargo is not available or is set to DEFAULT_CARGO_FIRST_REFITTABLE, then the first refittable cargo is used. The first refittable is chosen according to the order in your [[NML:Cargotable|cargo table]]. If this property is set to a valid cargo but the vehicle cannot refit to any cargo type, then the vehicle will be able to carry only this cargo, but it cannot be refitted (like e.g. the default train wagons).
|-
| <code style="color:green">cargo_capacity</code>
| 0 .. 255
| yes
| By default, passenger capacity is 4x, and mail/goods capacity 2x larger than capacity for other cargoes. The capacity set here is used for the default (i.e. first refittable) cargo. Use the <code style="color:green">cargo_capacity</code> callback to avoid this effect.
|-
| <code style="color:green">weight</code>
| 0 .. 1279 ton (float, mass units)
| Set to 0
|
|-
| <code style="color:green">ai_engine_rank</code>
| 0 ... 255
| no
| TTDPatch only: Higher values make the engine for the TTDPatch AI more attractive
|-
| <code style="color:green">engine_class</code>
| ENGINE_CLASS_XXX
| no
|
Defines which livery colour settings apply to the vehicle
;ENGINE_CLASS_STEAM
;ENGINE_CLASS_DIESEL
;ENGINE_CLASS_ELECTRIC
;ENGINE_CLASS_MONORAIL
;ENGINE_CLASS_MAGLEV
|-
| <code style="color:green">extra_power_per_wagon</code>
| 0 ... 65000 hp (float, power units)
| Set to 0
| Only wagons with a livery override for this engine will add power
|-
| <code style="color:green">tractive_effort_coefficient</code>
| 0 ... 1 (float)
| Set to 0
| Fraction of the vehicle weight that is available as tractive effort. Tractive effort (in kN) is calculated as (TE coefficient) * 10 * weight (in tons), with 10 being an approximation of the acceleration of gravity (9.81 m/s). Default value is 0.3.
|-
| <code style="color:green">air_drag_coefficient</code>
| 0 ... 1 (float)
| Set to 0
| Coefficient of the relative air drag, in arbitrary units. The default value is approximately (8 / max_speed), with max_speed in km/h, clamped to the range 0.004 .. 0.75.
|-
| <code style="color:green">length</code>
| 1 ... 8
| yes
| Length of the vehicle in arbitrary units. Use a value of 8 (equal to the predefined constant VEHICLE_LENGTH) for a full-length vehicle.
|-
| <code style="color:green">visual_effect_and_powered</code>
| <code style="color:green">visual_effect_and_powered</code> (VISUAL_EFFECT_XXX, offset, <code style="color:green">ENABLE_WAGON_POWER</code> or <code style="color:green">DISABLE_WAGON_POWER</code>)
| yes
|
Set the type of visual effect for the vehicle and its positional offset with respect to the vehicle. An offset of 0 is default, negative values mean more to the front and positive values are backwards. Minimum offset is -8, maximum is 7.

;VISUAL_EFFECT_DEFAULT
:No effect, unless for the default vehicles
;VISUAL_EFFECT_STEAM
:Steam like from steam engine
;VISUAL_EFFECT_DIESEL
:Steam from internal combustion engine
;VISUAL_EFFECT_ELECTRIC
:Electric sparks
;VISUAL_EFFECT_DISABLE
:No effect
|-
| <code style="color:green">extra_weight_per_wagon</code>
| 0 ... 255 ton (float, mass units)
| Set to 0
| Adds extra weight for powered wagons, see <code style="color:green">extra_power_per_wagon</code>
|-
| <code style="color:green">bitmask_vehicle_info</code>
| 8-bit bitmask
| yes
|
Used for obtaining [[#bitmask consist info|<code style="color:green">bitmask_consist_info</code>]]
|}

==Road vehicle properties==

{| class="t"
! property
! value range
! available for articulated vehicle
! comment
|-
| sprite_id
| SPRITE_ID_NEW_ROADVEH
| yes
| Set this property to enable new graphics
|-
| speed
| 0 ... 514km/h (float, speed units)
| no
|
|-
| misc_flags
| bitmask(ROADVEH_FLAG_XXX, ...)
| partly; tram flag must the same
|
;ROADVEH_FLAG_TRAM
:The vehicle requires tram tracks to run on
;ROADVEH_FLAG_2CC
:Enable 2nd company colour
;ROADVEH_FLAG_AUTOREFIT
:Allow autorefitting. To enable autorefit, furthermore the [[#Vehicle callbacks|refit_cost]]-callback has to allow it, or else (if this callback is not implemented or fails) the <code style="color:green">refit_cost</code>-property (see below) must be set to 0.
;ROADVEH_FLAG_NO_BREAKDOWN_SMOKE
:{{nml|0.3}} {{ottdp|1.3|no|ottdrev=r24124}} Disable breakdown smoke effect
|-
| refit_cost
| 0 ... 255
| yes
| in 25% units of the purchase price cost base
|-
| callback_flags
| bitmask(VEH_CBF_XXX, ...)
| yes
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| running_cost_base
| RUNNING_COST_XXX
| set to RUNNING_COST_NONE
|
;RUNNING_COST_STEAM
;RUNNING_COST_DIESEL
;RUNNING_COST_ELECTRIC
;RUNNING_COST_ROADVEH
;RUNNING_COST_NONE
:no running costs
|-
| power
| 0 ... 2550hp (float, power units)
| Set to 0
|
|-
| weight
| 0 ... 63.75ton (float, mass units)
| Set to 0
|
|-
| tractive_effort_coefficient
| 0 ... 1 (float)
| Set to 0
| Fraction of the vehicle weight that is available as tractive effort. Tractive effort (in kN) is calculated as (TE coefficient) * 10 * weight (in tons), with 10 being an approximation of the acceleration of gravity (9.81 m/s). Default value is 0.3.
|-
| air_drag_coefficient
| 0 ... 1 (float)
| Set to 0
| Coefficient of the relative air drag, in arbitrary units. The default value is approximately (8 / max_speed), with max_speed in km/h, clamped to the range 0.004 .. 0.75.
|-
| <code style="color:green">default_cargo_type</code>
| An identifier from the [[NML:Cargotable|cargo table]], or DEFAULT_CARGO_FIRST_REFITTABLE
| Yes
| If the vehicle is refittable to at least one cargo, but the chosen default cargo is not available or is set to DEFAULT_CARGO_FIRST_REFITTABLE, then the first refittable cargo is used. The first refittable is chosen according to the order in your [[NML:Cargotable|cargo table]]. If this property is set to a valid cargo but the vehicle cannot refit to any cargo type, then the vehicle will be able to carry only this cargo, but it cannot be refitted (like e.g. the default train wagons).
|-
| cargo_capacity
| 0 ... 255
| yes
| By default, passenger capacity is 4x, and mail/goods capacity 2x larger than capacity for other cargoes. The capacity set here is used for the default (i.e. first refittable) cargo. Use the <code style="color:green">cargo_capacity</code> callback to avoid this effect.
|-
| sound_effect
| SOUND_XXX
| no
|
See available [[NML:List of sound effects|sound effects]].
|-
| visual_effect
| visual_effect( VISUAL_EFFECT_XXX, offset)
| yes
|
Set the type of visual effect for the vehicle and its positional offset with respect to the vehicle. An offset of 0 is default, negative values mean more to the front and positive values are backwards. Minimum offset is -8, maximum is 7.

;VISUAL_EFFECT_DEFAULT
:No effect, unless for the default vehicles
;VISUAL_EFFECT_STEAM
:Steam like from steam engine
;VISUAL_EFFECT_DIESEL
:Steam from internal combustion engine
;VISUAL_EFFECT_ELECTRIC
:Electric sparks
;VISUAL_EFFECT_DISABLE
:No effect
|-
| length
| 1 ... 8
| yes
| Length of the vehicle in arbitrary units. Use a value of 8 (equal to the predefined constant VEHICLE_LENGTH) for a full-length vehicle.
|}

==Ship properties==

{| class="t"
! property
! value range
! comment
|-
| sprite_id
| SPRITE_ID_NEW_SHIP
| Set this property to enable new graphics
|-
| speed
| 0 ... 127 km/h (float, speed units)
|
|-
| misc_flags
| bitmask(SHIP_FLAG_XXX)
| Bitmask with to possible flags, set to 0 to disable all.

;SHIP_FLAG_2CC
:Enable use of the 2nd company colour
;SHIP_FLAG_AUTOREFIT
:llow autorefitting. To enable autorefit, furthermore the [[#Vehicle callbacks|refit_cost]]-callback has to allow it, or else (if this callback is not implemented or fails) the <code style="color:green">refit_cost</code>-property (see below) must be set to 0.
;SHIP_FLAG_NO_BREAKDOWN_SMOKE
:{{nml|0.3}} {{ottdp|1.3|no|ottdrev=r24124}} Disable breakdown smoke effect
|-
| refit_cost
| 0 ... 255
| in 1/32 of the default refit cost base
|-
| callback_flags
| bitmask(VEH_CBF_XXX, ...)
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| is_refittable
| [0 <nowiki>|</nowiki> 1]
| 0=false, 1=true. Note: if you do not set this property to 1, then refittable_cargo_classes / non_refittable_cargo_classes have no effect.
|-
| <code style="color:green">default_cargo_type</code>
| An identifier from the [[NML:Cargotable|cargo table]], or DEFAULT_CARGO_FIRST_REFITTABLE
| If the vehicle is refittable to at least one cargo, but the chosen default cargo is not available or is set to DEFAULT_CARGO_FIRST_REFITTABLE, then the first refittable cargo is used. The first refittable is chosen according to the order in your [[NML:Cargotable|cargo table]]. If this property is set to a valid cargo but the vehicle cannot refit to any cargo type, then the vehicle will be able to carry only this cargo, but it cannot be refitted (like e.g. the default train wagons).
|-
| cargo_capacity
| 0 ... 255
| For ships (unlike other vehicle types) the capacity set here is not affected by the cargo type.
|-
| sound_effect
| SOUND_XXX
|
See available [[NML:List of sound effects|sound effects]].
|-
| ocean_speed_fraction
| 0 ... 1 (float)
|
{{ottd|1.2|r22639}} fraction of base speed on ocean tiles (default: 1)
|-
| canal_speed_fraction
| 0 ... 1 (float)
|
{{ottd|1.2|r22639}} fraction of base speed on canal tiles (default: 1)
|-
| visual_effect
| visual_effect(VISUAL_EFFECT_XXX, offset)
| XXX=[DEFAULT <nowiki>|</nowiki> STEAM <nowiki>|</nowiki> DIESEL <nowiki>|</nowiki> ELECTRIC <nowiki>|</nowiki> DISABLE], it is the type of the visual effect you want for this ship. Default means no effect. Offset is the position of the effect. 0 is default, negative values mean more to the front and positive values are backwards. Minimum offset is -8, maximum is 7.
|}

==Aircraft properties==

{| class="t"
! property
! value range
! comment
|-
| sprite_id
| SPRITE_ID_NEW_AIRCRAFT
| Set this property to enable new graphics
|-
| speed
| 0 .. 3280 km/h (float, speed units)
|
|-
| range
| 0 .. 2894
| {{nml|0.3}} {{ottdp|1.2|no|ottdrev=r23504}} Maximum (euclidean) distance the aircraft can cover between two airports. Set to 0 for unlimited range.
|-
| misc_flags
| bitmask(AIRCRAFT_FLAG_2CC, AIRCRAFT_FLAG_AUTOREFIT)
| Bitmask with to possible flags, set to 0 to disable all.

;AIRCRAFT_FLAG_2CC
:Enable 2nd company colour
;AIRCRAFT_FLAG_AUTOREFIT
:Allow autorefitting. To enable autorefit, furthermore the [[#Vehicle callbacks|refit_cost]]-callback has to allow it, or else (if this callback is not implemented or fails) the <code style="color:green">refit_cost</code>-property (see below) must be set to 0.
;AIRCRAFT_FLAG_NO_BREAKDOWN_SMOKE
:{{nml|0.3}} {{ottdp|1.3|no|ottdrev=r24124}} Disable breakdown smoke effect
|-
| refit_cost
| 0 ... 255
| in 1/32 of default refit cost base
|-
| callback_flags
| bitmask(VEH_CBF_XXX, ...)
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| aircraft_type
| AIRCRAFT_TYPE_XXX
|
;AIRCRAFT_TYPE_HELICOPTER
:Can land on helipad
;AIRCRAFT_TYPE_SMALL
:Can land on all airports with runway
;AIRCRAFT_TYPE_LARGE
:Can land on all airports with runway. But have a high crash chance on small airports
|-
| acceleration
| 0 ... 255
| In arbitrary units
|-
| passenger_capacity
| 0 ... 65536
| Capacity for the passenger compartment. See also the notes at <code style="color:darkgreen">mail_capacity</code> below.
|-
| mail_capacity
| 0 ... 255
| Capacity for the mail compartment, if refitted to a cargo in the CC_PASSENGERS class. When refitted to other cargoes, this capacity is added to the passenger capacity to determine the base capacity. The actual capacity is set to this base capacity divided by 1 for mail, 2 for goods and 4 for all other cargoes. To override this effect, use the <code style="color:darkgreen">passenger_capacity</code> and <code style="color:darkgreen">mail_capacity</code> callbacks.
|-
| sound_effect
| SOUND_XXX
|
See available [[NML:List of sound effects|sound effects]].
|}

==Vehicle variables==

Below an overview of all vehicle-specific variables. Not that in the purchase list, the vehicle is not built yet and as such many variables are not available. All general variables are available, refer to the table for info on vehicle-specific variables. Trying to access a non-available variable invokes undefined behaviour. Please note that while all variables are available for all vehicles types, some of them only make sense for one or more vehicle types. For example checking current_railtype for a non-rail vehicle doesn't make sense at all.

===Variables without parameter===

{| class="t"
! name
! value range
! available in purchase list?
! comment
|-
| position_in_consist
| 0 ... 255
| No
| The position of the current vehicle-part from the start of the vehicle. The engine will get value 0, the first wagon (or second engine) gets value 1, etc.
|-
| position_in_consist_from_end
| 0 ... 255
| No
| Same as position_in_consist but counted from the end. The last wagon will get value 0.
|-
| num_vehs_in_consist
| 1 ... 256
| No
| The total number of vehicles-parts in this vehicle. For aircraft this will include the shadow and the rotor.
|-
| position_in_vehid_chain
| 0 ... 255
| No
| See position_in_consist, but not of the complete vehicle but only all consecutive parts with the same id.
|-
| position_in_vehid_chain_from_end
| 0 ... 255
| No
| See position_in_consist_from_end, but not of the complete vehicle but only all consecutive parts with the same id.
|-
| num_vehs_in_vehid_chain
| 1 ... 256
| No
| See num_vehs_in_consist, but not of the complete vehicle but only all consecutive parts with the same id.
|-
| cargo_classes_in_consist
| Bitmask of CC_XXX
| No
|
[[NML:Cargos#Cargo classes|cargo classes]]
|-
| most_common_refit
|
[[NML:Cargos#Cargo properties|cargo class]]
| No
| cargo class most often refit to
|-
| bitmask_consist_info
| Bitmask 8 bit
| No
|
Binary OR of the values of [[#bitmask vehicle info|bitmask_vehicle_info]] of all vehicles (engines, wagons) in the consist. Only available for rail vehicles.
|-
| company_num
| 0 ... 14
| Yes
| company number of the vehicle owner. TTDPatch only supports up to 8 companies (0 ... 7)
|-
| company_type
| PLAYERTYPE_XX
| Yes
|
;PLAYERTYPE_HUMAN
:human player
;PLAYERTYPE_AI
:AI player
;PLAYERTYPE_HUMAN_IN_AI
:human managing AI company
;PLAYERTYPE_AI_IN_HUMAN
:AI managing human company

OpenTTD only uses PLAYERTYPE_HUMAN and PLAYERTYPE_AI. If you cheat yourself to be part of an AI company OpenTTD will still report PLAYERTYPE_AI for the company with yourself and the AI and it'll report PLAYERTYPE_HUMAN for the now uncontrolled company.
|-
| company_colour1
| COLOUR_XXX
| Yes
|
Refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for possible values.
|-
| company_colour2
| COLOUR_XXX
| Yes
|
Same as company_colour1, if no 2nd company colour is chosen. Refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for possible values.
|-
| aircraft_height
| 0 ... 255
| No
| Height difference between the aircraft and its shadow. 8 Units are equivalent to one height level on the map.
|-
| airport_type
| AIRPORTTYPE_XX
| No
|
;AIRPORTTYPE_SMALL
;AIRPORTTYPE_LARGE
;AIRPORTTYPE_HELIPORT
;AIRPORTTYPE_OILRIG
|-
| curv_info_prev_cur
| -2 ... 2
| No
| Difference in direction between the previous (towards engine) vehicle and this vehicle. Curvature to the right is positive. 1 unit is 45 degrees.
|-
| curv_info_cur_next
| -2 ... 2
| No
| Difference in direction between this vehicle and the next (towards rear end) vehicle. Curvature to the right is positive. 1 unit is 45 degrees.
|-
| curv_info_prev_next
| -4 ... 4
| No
| Difference in direction between the previous (towards engine) and next (towards rear end) vehicle. Curvature to the right is positive. 1 unit is 45 degrees. Equal to <code style="color:darkgreen">curve_invo_prev_cur + curv_info_cur_next</code>.
|-
| curv_info
| vehicle_curv_info(''prev_cur'', ''cur_next'')''''
| No
|
Returns a magic number that represents the curvature state of the prev-cur-next vehicle triplet. Do not try to make sense of this magic number, use the [[NML:Builtin functions|builtin function]] <code style="color:darkgreen">vehicle_curv_info()</code> instead to make comparisons. <code style="color:darkgreen">curv_info == vehicle_curv_info(a, b)</code> is equivalent to <code style="color:darkgreen">(curv_info_prev_cur == a) && (curv_info_cur_next == b)</code>, however the former can easily be used in a switch-block.
|-
| motion_counter
| 0 ... 15
| Yes, always 0
| Is increased every time the vehicle moves a single step on the map. Useful for animations.
|-
| cargo_type_in_veh
| entry in cargo translation table
| Yes, for the default cargo
| 0xFF if not present in the table
|-
| cargo_unit_weight
| weight per unit in 1/16t
| Yes, for the default cargo
|
|-
| cargo_classes
| Bitmask of [[NML:Cargos#Cargo properties|cargo class]]
| Yes, for the default cargo
| class of the currently transported cargo
|-
| vehicle_is_available
| [0 <nowiki>|</nowiki> 1]
| Yes
| Value is 1 if the vehicle is available on the open market
|-
| vehicle_is_testing
| [0 <nowiki>|</nowiki> 1]
| Yes
| Value is 1 if the vehicle is currently being tested
|-
| vehicle_is_offered
| [0 <nowiki>|</nowiki> 1]
| Yes
| Value is 1 if the vehicle is currently being offered for exclusive preview
|-
| build_year
| 0 ... 5000000
| Yes
| 0-based year when the vehicle was built, current year if the vehicle is not built yet
|-
| direction
| DIRECTION_XX
| No
|
See [[NML:List of direction constants|here]] for an overview of possible values and their meaning.
|-
| cargo_capacity
| 0 ... 65535
| No
| Cargo capacity (number of units) of the vehicle
|-
| cargo_count
| 0 ... 65535
| No
| Number of cargo units of cargo in the vehicle
|-
| cargo_subtype
| 0 ... 255
| Yes, always 0
| Cargo subtype, used to provide more than one refit option for the same cargo type. See also the <code style="color:darkgreen">cargo_subtype_text</code> callback.
|-
| vehicle_is_powered
| [0 <nowiki>|</nowiki> 1]
| No
| Vehicle provides power and is on the correct track type
|-
| vehicle_is_not_powered
| [0 <nowiki>|</nowiki> 1]
| No
| Vehicle is either on a wrong track type or it doesn't provide power at all
|-
| vehicle_is_potentially_powered
| [0 <nowiki>|</nowiki> 1]
| No
| Vehicle provides power, if it is on a suitable track type
|-
| vehicle_is_reversed
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle has reversed an odd number of times
|-
| built_during_preview
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle was built during the exclusive preview stage
|-
| current_railtype
| No
| Entry from railtype translation table or 0xFF
| Don't use this variable unless you've defined a railtype translation table. If the train is running on a railtype that is not listed in your railtype translation table this variable will contain 0xFF. Available since OpenTTD r20164.
|-
| waiting_triggers
|
| No
|
Random triggers waiting to be matched. (see [[NML:Random switch|Random switch]])
|-
| random_bits
| 0 ... 255
| No
|
Random data that can be used to randomize certain descisions. (see [[NML:Random switch|Random switch]])
|-
| grfid
| 0 ... 0xFFFFFFFF
| No
|
GRFID that defined the [[NML:Graphics|graphics]]-block for this vehicle. To compare this with other grfids, use the [[NML:Builtin functions|builtin function]] <code style="color:darkgreen">str2number()</code> to convert the other GRFID to a number as well.
|-
| vehicle_type_id
| 0 ... 65535
| No
| GRF-local ID of the vehicle, equal to the item ID. Note that vehicles from other NewGRFs may have the same ID, so you'll generally have to check the <code style="color:darkgreen">grfid</code> as well.
|-
| vehicle_is_hidden
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle is hidden in a depot or tunnel.
|-
| vehicle_is_stopped
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle is stopped, or if it is braking for a stop (trains only).
|-
| vehicle_is_crashed
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle has crashed.
|-
| vehicle_is_broken
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle is broken down.
|-
| date_of_last_service
| date(year, month, day)
| No
|
|-
| breakdowns_since_last_service
| 0 ... 255
| No
| Number of breakdowns since the last service
|-
| reliability
| 0 ... 100
| No
| Reliability (percentage)
|-
| age_in_days
| 0 ... 65535
| No
| Vehicle age in days.
|-
| max_age_in_days
| 0 ... 65535
| No
| Maximum vehicle age in days.
|-
| current_speed
| (speed units)
| No
| The current speed of the vehicle in m/s
|-
| max_speed
| (speed units)
| No
| The maximum speed of the vehicle in m/s
|-
| current_max_speed
| (speed units)
| No
| {{nml|0.3}} {{ottdp|1.3|no|ottdrev=r24246}} Current maximum speed of the vehicle in m/s. This includes e.g. track or timetable limits. Only valid for front vehicle.
|-
| vehicle_is_in_depot
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle is inside a depot
|}

===Variables that require an argument===

{| class="t"
! name
! Argument
! value range
! available in purchase list?
! comment
|-
| count_veh_id
| The vehicle ID to look for.
| 0..255
| No
| The number of vehicles in the current consist that have the given ID.
|-
| other_veh_curv_info
| Offset in the chain from the current vehicle.<ref name="offset">Value range is -128..127. Positive values are interpreted as towards the end, negative values as towards the front. If the offset is outside the vehicle chain, the result value will be 0.</ref>
| -4..4
| No
| Difference in direction between the other vehicle and this vehicle. Curvature to the right is positive. 1 unit is 45 degrees.
|-
| other_veh_is_hidden
| Offset in the chain from the current vehicle.<ref name="offset"/>
| [0 <nowiki>|</nowiki> 1]
| No
| 1 the other vehicle is hidden in a depot or tunnel, 0 otherwise
|-
| other_veh_x_offset
| Offset in the chain from the current vehicle.<ref name="offset"/>
| -128..127
| No
| Signed difference in X-position (top-right to bottom-left) between the other vehicle and this vehicle.
|-
| other_veh_x_offset
| Offset in the chain from the current vehicle.<ref name="offset"/>
| -128..127
| No
| Signed difference in Y-position (top-left to bottom-right) between the other vehicle and this vehicle.
|-
| other_veh_is_hidden
| Offset in the chain from the current vehicle.<ref name="offset"/>
| -128..127
| No
| Signed difference in Z-position (upwards) between the other vehicle and this vehicle.
|}
<references/>

==Vehicle callbacks==
The following table contains a list of available vehicle callbacks. Additionally, it's possible to provide cargo-specific graphics, using the identifier from the [[NML:Cargotable|cargo table]] as callback name. These callbacks will be used if the vehicle is refitted to the corresponding cargo type. If no cargo-specific graphics match the cargo that the vehicle is carrying, the <code style="color:darkgreen">default</code> callback is used instead. Cargo-specific graphics callbacks are never called from the purchase menu, refer to the <code style="color:darkgreen">purchase</code> callback below instead.

Note that the above affects '''graphics only''', other callbacks are unaffected.

{| class="t"
! Name
! Available for
! In purchase menu?
! value range
! comment
|-
| default
| All
| Yes, unless <code style="color:darkgreen">purchase</code> is set separately
| Sprite group
| 'Normal' vehicle graphics, if no cargo-specific graphics apply. See also the section on [[#Sprites in GUI|GUI sprites]].
|-
| purchase
| All
| Yes, only
| Sprite group
| Graphics to show in the buy menu (only the horizontal view is needed, except for dual-headed trains. With the <code>dual_headed</code> property set, special rules for the purchase menu sprite apply: two sprites are drawn (for front and back) as if the vehicle is normally constructed. If you supply one purchase menu sprite, it will be used for both vehicle parts in the purchase menu. Provide a set of 8 sprites, and the 7th resp. 3rd sprite will be drawn; provide a set of 8 blank sprites except the 7th if you want to fully control a single purchase menu sprite for a dual-headed engine. ) See also the section on [[#Sprites in GUI|GUI sprites]].
|-
| rotor
| Aircraft (helicopters)
| No
| Sprite group
| Graphics for the helicopter rotor (4 sprites; 1 stopped and 3 moving)
|-
| random_trigger
| All
| No
| N/A
| See [[NML:Random switch|random switch]] for more information.
|-
| cargo_subtype_text
| All
| No
| String, or CB_RESULT_NO_TEXT
| With this callback, you can display extra text after the cargo in the vehicle information window. This callback is called during refitting, with succesively increased values of the <code style="color:darkgreen">cargo_subtype</code> variable, until the callback returns CB_RESULT_NO_TEXT. All returned strings are then displayed as refit options. The chosen refit option is saved in the <code style="color:darkgreen">cargo_subtype</code> variable, so it can be used later for other things. In the HEQS grf for example, this mechanism is used to let the user choose between different capacities of the same vehicle.
|-
| additional_text
| All
| Yes, only
| String
| Additional text to show in the purchase list.
|-
| colour_mapping
| All
| Yes, unless <code style="color:darkgreen">purchase_colour_mapping</code> is set separately
| Recolour sprite number
|
With this callback, you can use a different recolour sprite instead of the standard 1cc / 2cc company colour remappings. See [[NML:List of default colour translation palettes|here]] for a list of default palettes. See the [[NML:Builtin functions|builtin function]] <code style="color:darkgreen">reserve_sprites()</code> for info on how to allocate your own sprite. For performance, the result is cached and only updated if the <code style="color:darkgreen"> every_32_days</code> callback requires so. Add CB_RESULT_COLOUR_MAPPING_ADD_CC to the result to add the company colour to the sprites, this requires 16 (1cc) or 256 (2cc) sprites in total.
|-
| start_stop
| All
| No
| String or CB_RESULT_NO_TEXT
| Called when starting or stopping a vehicle. Mainly useful to prevent vehicles from leaving the depot unless a certain condition is met. Return CB_RESULT_NO_TEXT to allow or a string (containing an error message) to disallow starting/stopping.
|-
| every_32_days
| All
| No
| bitmask(CB_RESULT_32_DAYS_XXX, ...)
| Called every 32 days. Set CB_RESULT_32_DAYS_TRIGGER in the bitmask to trigger TRIGGER_VEHICLE_32_CALLBACK. Set CB_RESULT_32_DAYS_COLOUR_MAPPING in the bitmask to update the colour mapping by re-running the <code style="color:darkgreen">colour_mapping</code> callback.
|-
| sound_effect
| All
| No
| SOUND_XXX, sound("sound.wav"), import_sound(grfid, number) or CB_RESULT_NO_SOUND
|
Called to play various vehicle sounds. <code style="color:darkgreen">extra_callback_info1</code> contains the sound event, see the [[#Sound events|table]] below. Return SOUND_XXX (see [[NML:List_of_sound_effects|here]]) to return a default sound. <code style="color:darkgreen">sound("soundfile")</code> imports a sound from a .wav file. <code style="color:darkgreen">import_sound(grfid, number)</code> imports a sound from another grf. A failed (or not implemented) callback will cause the default sound to be played. Return CB_RESULT_NO_SOUND to play no sound at all.
|-
| articulated_part
| Trains, Road Vehicles
| Yes (no separate callback)
| Vehicle ID, or CB_RESULT_NO_MORE_ARTICULATED_PARTS
| With this callback, you can add articulated parts (e.g. tenders) to your vehicle. Called repeatedly, until CB_RESULT_NO_MORE_ARTICULATED_PARTS is returned. After each call, the returned vehicleID is added to your vehicle. <code style="color:darkgreen">extra_callback_info1</code> contains 1 during the first call, 2 during the second, etc. Note that callback may be called from the purchase list, using vehicle variables is not possible. Or CB_RESULT_REVERSED_VEHICLE to the returned vehicle ID to display the vehicle backwards.

For NML 0.2 and lower the vehicle ID of the articulated part must be in the range 0 .. 127.
|-
| can_attach_wagon
| Trains
| No
| String or CB_RESULT_ATTACH_XXX
| Called when a wagon is being attached, to allow or disallow attaching. This callback has to be defined at the engine. However, variables in the <code style="color:darkgreen">SELF</code> scope refer to the wagon being attached, the <code style="color:darkgreen">PARENT</code> scope refers to the engine that the wagon is being attached to. Return a string to disallow with the string as error message. Return CB_RESULT_ATTACH_DISALLOW to disallow with standard message ("incompatible railtypes"), CB_RESULT_ATTACH_ALLOW to allow or CB_RESULT_ATTACH_ALLOW_IF_RAILTYPES to allow if the railtypes match (default).
|-
| refit_cost
| {{ottdp|1.2|no|ottdrev=r23089}} All
| Yes
| -8192 .. 8191 as refit cost. Add <code style="color:darkgreen">CB_RESULT_AUTOREFIT</code> if you want to allow autorefit.
| When returning a negative value, encode the cost as (cost & <code style="color:darkgreen">CB_RESULT_REFIT_COST_MASK</code>) before (possibly) adding <code style="color:darkgreen">CB_RESULT_AUTOREFIT</code>. To allow autorefitting, the corresponding bit in the <code style="color:darkgreen">misc_flags</code> must be set as well. Variable <code style="color:darkgreen">extra_callback_info1</code> contains information about the target cargo type in the format 0xccccsstt, with tt being the new cargo type, ss the new cargo subtype (see <code style="color:darkgreen">cargo_subtype_text</code>-callback) and cccc a bitmask of the [[NML:Cargos#Cargo_classes|cargo classes]] of the target cargo type. Note that this callback may also be called when the vehicle does not exist yet, so the available variables are limited.
|}

The following callbacks all have an equivalent property. The property description applies here also, except where otherwise noted.

{| class="t"
! Name
! Available for
! In purchase menu?
! comment
|-
| loading_speed
| All
| No
|
|-
| speed
| All
| Yes, unless <code style="color:darkgreen">purchase_speed</code> is set separately
| Units are not (yet) available
|-
| cost_factor
| All
| Yes, only
|
|-
| running_cost_factor
| All
| Yes, unless <code style="color:darkgreen">purchase_running_cost_factor</code> is set separately
|
|-
| cargo_age_period
| All
| No
|
|-
| cargo_capacity
| All except aircraft
| Yes, unless <code style="color:darkgreen">purchase_cargo_capacity</code> is set separately
|
|-
| passenger_capacity
| Aircraft
| Yes, unless <code style="color:darkgreen">purchase_passenger_capacity</code> is set separately
|
|-
| mail_capacity
| Aircraft
| Yes, unless <code style="color:darkgreen">purchase_mail_capacity</code> is set separately
|
|-
| range
| Aircraft
| Yes, unless <code style="color:darkgreen">purchase_range</code> is set separately
|
|-
| visual_effect_and_powered
| Trains
| No
|
|-
| visual_effect
| Road Vehicles, Ships
| No
|
|-
| power
| Trains, Road Vehicles
| Yes, unless <code style="color:darkgreen">purchase_power</code> is set separately
| Units are not (yet) available
|-
| weight
| Trains, Road Vehicles
| Yes, unless <code style="color:darkgreen">purchase_weight</code> is set separately
| Units are not (yet) available
|-
| length
| Trains, Road vehicles
| No
|
|-
| tractive_effort_coefficient
| Trains, Road Vehicles
| Yes, unless <code style="color:darkgreen">purchase_tractive_effort_coefficient</code> is set separately
| Value range is 0 .. 255 instead of 0 .. 1.
|-
| bitmask_vehicle_info
| Trains
| No
|
|}

===Sprites in GUI===
{{ottdp|1.2|no|ottdrev=r23080}} Since OpenTTD r23080 you can use variable <code style="color:darkgreen">extra_callback_info1</code> to display different sprites in the GUI and on the map. Currently these cases are available:
{| |-
! Lowest byte of extra_callback_info1 !! Meaning
|-
| 0x00 || Vehicle is drawn in a viewport, i.e. on the map.
|-
| 0x01..0x0F || reserved
|-
| 0x10 || Vehicle is drawn in the depot GUI. <ref>OpenTTD also uses this value with the purchase-list chain (cargotype FF) to determine the gridsize in ship and aircraft depots.</ref>
|-
| 0x11 || Vehicle is drawn in the vehicle details GUI. (This includes the refit GUI.)
|-
| 0x12 || Vehicle is drawn in the vehicle list.
|-
| 0x13..0x1F || reserved for other future GUIs.
|-
| 0x20 || Vehicle is drawn in the purchase list. (This includes the autoreplace GUI.)
|-
| 0x21 || Vehicle is drawn in the exclusive preview GUI or in the advertisement news.
|-
| 0x22..0x2F || reserved for other future GUIs with non-purchased vehicles.
|-
| 0x30..0xFF || reserved
|}
<references/>
The other bytes of variable <code style="color:darkgreen">extra_callback_info1</code> are reserved, and must be masked.
The cases 0x20..0x2F are called using the <code style="color:darkgreen">purchase</code>-callback, the other cases are called for the <code style="color:darkgreen">default</code>- or cargo-specific callbacks. Exception is the the special depot-gridsize call, which uses the <code style="color:darkgreen">purchase</code>-callback.

===Sound events===

{| class="t"
! Event
! Description
|-
| SOUND_EVENT_START
| Vehicle leaves station or depot, plane takes off
|-
| SOUND_EVENT_TUNNEL
| Vehicle enters tunnel
|-
| SOUND_EVENT_BREAKDOWN
| Vehicle breaks down (not for planes)
|-
| SOUND_EVENT_RUNNING
| Once per engine tick, but no more than once per vehicle motion
|-
| SOUND_EVENT_TOUCHDOWN
| Aircraft touches down
|-
| SOUND_EVENT_VISUAL_EFFECT
| Visual effect is generated (steam plume, diesel smoke, electric spark)
|-
| SOUND_EVENT_RUNNING_16
| Every 16 engine ticks if in motion
|-
| SOUND_EVENT_STOPPED
| Every 16 engine ticks if stopped
|-
| SOUND_EVENT_LOAD_UNLOAD
| Consist loads or unloads cargo
|}

VehicleIDs

2012-08-02T17:52:36Z

Hirundo: Add NML (decimal) vehicle IDs

== Introduction ==

This is a list of vehicle IDs, for example for choosing the ID to change in [[Action0|action 0]] or [[Action3|Action 3]].

The first column of each table shows the ID of the vehicle within the game (in decimal), the second columns shows the ID to use for .NFO files (in hex), and the third column shows the standard name of the vehicle.

Please see the RoadVehicleIDRecommendation for information on how to make your road vehicle set compatible with other road vehicle sets.

The IDs listed are the only IDs that can be used in TTDPatch and OpenTTD prior to r12924. Since OpenTTD r13482, IDs greater than 255 are allowed, up to a theoretical limit of 65535. Any engine defined which is not in the original range listed below will have no default properties, including name.

==Train Engines==

{|
!ID!!NFO ID!!NML ID!!Name

|-
|0||<center>00</center>||<center>0</center>||Kirby Paul Tank (Steam)

|-
|1||<center>01</center>||<center>1</center>||MJS 250 (Diesel)

|-
|2||<center>02</center>||<center>2</center>||Ploddyphut Choo-Choo

|-
|3||<center>03</center>||<center>3</center>||Powernaut Choo-Choo

|-
|4||<center>04</center>||<center>4</center>||Mightymover Choo-Choo

|-
|5||<center>05</center>||<center>5</center>||Ploddyphut Diesel

|-
|6||<center>06</center>||<center>6</center>||Powernaut Diesel

|-
|7||<center>07</center>||<center>7</center>||Wills 2-8-0 (Steam)

|-
|8||<center>08</center>||<center>8</center>||Chaney 'Jubilee' (Steam)

|-
|9||<center>09</center>||<center>9</center>||Ginzu 'A4' (Steam)

|-
|10||<center>0A</center>||<center>10</center>||SH '8P' (Steam)

|-
|11||<center>0B</center>||<center>11</center>||Manley-Morel DMU (Diesel)

|-
|12||<center>0C</center>||<center>12</center>||'Dash' (Diesel)

|-
|13||<center>0D</center>||<center>13</center>||SH/Hendry '25' (Diesel)

|-
|14||<center>0E</center>||<center>14</center>||UU '37' (Diesel)

|-
|15||<center>0F</center>||<center>15</center>||Floss '47' (Diesel)

|-
|16||<center>10</center>||<center>16</center>||CS 4000 (Diesel)

|-
|17||<center>11</center>||<center>17</center>||CS 2400 (Diesel)

|-
|18||<center>12</center>||<center>18</center>||Centennial (Diesel)

|-
|19||<center>13</center>||<center>19</center>||Kelling 3100 (Diesel)

|-
|20||<center>14</center>||<center>20</center>||Turner Turbo (Diesel)

|-
|21||<center>15</center>||<center>21</center>||MJS 1000 (Diesel)

|-
|22||<center>16</center>||<center>22</center>||SH '125' (Diesel)

|-
|23||<center>17</center>||<center>23</center>||SH '30' (Electric)

|-
|24||<center>18</center>||<center>24</center>||SH '40' (Electric)

|-
|25||<center>19</center>||<center>25</center>||'T.I.M.' (Electric)

|-
|26||<center>1A</center>||<center>26</center>||'AsiaStar' (Electric)
|}

==Train Wagons==

{|
!ID!!NFO ID!!NML ID!!Name

|-
|27||<center>1B</center>||<center>27</center>||Passenger Carriage

|-
|28||<center>1C</center>||<center>28</center>||Mail Van

|-
|29||<center>1D</center>||<center>29</center>||Coal Truck

|-
|30||<center>1E</center>||<center>30</center>||Oil Tanker

|-
|31||<center>1F</center>||<center>31</center>||Livestock Van

|-
|32||<center>20</center>||<center>32</center>||Goods Van

|-
|33||<center>21</center>||<center>33</center>||Grain Hopper

|-
|34||<center>22</center>||<center>34</center>||Wood Truck

|-
|35||<center>23</center>||<center>35</center>||Iron Ore Hopper

|-
|36||<center>24</center>||<center>36</center>||Steel Truck

|-
|37||<center>25</center>||<center>37</center>||Armoured Van

|-
|38||<center>26</center>||<center>38</center>||Food Van

|-
|39||<center>27</center>||<center>39</center>||Paper Truck

|-
|40||<center>28</center>||<center>40</center>||Copper Ore Hopper

|-
|41||<center>29</center>||<center>41</center>||Water Tanker

|-
|42||<center>2A</center>||<center>42</center>||Fruit Truck

|-
|43||<center>2B</center>||<center>43</center>||Rubber Truck

|-
|44||<center>2C</center>||<center>44</center>||Sugar Truck

|-
|45||<center>2D</center>||<center>45</center>||Candyfloss Hopper

|-
|46||<center>2E</center>||<center>46</center>||Toffee Hopper

|-
|47||<center>2F</center>||<center>47</center>||Bubble Van

|-
|48||<center>30</center>||<center>48</center>||Cola Tanker

|-
|49||<center>31</center>||<center>49</center>||Sweet Van

|-
|50||<center>32</center>||<center>50</center>||Toy Van

|-
|51||<center>33</center>||<center>51</center>||Battery Truck

|-
|52||<center>34</center>||<center>52</center>||Fizzy Drink Truck

|-
|53||<center>35</center>||<center>53</center>||Plastic Truck
|}

==Monorail Engines==

{|
!ID!!NFO ID!!NML ID!!Name

|-
|54||<center>36</center>||<center>54</center>||'X2001' (Electric)

|-
|55||<center>37</center>||<center>55</center>||'Millennium Z1' (Electric)

|-
|56||<center>38</center>||<center>56</center>||Wizzowow Z99
|}

==Monorail Wagons==

{|
!ID!!NFO ID!!NML ID!!Name

|-
|57||<center>39</center>||<center>57</center>||Passenger Carriage

|-
|58||<center>3A</center>||<center>58</center>||Mail Van

|-
|59||<center>3B</center>||<center>59</center>||Coal Truck

|-
|60||<center>3C</center>||<center>60</center>||Oil Tanker

|-
|61||<center>3D</center>||<center>61</center>||Livestock Van

|-
|62||<center>3E</center>||<center>62</center>||Goods Van

|-
|63||<center>3F</center>||<center>63</center>||Grain Hopper

|-
|64||<center>40</center>||<center>64</center>||Wood Truck

|-
|65||<center>41</center>||<center>65</center>||Iron Ore Hopper

|-
|66||<center>42</center>||<center>66</center>||Steel Truck

|-
|67||<center>43</center>||<center>67</center>||Armoured Van

|-
|68||<center>44</center>||<center>68</center>||Food Van

|-
|69||<center>45</center>||<center>69</center>||Paper Truck

|-
|70||<center>46</center>||<center>70</center>||Copper Ore Hopper

|-
|71||<center>47</center>||<center>71</center>||Water Tanker

|-
|72||<center>48</center>||<center>72</center>||Fruit Truck

|-
|73||<center>49</center>||<center>73</center>||Rubber Truck

|-
|74||<center>4A</center>||<center>74</center>||Sugar Truck

|-
|75||<center>4B</center>||<center>75</center>||Candyfloss Hopper

|-
|76||<center>4C</center>||<center>76</center>||Toffee Hopper

|-
|77||<center>4D</center>||<center>77</center>||Bubble Van

|-
|78||<center>4E</center>||<center>78</center>||Cola Tanker

|-
|79||<center>4F</center>||<center>79</center>||Sweet Van

|-
|80||<center>50</center>||<center>80</center>||Toy Van

|-
|81||<center>51</center>||<center>81</center>||Battery Truck

|-
|82||<center>52</center>||<center>82</center>||Fizzy Drink Truck

|-
|83||<center>53</center>||<center>83</center>||Plastic Truck
|}

==Maglev Engines==

{|
!ID!!NFO ID!!NML ID!!Name

|-
|84||<center>54</center>||<center>84</center>||Lev1 'Leviathan' (Electric)

|-
|85||<center>55</center>||<center>85</center>||Lev2 'Cyclops' (Electric)

|-
|86||<center>56</center>||<center>86</center>||Lev3 'Pegasus' (Electric)

|-
|87||<center>57</center>||<center>87</center>||Lev4 'Chimaera' (Electric)

|-
|88||<center>58</center>||<center>88</center>||Wizzowow Rocketeer
|}

==Maglev Wagons==

{|
!ID!!NFO ID!!NML ID!!Name

|-
|89||<center>59</center>||<center>89</center>||Passenger Carriage

|-
|90||<center>5A</center>||<center>90</center>||Mail Van

|-
|91||<center>5B</center>||<center>91</center>||Coal Truck

|-
|92||<center>5C</center>||<center>92</center>||Oil Tanker

|-
|93||<center>5D</center>||<center>93</center>||Livestock Van

|-
|94||<center>5E</center>||<center>94</center>||Goods Van

|-
|95||<center>5F</center>||<center>95</center>||Grain Hopper

|-
|96||<center>60</center>||<center>96</center>||Wood Truck

|-
|97||<center>61</center>||<center>97</center>||Iron Ore Hopper

|-
|98||<center>62</center>||<center>98</center>||Steel Truck

|-
|99||<center>63</center>||<center>99</center>||Armoured Van

|-
|100||<center>64</center>||<center>100</center>||Food Van

|-
|101||<center>65</center>||<center>101</center>||Paper Truck

|-
|102||<center>66</center>||<center>102</center>||Copper Ore Hopper

|-
|103||<center>67</center>||<center>103</center>||Water Tanker

|-
|104||<center>68</center>||<center>104</center>||Fruit Truck

|-
|105||<center>69</center>||<center>105</center>||Rubber Truck

|-
|106||<center>6A</center>||<center>106</center>||Sugar Truck

|-
|107||<center>6B</center>||<center>107</center>||Candyfloss Hopper

|-
|108||<center>6C</center>||<center>108</center>||Toffee Hopper

|-
|109||<center>6D</center>||<center>109</center>||Bubble Van

|-
|110||<center>6E</center>||<center>110</center>||Cola Tanker

|-
|111||<center>6F</center>||<center>111</center>||Sweet Van

|-
|112||<center>70</center>||<center>112</center>||Toy Van

|-
|113||<center>71</center>||<center>113</center>||Battery Truck

|-
|114||<center>72</center>||<center>114</center>||Fizzy Drink Truck

|-
|115||<center>73</center>||<center>115</center>||Plastic Truck
|}

==Buses==

{|
!ID!!NFO ID!!NML ID!!Name

|-
|116||<center>00</center>||<center>0</center>||MPS Regal Bus

|-
|117||<center>01</center>||<center>1</center>||Hereford Leopard Bus

|-
|118||<center>02</center>||<center>2</center>||Foster Bus

|-
|119||<center>03</center>||<center>3</center>||Foster MkII Superbus

|-
|120||<center>04</center>||<center>4</center>||Ploddyphut MkI Bus

|-
|121||<center>05</center>||<center>5</center>||Ploddyphut MkII Bus

|-
|122||<center>06</center>||<center>6</center>||Ploddyphut MkIII Bus
|}

==Trucks - Regular climates (mostly)==

{|
!ID!!NFO ID!!NML ID!!Name

|-
|123||<center>07</center>||<center>7</center>||Balogh Coal Truck

|-
|124||<center>08</center>||<center>8</center>||Uhl Coal Truck

|-
|125||<center>09</center>||<center>9</center>||DW Coal Truck

|-
|126||<center>0A</center>||<center>10</center>||MPS Mail Truck

|-
|127||<center>0B</center>||<center>11</center>||Reynard Mail Truck

|-
|128||<center>0C</center>||<center>12</center>||Perry Mail Truck

|-
|129||<center>0D</center>||<center>13</center>||MightyMover Mail Truck

|-
|130||<center>0E</center>||<center>14</center>||Powernaught Mail Truck

|-
|131||<center>0F</center>||<center>15</center>||Wizzowow Mail Truck

|-
|132||<center>10</center>||<center>16</center>||Witcombe Oil Tanker

|-
|133||<center>11</center>||<center>17</center>||Foster Oil Tanker

|-
|134||<center>12</center>||<center>18</center>||Perry Oil Tanker

|-
|135||<center>13</center>||<center>19</center>||Talbott Livestock Van

|-
|136||<center>14</center>||<center>20</center>||Uhl Livestock Van

|-
|137||<center>15</center>||<center>21</center>||Foster Livestock Van

|-
|138||<center>16</center>||<center>22</center>||Balogh Goods Truck

|-
|139||<center>17</center>||<center>23</center>||Craighead Goods Truck

|-
|140||<center>18</center>||<center>24</center>||Goss Goods Truck

|-
|141||<center>19</center>||<center>25</center>||Hereford Grain Truck

|-
|142||<center>1A</center>||<center>26</center>||Thomas Grain Truck

|-
|143||<center>1B</center>||<center>27</center>||Goss Grain Truck

|-
|144||<center>1C</center>||<center>28</center>||Witcombe Wood Truck

|-
|145||<center>1D</center>||<center>29</center>||Foster Wood Truck

|-
|146||<center>1E</center>||<center>30</center>||Moreland Wood Truck

|-
|147||<center>1F</center>||<center>31</center>||MPS Iron Ore Truck

|-
|148||<center>20</center>||<center>32</center>||Uhl Iron Ore Truck

|-
|149||<center>21</center>||<center>33</center>||Chippy Iron Ore Truck

|-
|150||<center>22</center>||<center>34</center>||Balogh Steel Truck

|-
|151||<center>23</center>||<center>35</center>||Uhl Steel Truck

|-
|152||<center>24</center>||<center>36</center>||Kelling Steel Truck

|-
|153||<center>25</center>||<center>37</center>||Balogh Armoured Truck

|-
|154||<center>26</center>||<center>38</center>||Uhl Armoured Truck

|-
|155||<center>27</center>||<center>39</center>||Foster Armoured Truck

|-
|156||<center>28</center>||<center>40</center>||Foster Food Van

|-
|157||<center>29</center>||<center>41</center>||Perry Food Van

|-
|158||<center>2A</center>||<center>42</center>||Chippy Food Van

|-
|159||<center>2B</center>||<center>43</center>||Uhl Paper Truck

|-
|160||<center>2C</center>||<center>44</center>||Balogh Paper Truck

|-
|161||<center>2D</center>||<center>45</center>||MPS Paper Truck

|-
|162||<center>2E</center>||<center>46</center>||MPS Copper Ore Truck

|-
|163||<center>2F</center>||<center>47</center>||Uhl Copper Ore Truck

|-
|164||<center>30</center>||<center>48</center>||Goss Copper Ore Truck

|-
|165||<center>31</center>||<center>49</center>||Uhl Water Tanker

|-
|166||<center>32</center>||<center>50</center>||Balogh Water Tanker

|-
|167||<center>33</center>||<center>51</center>||MPS Water Tanker

|-
|168||<center>34</center>||<center>52</center>||Balogh Fruit Truck

|-
|169||<center>35</center>||<center>53</center>||Uhl Fruit Truck

|-
|170||<center>36</center>||<center>54</center>||Kelling Fruit Truck

|-
|171||<center>37</center>||<center>55</center>||Balogh Rubber Truck

|-
|172||<center>38</center>||<center>56</center>||Uhl Rubber Truck

|-
|173||<center>39</center>||<center>57</center>||RMT Rubber Truck
|}

==Trucks - Toyland==

{|
!ID!!NFO ID!!NML ID!!Name

|-
|174||<center>3A</center>||<center>58</center>||MightyMover Sugar Truck

|-
|175||<center>3B</center>||<center>59</center>||Powernaught Sugar Truck

|-
|176||<center>3C</center>||<center>60</center>||Wizzowow Sugar Truck

|-
|177||<center>3D</center>||<center>61</center>||MightyMover Cola Truck

|-
|178||<center>3E</center>||<center>62</center>||Powernaught Cola Truck

|-
|179||<center>3F</center>||<center>63</center>||Wizzowow Cola Truck

|-
|180||<center>40</center>||<center>64</center>||MightyMover Candyfloss Truck

|-
|181||<center>41</center>||<center>65</center>||Powernaught Candyfloss Truck

|-
|182||<center>42</center>||<center>66</center>||Wizzowow Candyfloss Truck

|-
|183||<center>43</center>||<center>67</center>||MightyMover Toffee Truck

|-
|184||<center>44</center>||<center>68</center>||Powernaught Toffee Truck

|-
|185||<center>45</center>||<center>69</center>||Wizzowow Toffee Truck

|-
|186||<center>46</center>||<center>70</center>||MightyMover Toy Van

|-
|187||<center>47</center>||<center>71</center>||Powernaught Toy Van

|-
|188||<center>48</center>||<center>72</center>||Wizzowow Toy Van

|-
|189||<center>49</center>||<center>73</center>||MightyMover Sweet Lorry

|-
|190||<center>4A</center>||<center>74</center>||Powernaught Sweet Lorry

|-
|191||<center>4B</center>||<center>75</center>||Wizzowow Sweet Lorry

|-
|192||<center>4C</center>||<center>76</center>||MightyMover Battery Truck

|-
|193||<center>4D</center>||<center>77</center>||Powernaught Battery Truck

|-
|194||<center>4E</center>||<center>78</center>||Wizzowow Battery Truck

|-
|195||<center>4F</center>||<center>79</center>||MightyMover Fizzy Drink Truck

|-
|196||<center>50</center>||<center>80</center>||Powernaught Fizzy Drink Truck

|-
|197||<center>51</center>||<center>81</center>||Wizzowow Fizzy Drink Truck

|-
|198||<center>52</center>||<center>82</center>||MightyMover Plastic Truck

|-
|199||<center>53</center>||<center>83</center>||Powernaught Plastic Truck

|-
|200||<center>54</center>||<center>84</center>||Wizzowow Plastic Truck

|-
|201||<center>55</center>||<center>85</center>||MightyMover Bubble Truck

|-
|202||<center>56</center>||<center>86</center>||Powernaught Bubble Truck

|-
|203||<center>57</center>||<center>87</center>||Wizzowow Bubble Truck
|}

==Ships==

{|
!ID!!NFO ID!!NML ID!!Name

|-
|204||<center>00</center>||<center>0</center>||MPS Oil Tanker

|-
|205||<center>01</center>||<center>1</center>||CS-Inc. Oil Tanker

|-
|206||<center>02</center>||<center>2</center>||MPS Passenger Ferry

|-
|207||<center>03</center>||<center>3</center>||FFP Passenger Ferry

|-
|208||<center>04</center>||<center>4</center>||Bakewell 300 Hovercraft

|-
|209||<center>05</center>||<center>5</center>||Chugger-Chug Passenger Ferry

|-
|210||<center>06</center>||<center>6</center>||Shivershake Passenger Ferry

|-
|211||<center>07</center>||<center>7</center>||Yate Cargo ship

|-
|212||<center>08</center>||<center>8</center>||Bakewell Cargo ship

|-
|213||<center>09</center>||<center>9</center>||Mightymover Cargo ship

|-
|214||<center>0A</center>||<center>10</center>||Powernaut Cargo ship
|}

==Planes==

{|
!ID!!NFO ID!!NML ID!!Name

|-
|215||<center>00</center>||<center>0</center>||Sampson U52

|-
|216||<center>01</center>||<center>1</center>||Coleman Count

|-
|217||<center>02</center>||<center>2</center>||FFP Dart

|-
|218||<center>03</center>||<center>3</center>||Yate Haugan

|-
|219||<center>04</center>||<center>4</center>||Bakewell Cotswald LB-3

|-
|220||<center>05</center>||<center>5</center>||Bakewell Luckett LB-8

|-
|221||<center>06</center>||<center>6</center>||Bakewell Luckett LB-9

|-
|222||<center>07</center>||<center>7</center>||Bakewell Luckett LB80

|-
|223||<center>08</center>||<center>8</center>||Bakewell Luckett LB-10

|-
|224||<center>09</center>||<center>9</center>||Bakewell Luckett LB-11

|-
|225||<center>0A</center>||<center>10</center>||Yate Aerospace YAC 1-11

|-
|226||<center>0B</center>||<center>11</center>||Darwin 100

|-
|227||<center>0C</center>||<center>12</center>||Darwin 200

|-
|228||<center>0D</center>||<center>13</center>||Darwin 300

|-
|229||<center>0E</center>||<center>14</center>||Darwin 400

|-
|230||<center>0F</center>||<center>15</center>||Darwin 500

|-
|231||<center>10</center>||<center>16</center>||Darwin 600

|-
|232||<center>11</center>||<center>17</center>||Guru Galaxy

|-
|233||<center>12</center>||<center>18</center>||Airtaxi A21

|-
|234||<center>13</center>||<center>19</center>||Airtaxi A31

|-
|235||<center>14</center>||<center>20</center>||Airtaxi A32

|-
|236||<center>15</center>||<center>21</center>||Airtaxi A33

|-
|237||<center>16</center>||<center>22</center>||Yate Aerospace YAe46

|-
|238||<center>17</center>||<center>23</center>||Dinger 100

|-
|239||<center>18</center>||<center>24</center>||AirTaxi A34-1000

|-
|240||<center>19</center>||<center>25</center>||Yate Z-Shuttle

|-
|241||<center>1A</center>||<center>26</center>||Kelling K1

|-
|242||<center>1B</center>||<center>27</center>||Kelling K6

|-
|243||<center>1C</center>||<center>28</center>||Kelling K7

|-
|244||<center>1D</center>||<center>29</center>||Darwin 700

|-
|245||<center>1E</center>||<center>30</center>||FFP Hyperdart 2

|-
|246||<center>1F</center>||<center>31</center>||Dinger 200

|-
|247||<center>20</center>||<center>32</center>||Dinger 1000

|-
|248||<center>21</center>||<center>33</center>||Ploddyphut 100

|-
|249||<center>22</center>||<center>34</center>||Ploddyphut 500

|-
|250||<center>23</center>||<center>35</center>||Flashbang X1

|-
|251||<center>24</center>||<center>36</center>||Juggerplane M1

|-
|252||<center>25</center>||<center>37</center>||Flashbang Wizzer
|}

==Helicopters==

{|
!ID!!NFO ID!!NML ID!!Name

|-
|253||<center>26</center>||<center>38</center>||Tricario Helicopter

|-
|254||<center>27</center>||<center>39</center>||Guru X2 Helicopter

|-
|255||<center>28</center>||<center>40</center>||Powernaut Helicopter
|}

NML:Houses

2012-08-02T08:16:21Z

Hirundo: /* House properties */ Fix local_authority_impact description

{{NMLNavPropVarCB}}

==House properties==

{| class="t"
! property
! value range
! comment
|-
| name
| string
| for example string(STR_NAME_EIFFEL_TOWER)
|-
| substitute
| 0 ... 109
| Number of the default house that replaces this one, if this house 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 ... 109
| id of the default house which this house replaces. This will cause your house to be placed instead of the default house. This is ignored, if the default house has already been overridden. You can define this property multiple times
|-
| building_flags
| bitmask(HOUSE_FLAG_XXX,...)
|
;HOUSE_FLAG_SIZE_1x1
;HOUSE_FLAG_SIZE_2x1
;HOUSE_FLAG_SIZE_1x2
;HOUSE_FLAG_SIZE_2x2
;HOUSE_FLAG_NOT_SLOPED
:Can only be built on flat terrain
;HOUSE_FLAG_ANIMATE
:Enable animation
;HOUSE_FLAG_CHURCH
:House is a church
;HOUSE_FLAG_STADIUM
:House is a stadium
;HOUSE_FLAG_ONLY_SE
:Can only be built in the scenario editor
;HOUSE_FLAG_PROTECTED
:Will not be removed by the game
;HOUSE_FLAG_SYNC_CALLBACK
:Callbacks for tiles are synchronised
;HOUSE_FLAG_RANDOM_ANIMATION
:Enable random animation
|-
| population
| 0 ... 255
| number of inhabitants the building adds to the town, if present
|-
| mail_multiplier
| 0 ... 255
|
|-
| pax_acceptance
| 0 ... 1
| Can be increased in steps of 0.125. A station accepts a cargo, if the combined acceptance of all houses in range is at least 1.
|-
| mail_acceptance
| 0 ... 1
|
|-
| cargo_acceptance
| 0 ... 1
| Like passenger acceptance. Additionally flag can be added which defines one of the cargo type
;HOUSE_ACCEPT_GOODS
;HOUSE_ACCEPT_FOOD
;HOUSE_ACCEPT_FIZZY_DRINKS
:FIZZY_DRINKS has in toyland the same meaning as FOOD in other climates.
|-
| accepted_cargo
|
| up to three cargo labels, e.g. MAIL, PASS, COAL
|-
| local_authority_impact
| 0 ... 65525
| amount of happiness decrease of the city council, if the building is destroyed. Town ratings can vary between -1000 (appalling) and +1000 (outstanding).
|-
| removal_cost_multiplier
| 0 ... 255
|
|-
| probability
| 0 ... 16 (float)
| Probability with respect to the default houses (=1). Mind that these are relative probabilities with respect to all houses defined. If all probabilities are defined as 16, they'll all have the same probability as if they had all a probability of 1.
|-
| years_available
| array of two int
| [xx, yy] where xx and yy indicate the introduction year and the last year the building can be built
|-
| minimum_lifetime
| 0 ... 255
| number of years the building will remain at least
|-
| availability_mask
|
[bitmask([[NML:List of town zones|town zones]]), bitmask(CLIMATE_XXX, ...)]
|
An array with two bitmasks, the first bitmask is a mask of town zones where this house is available. The second bitmask is a mask of climates combined with the special value ABOVE_SNOWLINE which you need to set for houses available in the arctic climate above the snowline. Examples:

* Available in the centre town zone in toyland only: <code>[bitmask(TOWNZONE_CENTRE), bitmask(CLIMATE_TOYLAND)]</code>
* Available in all town zones in the arctic climate both above and below the snowline: <code>[ALL_TOWNZONES, bitmask(CLIMATE_ARCTIC, ABOVE_SNOWLINE)]</code>
* Available everywhere except on the town edge: <code>[ALL_TOWNZONES & ~bitmask(TOWNZONE_EDGE), ALL_CLIMATES | bitmask(ABOVE_SNOWLINE)</code>
|-
| callback_flags
| bitmask(HOUSE_CBF_XX)
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| random_colours
| array of 4, each COLOUR_XXX
|
colour values in an array, refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for a list of possible values.
|-
| refresh_multiplier
| 0 ... 63
| Defines the frequency with which the tile will be re-randomized which has an impact for random animation.
|-
| animation_info
| Array [ANIMATION_XXX, frame-count]
|
Type of animation and its length (1...128 frames):

;ANIMATION_LOOPING
;ANIMATION_NON_LOOPING
|-
| animation_speed
| 2 ... 16
|
Speed of animation, see [[NML:Animation speed|animation speed table]] for the meaning of the values.
|-
| building_class
| 0 .. 255
| An arbitrary number. You can check for the presence of buildings of the same class when building new buildings or using animation
|
|-
| watched_cargo_types
| array of values from your [[NML:Cargotable|cargo table]]
| {{ottdp|1.2|2.6|ottdrev=r23072|ttdprev=r1677}}List of cargo types to watch, to be used with the <code style:darkgreen>watched_cargo_accepted</code> callback.
|}

==House variables==

{| class="t"
! name
! value range
! comment
|-
| construction_state
| 0..3
| Current construction state of the industry tile
|-
| pseudo_random_bits
| 0..3
| Some pseudo-random bits, based on the tile position. TTD houses use this to randomize their appearance.
|-
| age
| 0..255
| Age of the house in years, limited to 255
|-
| town_zone
|
[[NML:List of town zones|town zone]]
| The town zone of the current tile
|-
| terrain_type
| TILETYPE_XX
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|-
| same_house_count_town
| 0..255
| Number of the houses with the same ID in the same town as this house
|-
| same_house_count_map
| 0..255
| Number of the houses with the same ID on the entire map
|-
| same_class_count_town
| 0..255
| Number of the houses with the same <code style="color:darkgreen">building_class</code> in the same town as this house
|-
| same_class_count_map
| 0..255
| Number of the houses with the same <code style="color:darkgreen">building_class</code> on the entire map
|-
| generating_town
| [0 <nowiki>|</nowiki> 1]
| 1 a random town is currently being created, 0 otherwise. Note that while generating a random town, [[NML:Towns#Town variables|town variables]] <code style="color:darkgreen">population</code> and <code style="color:darkgreen">building_count</code> are incorrect. The population variable contains the population of buildings generated ''yet'', the final value may be larger. The building_count is surely higher than the final value will be.
|-
| animation_frame
| 0..255
| Current animation frame
|-
| x_coordinate
| 0..2047
| X-coordinate (top right -> bottom left) of the tile on the map
|-
| y_coordinate
| 0..2047
| Y-coordinate (top left -> bottom right) of the tile on the map
|}

The following variables require one or more arguments
{| class="t"
! name
! arguments
! value range
! comment
|-
| old_house_count_town
| ID of old house type (0..109)
| 0..255
| Number of old houses with a given ID in the same town as the current house
|-
| old_house_count_town
| ID of old house type (0..109)
| 0..255
| Number of old houses with a given ID on the whole map
|-
| other_house_count_town
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses with a given ID in the same town as the current house
|-
| other_house_count_map
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses with a given ID on the whole map
|-
| other_class_count_town
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses, with the same class as the house with the given ID, in the same town as the current house
|-
| other_class_count_map
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses, with the same class as the house with the given ID, on the whole map
|-
| nearby_tile_slope
| x- and y-offset (both signed, range -8..7)
| SLOPE_XXX
| See [[NML:List of tile slopes|tile slopes]] for an overview of possible values
|-
| nearby_tile_is_water
| x- and y-offset (both signed, range -8..7)
| [0 <nowiki>|</nowiki> 1]
| 1 if the tile is water, 0 otherwise
|-
| nearby_tile_terrain_type
| x- and y-offset (both signed, range -8..7)
| TILETYPE_XX
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|-
| nearby_tile_water_class
| x- and y-offset (both signed, range -8..7)
| WATER_CLASS_XXX
| XXX = [NONE <nowiki>|</nowiki> SEA <nowiki>|</nowiki> CANAL <nowiki>|</nowiki> RIVER] Note that tiles for which <code style="color:darkgreen">nearby_tile_is_water</code> is 0 may still have a water class, e.g. industry tiles with water beneath them.
|-
| nearby_tile_height
| x- and y-offset (both signed, range -8..7)
| 0..255 (currently limited to 0..15)
| Height of the lowest corner of the tile. 1 unit is one height level of 8 pixels.
|-
| nearby_tile_class
| x- and y-offset (both signed, range -8..7)
|
[[NML:List of tile classes|Tile class]]
|
|-
| nearby_tile_animation_frame
| x- and y-offset (both signed, range -8..7)
| 0..255
| Animation frame of the given tile
|-
| cargo_accepted_nearby_ever
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby">Cargo type should be from your cargo translation table. X- and y-offset are optional, if provided both must be in range -128..127. A station is considered nearby if the tile is in the station's acceptance area. This is the purpose of the x- and y-offset, as other tiles may have other stations nearby.</ref>
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was ever accepted at a nearby station, 0 otherwise
|-
| cargo_accepted_nearby_last_month
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was accepted at a nearby station in the last month, 0 otherwise
|-
| cargo_accepted_nearby_this_month
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was ever accepted at a nearby station in this month, 0 otherwise
|-
| cargo_accepted_nearby_last_bigtick
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was ever accepted at a nearby station since the last periodic processing, which happens every 250 ticks. 0 otherwise
|-
| cargo_accepted_nearby_watched
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was one of the cargo types that triggered the <code style="color:darkgreen">watched_cargo_accepted</code>-callback (only during this callback), 0 otherwise
|-
| nearest_house_matching_criterion
| radius (1..63) and criterion (SEARCH_HOUSE_BY_XXX, XXX = [<nowiki>ID | CLASS | GRFID</nowiki>])
| 1..63, or 0 if not found
| Perform a circular search for a house matching either the id, <code style="color:darkgreen">building_class</code> or GRFID of this house, depending on the second parameter. The first parameter specifies the maximum search radius. Return value is the Manhattan distance of the closest matching house tile, or 0 if no match was found. Note that tiles of the originating house never match.
|-
| nearby_tile_house_id
| x- and y-offset (both signed, range -8..7)
| -1, or 0 .. 767
| Return value is -1 if the tile is not a house tile, X (0..255) if the tile contains old house type X, 256+X if the tile contains a house from this NewGRF with ID X, 512+X if the tile contains a house from a different NewGRF with ID X.
|-
| nearby_tile_house_class
| x- and y-offset (both signed, range -8..7)
| -1, 0, or 256 .. 767
| Return value is -1 if the tile is not a house tile, 0 if the house tile does not have a class (this includes all old house types), 256+X (X = 0..255) if the house has been defined by this NewGRF with <code style="color:darkgreen">building_class</code> X or 512+X if the house has been defined by a different NewGRF with <code style="color:darkgreen">building_class</code> X.
|-
| nearby_tile_house_grfid
| x- and y-offset (both signed, range -8..7)
| -1, 0 or a GRFID
| Return value is -1 if the tile is not a house tile, 0 if the house tile contains an old house type, or else the GRFID of the NewGRF defining the house.
|}
<references/>

==House callbacks==

{| class="t"
! callback
! return value
! comment
|-
| default
| Sprite layout
| Graphics for the house tile
|-
| random_trigger
| N/A
|
See [[NML:Random switch|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. <code>extra_callback_info1</code> contains random bits, if enabled in the <code>special_flags</code> property. Returning a sound effect in the high byte will cause that sound effect to be played.
|-
| anim_control
| Next animation frame or CB_RESULT_XXX
| Called every 256 ticks. 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. <code>extra_callback_info1</code> contains random bits, if enabled in the <code>building_flags</code> property. Returning a sound effect in the high byte will cause that sound effect to be played.
|-
| construction_anim
| Same as <code>anim_control</code>
| Works the same as the <code>anim_control</code> callback, except that it's called when the construction state changes.
|-
| watched_cargo_accepted
| Same as <code>anim_control</code>
| Works the same as the <code>anim_control</code> callback, except that it's called when one of the watched cargo types is accepted.
|-
| 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 <code>accepted_cargo</code> 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 the acceptance properties are used instead. Cargo types are from the <code>cargo_type_accept</code> callback, or the <code>accepted_cargo</code> 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.
|-
| cargo_production
| (cargo_type * 256) + amount
| Called every 256 ticks. Called multiple times until 0x20FF is returned. The high byte of the result contains a cargo type, the low byte contains the amount of that cargo to produce. <code>extra_callback_info1</code> contains the number of iterations so far, <code>extra_callback_info2</code> contains random bits.
|-
| 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.
|-
| name
| String
| Name of the building (when using tile query tool)
|-
| colour
| Palette number
|
Used to recolour the building. See here [[NML:List of default colour translation palettes|here]] for an overview of default palettes.
|-
| construction_check
| 0 or 1
| Return 1 to allow building the house or 0 to disallow.
|-
| destruction
| 0 or 1
| Called periodically. Return 0 to keep the building or 1 to destroy it.
|-
| protection
| 0 or 1
| Return 0 to allow destruction, or 1 to disallow
|}

NML:Houses

2012-07-31T19:06:04Z

Hirundo: /* House variables */ Add 60+x vars

{{NMLNavPropVarCB}}

==House properties==

{| class="t"
! property
! value range
! comment
|-
| name
| string
| for example string(STR_NAME_EIFFEL_TOWER)
|-
| substitute
| 0 ... 109
| Number of the default house that replaces this one, if this house 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 ... 109
| id of the default house which this house replaces. This will cause your house to be placed instead of the default house. This is ignored, if the default house has already been overridden. You can define this property multiple times
|-
| building_flags
| bitmask(HOUSE_FLAG_XXX,...)
|
;HOUSE_FLAG_SIZE_1x1
;HOUSE_FLAG_SIZE_2x1
;HOUSE_FLAG_SIZE_1x2
;HOUSE_FLAG_SIZE_2x2
;HOUSE_FLAG_NOT_SLOPED
:Can only be built on flat terrain
;HOUSE_FLAG_ANIMATE
:Enable animation
;HOUSE_FLAG_CHURCH
:House is a church
;HOUSE_FLAG_STADIUM
:House is a stadium
;HOUSE_FLAG_ONLY_SE
:Can only be built in the scenario editor
;HOUSE_FLAG_PROTECTED
:Will not be removed by the game
;HOUSE_FLAG_SYNC_CALLBACK
:Callbacks for tiles are synchronised
;HOUSE_FLAG_RANDOM_ANIMATION
:Enable random animation
|-
| population
| 0 ... 255
| number of inhabitants the building adds to the town, if present
|-
| mail_multiplier
| 0 ... 255
|
|-
| pax_acceptance
| 0 ... 1
| Can be increased in steps of 0.125. A station accepts a cargo, if the combined acceptance of all houses in range is at least 1.
|-
| mail_acceptance
| 0 ... 1
|
|-
| cargo_acceptance
| 0 ... 1
| Like passenger acceptance. Additionally flag can be added which defines one of the cargo type
;HOUSE_ACCEPT_GOODS
;HOUSE_ACCEPT_FOOD
;HOUSE_ACCEPT_FIZZY_DRINKS
:FIZZY_DRINKS has in toyland the same meaning as FOOD in other climates.
|-
| accepted_cargo
|
| up to three cargo labels, e.g. MAIL, PASS, COAL
|-
| local_authority_impact
| 0 ... 65525
| amount of happiness increase of the city council, if the building is destroyed
|-
| removal_cost_multiplier
| 0 ... 255
|
|-
| probability
| 0 ... 16 (float)
| Probability with respect to the default houses (=1). Mind that these are relative probabilities with respect to all houses defined. If all probabilities are defined as 16, they'll all have the same probability as if they had all a probability of 1.
|-
| years_available
| array of two int
| [xx, yy] where xx and yy indicate the introduction year and the last year the building can be built
|-
| minimum_lifetime
| 0 ... 255
| number of years the building will remain at least
|-
| availability_mask
|
[bitmask([[NML:List of town zones|town zones]]), bitmask(CLIMATE_XXX, ...)]
|
An array with two bitmasks, the first bitmask is a mask of town zones where this house is available. The second bitmask is a mask of climates combined with the special value ABOVE_SNOWLINE which you need to set for houses available in the arctic climate above the snowline. Examples:

* Available in the centre town zone in toyland only: <code>[bitmask(TOWNZONE_CENTRE), bitmask(CLIMATE_TOYLAND)]</code>
* Available in all town zones in the arctic climate both above and below the snowline: <code>[ALL_TOWNZONES, bitmask(CLIMATE_ARCTIC, ABOVE_SNOWLINE)]</code>
* Available everywhere except on the town edge: <code>[ALL_TOWNZONES & ~bitmask(TOWNZONE_EDGE), ALL_CLIMATES | bitmask(ABOVE_SNOWLINE)</code>
|-
| callback_flags
| bitmask(HOUSE_CBF_XX)
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| random_colours
| array of 4, each COLOUR_XXX
|
colour values in an array, refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for a list of possible values.
|-
| refresh_multiplier
| 0 ... 63
| Defines the frequency with which the tile will be re-randomized which has an impact for random animation.
|-
| animation_info
| Array [ANIMATION_XXX, frame-count]
|
Type of animation and its length (1...128 frames):

;ANIMATION_LOOPING
;ANIMATION_NON_LOOPING
|-
| animation_speed
| 2 ... 16
|
Speed of animation, see [[NML:Animation speed|animation speed table]] for the meaning of the values.
|-
| building_class
| 0 .. 255
| An arbitrary number. You can check for the presence of buildings of the same class when building new buildings or using animation
|
|-
| watched_cargo_types
| array of values from your [[NML:Cargotable|cargo table]]
| {{ottdp|1.2|2.6|ottdrev=r23072|ttdprev=r1677}}List of cargo types to watch, to be used with the <code style:darkgreen>watched_cargo_accepted</code> callback.
|}
==House variables==

{| class="t"
! name
! value range
! comment
|-
| construction_state
| 0..3
| Current construction state of the industry tile
|-
| pseudo_random_bits
| 0..3
| Some pseudo-random bits, based on the tile position. TTD houses use this to randomize their appearance.
|-
| age
| 0..255
| Age of the house in years, limited to 255
|-
| town_zone
|
[[NML:List of town zones|town zone]]
| The town zone of the current tile
|-
| terrain_type
| TILETYPE_XX
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|-
| same_house_count_town
| 0..255
| Number of the houses with the same ID in the same town as this house
|-
| same_house_count_map
| 0..255
| Number of the houses with the same ID on the entire map
|-
| same_class_count_town
| 0..255
| Number of the houses with the same <code style="color:darkgreen">building_class</code> in the same town as this house
|-
| same_class_count_map
| 0..255
| Number of the houses with the same <code style="color:darkgreen">building_class</code> on the entire map
|-
| generating_town
| [0 <nowiki>|</nowiki> 1]
| 1 a random town is currently being created, 0 otherwise. Note that while generating a random town, [[NML:Towns#Town variables|town variables]] <code style="color:darkgreen">population</code> and <code style="color:darkgreen">building_count</code> are incorrect. The population variable contains the population of buildings generated ''yet'', the final value may be larger. The building_count is surely higher than the final value will be.
|-
| animation_frame
| 0..255
| Current animation frame
|-
| x_coordinate
| 0..2047
| X-coordinate (top right -> bottom left) of the tile on the map
|-
| y_coordinate
| 0..2047
| Y-coordinate (top left -> bottom right) of the tile on the map
|}

The following variables require one or more arguments
{| class="t"
! name
! arguments
! value range
! comment
|-
| old_house_count_town
| ID of old house type (0..109)
| 0..255
| Number of old houses with a given ID in the same town as the current house
|-
| old_house_count_town
| ID of old house type (0..109)
| 0..255
| Number of old houses with a given ID on the whole map
|-
| other_house_count_town
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses with a given ID in the same town as the current house
|-
| other_house_count_map
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses with a given ID on the whole map
|-
| other_class_count_town
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses, with the same class as the house with the given ID, in the same town as the current house
|-
| other_class_count_map
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses, with the same class as the house with the given ID, on the whole map
|-
| nearby_tile_slope
| x- and y-offset (both signed, range -8..7)
| SLOPE_XXX
| See [[NML:List of tile slopes|tile slopes]] for an overview of possible values
|-
| nearby_tile_is_water
| x- and y-offset (both signed, range -8..7)
| [0 <nowiki>|</nowiki> 1]
| 1 if the tile is water, 0 otherwise
|-
| nearby_tile_terrain_type
| x- and y-offset (both signed, range -8..7)
| TILETYPE_XX
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|-
| nearby_tile_water_class
| x- and y-offset (both signed, range -8..7)
| WATER_CLASS_XXX
| XXX = [NONE <nowiki>|</nowiki> SEA <nowiki>|</nowiki> CANAL <nowiki>|</nowiki> RIVER] Note that tiles for which <code style="color:darkgreen">nearby_tile_is_water</code> is 0 may still have a water class, e.g. industry tiles with water beneath them.
|-
| nearby_tile_height
| x- and y-offset (both signed, range -8..7)
| 0..255 (currently limited to 0..15)
| Height of the lowest corner of the tile. 1 unit is one height level of 8 pixels.
|-
| nearby_tile_class
| x- and y-offset (both signed, range -8..7)
|
[[NML:List of tile classes|Tile class]]
|
|-
| nearby_tile_animation_frame
| x- and y-offset (both signed, range -8..7)
| 0..255
| Animation frame of the given tile
|-
| cargo_accepted_nearby_ever
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby">Cargo type should be from your cargo translation table. X- and y-offset are optional, if provided both must be in range -128..127. A station is considered nearby if the tile is in the station's acceptance area. This is the purpose of the x- and y-offset, as other tiles may have other stations nearby.</ref>
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was ever accepted at a nearby station, 0 otherwise
|-
| cargo_accepted_nearby_last_month
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was accepted at a nearby station in the last month, 0 otherwise
|-
| cargo_accepted_nearby_this_month
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was ever accepted at a nearby station in this month, 0 otherwise
|-
| cargo_accepted_nearby_last_bigtick
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was ever accepted at a nearby station since the last periodic processing, which happens every 250 ticks. 0 otherwise
|-
| cargo_accepted_nearby_watched
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was one of the cargo types that triggered the <code style="color:darkgreen">watched_cargo_accepted</code>-callback (only during this callback), 0 otherwise
|-
| nearest_house_matching_criterion
| radius (1..63) and criterion (SEARCH_HOUSE_BY_XXX, XXX = [<nowiki>ID | CLASS | GRFID</nowiki>])
| 1..63, or 0 if not found
| Perform a circular search for a house matching either the id, <code style="color:darkgreen">building_class</code> or GRFID of this house, depending on the second parameter. The first parameter specifies the maximum search radius. Return value is the Manhattan distance of the closest matching house tile, or 0 if no match was found. Note that tiles of the originating house never match.
|-
| nearby_tile_house_id
| x- and y-offset (both signed, range -8..7)
| -1, or 0 .. 767
| Return value is -1 if the tile is not a house tile, X (0..255) if the tile contains old house type X, 256+X if the tile contains a house from this NewGRF with ID X, 512+X if the tile contains a house from a different NewGRF with ID X.
|-
| nearby_tile_house_class
| x- and y-offset (both signed, range -8..7)
| -1, 0, or 256 .. 767
| Return value is -1 if the tile is not a house tile, 0 if the house tile does not have a class (this includes all old house types), 256+X (X = 0..255) if the house has been defined by this NewGRF with <code style="color:darkgreen">building_class</code> X or 512+X if the house has been defined by a different NewGRF with <code style="color:darkgreen">building_class</code> X.
|-
| nearby_tile_house_grfid
| x- and y-offset (both signed, range -8..7)
| -1, 0 or a GRFID
| Return value is -1 if the tile is not a house tile, 0 if the house tile contains an old house type, or else the GRFID of the NewGRF defining the house.
|}
<references/>

==House callbacks==

{| class="t"
! callback
! return value
! comment
|-
| default
| Sprite layout
| Graphics for the house tile
|-
| random_trigger
| N/A
|
See [[NML:Random switch|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. <code>extra_callback_info1</code> contains random bits, if enabled in the <code>special_flags</code> property. Returning a sound effect in the high byte will cause that sound effect to be played.
|-
| anim_control
| Next animation frame or CB_RESULT_XXX
| Called every 256 ticks. 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. <code>extra_callback_info1</code> contains random bits, if enabled in the <code>building_flags</code> property. Returning a sound effect in the high byte will cause that sound effect to be played.
|-
| construction_anim
| Same as <code>anim_control</code>
| Works the same as the <code>anim_control</code> callback, except that it's called when the construction state changes.
|-
| watched_cargo_accepted
| Same as <code>anim_control</code>
| Works the same as the <code>anim_control</code> callback, except that it's called when one of the watched cargo types is accepted.
|-
| 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 <code>accepted_cargo</code> 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 the acceptance properties are used instead. Cargo types are from the <code>cargo_type_accept</code> callback, or the <code>accepted_cargo</code> 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.
|-
| cargo_production
| (cargo_type * 256) + amount
| Called every 256 ticks. Called multiple times until 0x20FF is returned. The high byte of the result contains a cargo type, the low byte contains the amount of that cargo to produce. <code>extra_callback_info1</code> contains the number of iterations so far, <code>extra_callback_info2</code> contains random bits.
|-
| 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.
|-
| name
| String
| Name of the building (when using tile query tool)
|-
| colour
| Palette number
|
Used to recolour the building. See here [[NML:List of default colour translation palettes|here]] for an overview of default palettes.
|-
| construction_check
| 0 or 1
| Return 1 to allow building the house or 0 to disallow.
|-
| destruction
| 0 or 1
| Called periodically. Return 0 to keep the building or 1 to destroy it.
|-
| protection
| 0 or 1
| Return 0 to allow destruction, or 1 to disallow
|}

NML:Houses

2012-07-31T17:22:07Z

Hirundo: /* House variables */ Add information about 40+x vars

VariationalAction2/Houses

2012-07-31T12:03:02Z

Hirundo: /* Current animation frame (46) */ Don't confuse variables and properties

==Introduction==

== Variables ==

{| |-
!Variable!![[GRFActionsDetailed|'''Size''']]!!Version*!!Description
|-
|40||B||{{ottdp|0.6|2.5}}||Construction stage and pseudo-random values
|-
|41||B||{{ottdp|0.6|2.5}}||Age of the building in years (or, strictly speaking, the difference between the current year and the year the building was built). Returns 255 for buildings older than 255 years.
|-
|42||B||{{ottdp|0.6|2.5|ttdprev=alpha 43}}||Town zone where the building is situated.
|-
|43||B||{{ottdp|0.6|2.5}}||Terrain type: 0 normal, 1 desert, 2 rainforest, 4 on or above snowline
|-
|44||D||{{ottdp|0.6|2.5|ttdprev=alpha 43}}||Building counts
|-
|45||B||{{ottdp|0.6|2.5|ttdprev=alpha 38}}||Town expansion bits
|-
|46||B||{{ottdp|0.6|2.5|ttdprev=alpha 67}}||Current animation frame
|-
|47||D||{{ottdp|0.7|2.6|ottdrev=r14294|ttdprev=r2020}}||XY Coordinate of the building
|-
|60||D||{{ottdp|0.6|2.5|ttdprev=alpha 56}}||Other building counts
|-
|61||D||{{ottdp|0.6|2.5|ttdprev=alpha 56}}||Other building counts
|-
|62||D||{{ottdp|0.6|2.5|ttdprev=alpha 72}}||Land info for nearby tiles
|-
|63||B||{{ottdp|0.7|2.6|ttdprev=r1665}}||Current animation frame of nearby house tiles
|-
|64||B||{{ottdp|1.2|2.6|ottdrev=r23070|ttdprev=r1672}}||Cargo acceptance history of nearby stations
|-
|65||B||{{ottdp|0.7|2.6|ottdrev=r13603|ttdprev=r2242}}||Distance of nearest house matching a given criterion
|-
|66||D||{{ottdp|1.0|2.6|ttdprev=r2246}}||Class and ID of nearby house tile
|-
|67||D||{{ottdp|1.0|2.6|ttdprev=r2246}}||GRFID of nearby house tile
|-
|80+x||||||None defined, and none ever will because town buildings don't have an internal structure. Trying to access these variables crashes TTD.
|}

<nowiki>*</nowiki> Specified version is earliest known to support the variable in its current form. Some variables may have been available earlier.

== Description ==

=== Construction stage and pseudo-random values (40) ===

{| |-
!Bits!!Meaning
|-
|0..1||Construction state: 0..2: various states of construction, 3: construction finished
|-
|2..3||A pseudo-random value. It isn't actually random, but is derived from the position of the building. Old buildings use this value to randomize their colors. TTDPatch has a better way to randomize things, but you can still use that value to mimic unpatched TTD behaviour. Note that adjacent tiles aren't guaranteed to have the same pseudo-random bits
|}

=== Town zone (42) ===

Town zone where the building is situated. The value is between 0 and 4, where 0 is the outermost zone of the town. Smaller towns have fewer zones. Roads are plain in zone 0 and 1, paved in zone 2, have trees in zone 3 and streetlights in zone 4

=== Building counts (44) ===

Returns dword LLllCCcc, where cc means how many buildings of the current type can be found in the current town, while CC is the same for the whole map. ll and LL are similar to cc and CC, but contain the number of tiles that have the same class as the current one. For tiles that have no class, ll and LL are always zero. Overridden old types are considered to be the new type they were overridden with. During [[Callbacks#House construction check (17)|callback 17]], the current building isn't on the map yet, and therefore isn't counted. In other cases, the building count is at least one, since the current building is counted as well.

=== Town expansion bits (45) ===

{| |-
!Bit!!Value!!Meaning
|-
|0||1||Set if TTD is currently creating a random town, clear otherwise. PLEASE NOTE: while TTD is generating a random town, town variables 82 (town population) and B6 (number of buildings) are incorrect. The population counter contains the population of buildings generated _yet_, which means the final value may be larger than you get. The building count variable, on the other hand, is surely higher than the final value will be. If you want to check these variables during [[Callbacks#House construction check (17)|callback 17]], you may need to check variable 45 as well and make adjustments if this bit is set.
|}

Other bits are currently reserved for future use.

=== Current animation frame (46) ===

The current animation frame being displayed. If you don't use animation callbacks, it's between zero and the value set in property 1A. Animation callbacks can set this to anything between 0 and 127.

Enabling animation on a house tile by setting properties 9, 1A and probably 1B ensures that variable 46 will indeed change with time, and the building is redrawn every time variable 46 changes. This means that you can use a VarAction2 to choose the current frame according to variable 46. Please note that this kind of animation needs more CPU time and more sprites, so you should prefer palette animation if possible.

=== XY Coordinate of the building (47) ===

The coordinate of the tile this part of the building is located.  If the building is not yet constructed, like during [[Callbacks#House construction check (17)|callback 17]], the returned value will be the proposed location.  The format of the var is YYYYXXXX.

=== Other building counts (60, 61) ===

For variable 60, the parameter is an old house type number. For variable 61, it is a new house type number defined in the current GRF file.

These variables work like variable 44, but they count the given house type instead of the current one.

Please note that, unlike random graphics, changes of deterministic building graphics don't automatically redraw the building (except when either the construction state or property 46 changes), resulting in temporary graphics glitches when a visible building changes its graphics. These glitches can be fixed by scrolling the building out of view, then back again.

=== Land info for nearby tiles (62) ===

This variable works exactly like [[VarAction2IndustryTiles#Land info of nearby tiles 60|var. 60 for industry tiles]], except that bit 0 of the '''bb''' part is undefined.

=== Current animation frame of nearby house tiles (63) ===

The parameter of this variable is an offset from the position of the current tile. The low nibble contains the signed X offset (that is 0h=0, 1h=+1 ... 7h=+7; 8h=-8, 9h=-7 ... Fh=-1), the high nibble contains the Y offset. Although you can query a 16x16 area with these parameters, it's currently useless to use offsets other than -1, 0 and +1; if you query a tile that doesn't belong to the same building as the current tile, the result is meaningless. It may even be junk if the queried tile isn't a house tile at all.

=== Cargo acceptance history of nearby stations (64) ===

The parameter of this variable is a cargo identifier. {{grfFrom|7}} If your GRF is version 7 or later and has a cargo translation table, this is an index to that table; otherwise, it's a cargo slot number. Additionally, GRF register 100h should contain an offset relative to the current tile (use 0 for the current tile). The lowest byte contains the signed X offset and the next higher byte the signed Y offset.

The returned value looks like this:

{| |-
!Bit number!!Meaning
|-
|0||This cargo was accepted in a nearby station some time in the past
|-
|1||This cargo was accepted in a nearby station last month
|-
|2||This cargo was accepted in a nearby station this month
|-
|3||This cargo was accepted in a nearby station since the last periodic processing (which happens every 250 ticks)
|-
|4||This cargo is one of the types that triggered [[Callbacks#Watched_cargo_accepted_.28148.29|callback 148]] (only during callback 148)
|-
|other bits||undefined; reserved for future use
|}

A station is considered nearby if the selected tile is inside its acceptance area. That's why you can give an offset - other tiles of your multi-tile building may have different stations "nearby".

{{ttdp|}} The information required for this variable is stored in the station2 structure, and therefore works only if the station2 structure is present. The station2 structure is present if any of the following is true:
* Generalfixes is on, and miscmods.noextendstationrange is off
* Any of fifoloading, newcargos or irregularstations is on

If the station2 structure isn't present, the returned value is always zero.

=== Distance of nearest house matching a given criterion (65) ===

This will perform a circular search around the current tile, trying to find another house tile that will match the same type, class or GRFID. (Note: other tiles of the originating house will not match.)  Search result will be the [http://en.wikipedia.org/wiki/Taxicab_geometry Manhattan distance] between both tiles or 0, if no house tile matching the given criteria has been found.

The parameter of this variable is composed of two parts:

Bits 0..5 indicate the radius of the search going to be performed (given in Manhattan metric). Maximum search radius is 63 while the minimum is 1. A radius of 0 is considered reserved - do not use.

Bits 6..7 indicate the type of search to be carried out:

0 : Search by house type as defined in the grf file

1 : Search by building class

2 : Search by GRFID

Just like other search variables, be aware that this is a CPU intensive one

=== Class and ID of nearby house tile (66) ===

The parameter of this variable is an offset from the position of the current tile. The low nibble contains the signed X offset (that is 0h=0, 1h=+1 ... 7h=+7; 8h=-8, 9h=-7 ... Fh=-1), the high nibble contains the Y offset. The returned value is structured like this:

{| |-
!High word!!Information about house class
|-
|||'''FFFFh''' if the selected tile isn't a house tile
|-
|||'''0000h''' if the selected house doesn't have a class specified (including old houses, which cannot have a class)
|-
|||'''01XXh''' if the selected house has been defined in the current GRF with class XX
|-
|||'''02XXh''' if the selected house has been defined in a different GRF with class XX
|-
!Low word!!Information about house ID
|-
|||'''FFFFh''' if the selected tile isn't a house tile
|-
|||'''00XXh''' if the selected house is old house type XX
|-
|||'''01XXh''' if the selected house has been defined in the current GRF with ID XX
|-
|||'''02XXh''' if the selected house has been defined in a different GRF with ID XX
|}

In case the selected house comes from another GRF, you need to use variable 67 (see below) to find out the corresponding GRFID and identify the exact type of the house. Please note that variable 67 is cheaper to calculate than this one, so if you are looking for a specific GRFID/houseID combination, you should try matching the GRFID first, and get variable 66 only if the GRFID matches.

=== GRFID of nearby house tile (67) ===

The parameter of this variable is an offset from the position of the current tile. The low nibble contains the signed X offset (that is 0h=0, 1h=+1 ... 7h=+7; 8h=-8, 9h=-7 ... Fh=-1), the high nibble contains the Y offset. The returned value is one of the following:
* '''FFFFFFFFh''' if the selected tile isn't a house tile
* '''00000000h''' if the selected house is an old house type
* otherwise, the GRFID of the GRF which defined the type of the selected house

==Example==

NML:Vehicles

2012-07-29T20:28:18Z

Hirundo: /* Vehicle variables */

{{NMLNavPropVarCB}}

==Properties common to all vehicle types==

{| class="t"
! property
! value range
! available for articulated vehicle
! comment
|-
| <code style="color:green">name</code>
| (string)
| yes
| for example <code style="color:darkgreen">string(STR_NAME_HEREFORD_TRAM)</code>
|-
| <code style="color:green">climates_available</code>
| bitmask(CLIMATE_XXX, CLIMATE_YYY, ...)
| set to <code style="color:green">NO_CLIMATE</code>
|
;CLIMATE_TEMPERATE
;CLIMATE_ARCTIC
;CLIMATE_TROPICAL
;CLIMATE_TOYLAND
;NO_CLIMATE
:Vehicle is availble in no climate (e.g. for articulated parts)
;ALL_CLIMATES
:Vehicle is available irrespective of climate

To make a vehicle available in all climates except toyland you could use: <code style="color:green">ALL_CLIMATES & ~bitmask(CLIMATE_TOYLAND)</code>.
|-
| <code style="color:green">introduction_date</code>
| <code style="color:green">date</code>(yyyy,mm,dd)
| no
| Valid range for yyyy is 0 ... 5000000. In TTDPatch, dates after 2044 will be limited to 2044. Unless the engine is introduced within two years after game-start (always 1920 in TTDPatch), a random number of days between 0 and 511 will be added to this.
|-
| <code style="color:green">model_life</code>
| 0 ... 254 (years) or <code style="color:green">VEHICLE_NEVER_EXPIRES</code>
| no
|
Number of years a model is "supported" by the manufacturer, see [[#Engine life cycle|below]].
|-
| <code style="color:green">retire_early</code>
| -128 ... 127 (years)
| no
|
Retire the vehicle (make it unavailable in the purchase menu) this many years before reliability starts dropping, see [[#Engine life cycle|below]]. May be negative.
|-
| <code style="color:green">vehicle_life</code>
| 0 ... 255 (years)
| no
| Life length of an individual vehicle, before it is considered too old and in need of replacement.
|-
| <code style="color:green">reliability_decay</code>
| 0 ... 255
| no
| Default vehicles use 20. The higher the value the faster reliability decays, the more frequent service is needed. 0 means reliability never decreases if the vehicle is not too old
|-
| <code style="color:green">refittable_cargo_classes</code>
|
bit set of [[NML:Cargos#Cargo classes|cargo classes]]
| yes
| for example: <code style="color:darkgreen">bitmask(CC_BULK, CC_COVERED)</code>
|-
| <code style="color:green">non_refittable_cargo_classes</code>
|
bit set of [[NML:Cargos#Cargo classes|cargo classes]]
| yes
| for example: <code style="color:darkgreen">bitmask(CC_OVERSIZED, CC_SPECIAL)</code>
|-
| <code style="color:green">refittable_cargo_types</code>
| bit mask of entries into the cargo translation table
| yes
| As of NML 0.3, do not use this. Use cargo_[dis]allow_refit (see below) instead.
|-
| <code style="color:green">cargo_allow_refit</code>
| Array of cargo labels from the [[NML:Cargotable|cargotable]]
| Yes
| {{ottdp|1.2|no|ottdrev=r23291}} A list of cargo types to allow refitting to, irrespective of cargo classes. Example: <code style="color:darkgreen">[COAL, IORE]</code>
|-
| <code style="color:green">cargo_disallow_refit</code>
| Array of cargo labels from the [[NML:Cargotable|cargotable]]
| Yes
| {{ottdp|1.2|no|ottdrev=r23291}} A list of cargo types to disallow refitting to, irrespective of cargo classes. Example: <code style="color:darkgreen">[MAIL]</code>
|-
| <code style="color:green">loading_speed</code>
| 0 ... 255 (cargo units)
| yes
| Units of cargo loaded per time unit. Default vehicles use 5 for trains and road vehicles, 10 for ships and 20 for aircraft. This amount of cargo is loaded to or unloaded from the vehicle every 40 ticks for trains, every 20 ticks for road vehicles and aircraft and every 10 ticks for ships.
|-
| <code style="color:green">cost_factor</code>
| 0 ... 255
| Set to 0
| multiplier to the base purchase cost
|-
| <code style="color:green">running_cost_factor</code>
| 0 ... 255
| Set to 0
| multiplier to the base running costs
|-
| <code style="color:green">cargo_age_period</code>
| 0 ... 65535
| yes
|
{{ottd|1.2|r22713}} This property specifies after how many ticks cargo is aged. Default value is 185. 74 ticks is equal to 1 day.
|}

===Refittability===

To determine whether your vehicle can be refitted to a certain cargo, OpenTTD uses the following table

{| class="t"
! Cargo matches refittable_cargo_classes
! Cargo matches non_refittable_cargo_classes
! Cargo in cargo_allow_refit
! Cargo in cargo_disallow_refit
! Result
|-
| Yes
| No
| Doesn't matter
| No
| Refittable
|-
| No
| Doesn't matter
| No
| Doesn't matter
| Not refittable
|-
| Doesn't matter
| Doesn't matter
| Yes
| No
| Refittable
|-
| Doesn't matter
| Doesn't matter
| Doesn't matter
| Yes
| Not refittable
|}

For those that prefer boolean logic, the formula is as follows:

refittable = ((cargo classes in refittable_cargo_classes AND NOT cargo classes in non_refittable_cargo_classes) OR cargo in cargo_allow_refit) AND NOT (cargo in cargo_disallow_refit)

In general, you should use refittable_cargo_classes and non_refittable_cargo_classes to decide to which cargos your vehicle is refittable, and only then use cargo_allow_refit and cargo_disallow_refit to allow/disallow specific cargos.

===Engine life cycle===

The life cycle of a vehicle model consists of three phases, as outlined in the following table.

{| class="t"
! phase
! duration
! reliability
|-
| 1
| 7 to 38 months
| increases from 48-73% to 75-100%
|-
| 2
| <code style="color:darkgreen">model_life</code> - 8 years
| stays constant at peak, 75-100%
|-
| 3
| 10 to 20.5 years
| decreases from peak to 25-50%
|}

If <code style="color:darkgreen">model_life</code> is set to <code style="color:darkgreen">VEHICLE_NEVER_EXPIRES</code>, the engine remains in phase 2 forever.

Normally, the vehicle is removed from the purchase menu at the and of phase 3. However if you set the <code style="color:darkgreen">retire_early</code> property, it will be retired this many years before (or after, if the value is negative) the end of phase 2.

==Sorting vehicles in the purchase list==
This is a special property that is not encoded in an item/property-block like most other properties but it has it's own block instead. The syntax is as follows:

sort(<feature>, [<ID>, <ID>, <ID>...]);

The engines will be sorted in the given order on the position where originally the first element was. Say the original engine sorting is this: A B C D E and you use this code <code style="color:darkgreen">sort(FEAT_TRAINS, [D, B, A]);</code> the final sorting will be this: C D B A E

==Train properties==

{| class="t"
! property
! value range
! available for articulated vehicle
! comment
|-
| <code style="color:green">sprite_id</code>
| <code style="color:green">SPRITE_ID_NEW_TRAIN</code>
| yes
| Set this property to enable new graphics
|-
| <code style="color:green">speed</code>
| 0 ... 65000 (float, speed units)
| no
| Max speed for engines, speed limit for wagons
|-
| <code style="color:green">misc_flags</code>
| bitmask(TRAIN_FLAG_XXX, ...)
| FLIP should not be set, TILT and MU TO the same value as the 1st part
|
;TRAIN_FLAG_TILT
: enable the tilt bonus (20% speed in curves, if all vehicles in consist have it set)
;TRAIN_FLAG_2CC
:Enable use of the 2nd company colour
;TRAIN_FLAG_MU
:act as multiple unit (used for livery selection only)
;TRAIN_FLAG_FLIP
:Allow vehicle to be flipped (reversed) in depot
;TRAIN_FLAG_AUTOREFIT
:Allow autoreffitting. To enable autorefit, furthermore the [[#Vehicle callbacks|refit_cost]]-callback has to allow it, or else (if this callback is not implemented or fails) the <code style="color:green">refit_cost</code>-property (see below) must be set to 0.
;TRAIN_FLAG_NO_BREAKDOWN_SMOKE
:{{nml|0.3}} {{ottdp|1.3|no|ottdrev=r24124}} Disable breakdown smoke effect
|-
| <code style="color:green">refit_cost</code>
| 0 ... 255
| yes
| in 50% units of the purchase price cost base
|-
| <code style="color:green">callback_flags</code>
| bitmask(VEH_CBF_XXX, ...)
| yes
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| <code style="color:green">track_type</code>
| item from railtypetable
| must be the same as front
| Default railtype table: RAIL, MONO, MGLV. If you install a railtypetable yourself you'll always get the railtype you specified. If you want a vehicle to run on electric rail and you don't have a railtypetable, set <code style="color:green">track_type</code> to RAIL and make sure that you set <code style="color:green">engine_class</code> to <code style="color:green">ENGINE_CLASS_ELECTRIC</code>.
|-
| <code style="color:green">ai_special_flag</code>
| [<code style="color:green">AI_FLAG_PASSENGER</code> <nowiki>|</nowiki> <code style="color:green">AI_FLAG_CARGO</code>]
| no
|
;<code style="color:green">AI_FLAG_PASSENGER</code>
:Tell computer players that it's an engine that should only be used for passenger service.
|-
| <code style="color:green">power</code>
| 0 ... 65000 hp (float, power units)
| Set to 0
|
|-
| <code style="color:green">running_cost_base</code>
| RUNNING_COST_XXX
| Set to RUNNING_COST_NONE
|
;RUNNING_COST_STEAM
;RUNNING_COST_DIESEL
;RUNNING_COST_ELECTRIC
;RUNNING_COST_ROADVEH
;RUNNING_COST_NONE
:no running costs
|-
| <code style="color:green">dual_headed</code>
| [0 <nowiki>|</nowiki> 1]
| Set to 0 for all parts of an articulated vehicle
| 1 = dual_headed, otherwise normal engine
|-
| <code style="color:green">default_cargo_type</code>
| An identifier from the [[NML:Cargotable|cargo table]], or DEFAULT_CARGO_FIRST_REFITTABLE
| Yes
| If the vehicle is refittable to at least one cargo, but the chosen default cargo is not available or is set to DEFAULT_CARGO_FIRST_REFITTABLE, then the first refittable cargo is used. The first refittable is chosen according to the order in your [[NML:Cargotable|cargo table]]. If this property is set to a valid cargo but the vehicle cannot refit to any cargo type, then the vehicle will be able to carry only this cargo, but it cannot be refitted (like e.g. the default train wagons).
|-
| <code style="color:green">cargo_capacity</code>
| 0 .. 255
| yes
| By default, passenger capacity is 4x, and mail/goods capacity 2x larger than capacity for other cargoes. The capacity set here is used for the default (i.e. first refittable) cargo. Use the <code style="color:green">cargo_capacity</code> callback to avoid this effect.
|-
| <code style="color:green">weight</code>
| 0 .. 1279 ton (float, mass units)
| Set to 0
|
|-
| <code style="color:green">ai_engine_rank</code>
| 0 ... 255
| no
| TTDPatch only: Higher values make the engine for the TTDPatch AI more attractive
|-
| <code style="color:green">engine_class</code>
| ENGINE_CLASS_XXX
| no
|
Defines which livery colour settings apply to the vehicle
;ENGINE_CLASS_STEAM
;ENGINE_CLASS_DIESEL
;ENGINE_CLASS_ELECTRIC
;ENGINE_CLASS_MONORAIL
;ENGINE_CLASS_MAGLEV
|-
| <code style="color:green">extra_power_per_wagon</code>
| 0 ... 65000 hp (float, power units)
| Set to 0
| Only wagons with a livery override for this engine will add power
|-
| <code style="color:green">tractive_effort_coefficient</code>
| 0 ... 1 (float)
| Set to 0
| Fraction of the vehicle weight that is available as tractive effort. Tractive effort (in kN) is calculated as (TE coefficient) * 10 * weight (in tons), with 10 being an approximation of the acceleration of gravity (9.81 m/s). Default value is 0.3.
|-
| <code style="color:green">air_drag_coefficient</code>
| 0 ... 1 (float)
| Set to 0
| Coefficient of the relative air drag, in arbitrary units. The default value is approximately (8 / max_speed), with max_speed in km/h, clamped to the range 0.004 .. 0.75.
|-
| <code style="color:green">length</code>
| 1 ... 8
| yes
| Length of the vehicle in arbitrary units. Use a value of 8 (equal to the predefined constant VEHICLE_LENGTH) for a full-length vehicle.
|-
| <code style="color:green">visual_effect_and_powered</code>
| <code style="color:green">visual_effect_and_powered</code> (VISUAL_EFFECT_XXX, offset, <code style="color:green">ENABLE_WAGON_POWER</code> or <code style="color:green">DISABLE_WAGON_POWER</code>)
| yes
|
Set the type of visual effect for the vehicle and its positional offset with respect to the vehicle. An offset of 0 is default, negative values mean more to the front and positive values are backwards. Minimum offset is -8, maximum is 7.

;VISUAL_EFFECT_DEFAULT
:No effect, unless for the default vehicles
;VISUAL_EFFECT_STEAM
:Steam like from steam engine
;VISUAL_EFFECT_DIESEL
:Steam from internal combustion engine
;VISUAL_EFFECT_ELECTRIC
:Electric sparks
;VISUAL_EFFECT_DISABLE
:No effect
|-
| <code style="color:green">extra_weight_per_wagon</code>
| 0 ... 255 ton (float, mass units)
| Set to 0
| Adds extra weight for powered wagons, see <code style="color:green">extra_power_per_wagon</code>
|-
| <code style="color:green">bitmask_vehicle_info</code>
| 8-bit bitmask
| yes
|
Used for obtaining [[#bitmask consist info|<code style="color:green">bitmask_consist_info</code>]]
|}

==Road vehicle properties==

{| class="t"
! property
! value range
! available for articulated vehicle
! comment
|-
| sprite_id
| SPRITE_ID_NEW_ROADVEH
| yes
| Set this property to enable new graphics
|-
| speed
| 0 ... 514km/h (float, speed units)
| no
|
|-
| misc_flags
| bitmask(ROADVEH_FLAG_XXX, ...)
| partly; tram flag must the same
|
;ROADVEH_FLAG_TRAM
:The vehicle requires tram tracks to run on
;ROADVEH_FLAG_2CC
:Enable 2nd company colour
;ROADVEH_FLAG_AUTOREFIT
:Allow autorefitting. To enable autorefit, furthermore the [[#Vehicle callbacks|refit_cost]]-callback has to allow it, or else (if this callback is not implemented or fails) the <code style="color:green">refit_cost</code>-property (see below) must be set to 0.
;ROADVEH_FLAG_NO_BREAKDOWN_SMOKE
:{{nml|0.3}} {{ottdp|1.3|no|ottdrev=r24124}} Disable breakdown smoke effect
|-
| refit_cost
| 0 ... 255
| yes
| in 25% units of the purchase price cost base
|-
| callback_flags
| bitmask(VEH_CBF_XXX, ...)
| yes
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| running_cost_base
| RUNNING_COST_XXX
| set to RUNNING_COST_NONE
|
;RUNNING_COST_STEAM
;RUNNING_COST_DIESEL
;RUNNING_COST_ELECTRIC
;RUNNING_COST_ROADVEH
;RUNNING_COST_NONE
:no running costs
|-
| power
| 0 ... 2550hp (float, power units)
| Set to 0
|
|-
| weight
| 0 ... 63.75ton (float, mass units)
| Set to 0
|
|-
| tractive_effort_coefficient
| 0 ... 1 (float)
| Set to 0
| Fraction of the vehicle weight that is available as tractive effort. Tractive effort (in kN) is calculated as (TE coefficient) * 10 * weight (in tons), with 10 being an approximation of the acceleration of gravity (9.81 m/s). Default value is 0.3.
|-
| air_drag_coefficient
| 0 ... 1 (float)
| Set to 0
| Coefficient of the relative air drag, in arbitrary units. The default value is approximately (8 / max_speed), with max_speed in km/h, clamped to the range 0.004 .. 0.75.
|-
| <code style="color:green">default_cargo_type</code>
| An identifier from the [[NML:Cargotable|cargo table]], or DEFAULT_CARGO_FIRST_REFITTABLE
| Yes
| If the vehicle is refittable to at least one cargo, but the chosen default cargo is not available or is set to DEFAULT_CARGO_FIRST_REFITTABLE, then the first refittable cargo is used. The first refittable is chosen according to the order in your [[NML:Cargotable|cargo table]]. If this property is set to a valid cargo but the vehicle cannot refit to any cargo type, then the vehicle will be able to carry only this cargo, but it cannot be refitted (like e.g. the default train wagons).
|-
| cargo_capacity
| 0 ... 255
| yes
| By default, passenger capacity is 4x, and mail/goods capacity 2x larger than capacity for other cargoes. The capacity set here is used for the default (i.e. first refittable) cargo. Use the <code style="color:green">cargo_capacity</code> callback to avoid this effect.
|-
| sound_effect
| SOUND_XXX
| no
|
See available [[NML:List of sound effects|sound effects]].
|-
| visual_effect
| visual_effect( VISUAL_EFFECT_XXX, offset)
| yes
|
Set the type of visual effect for the vehicle and its positional offset with respect to the vehicle. An offset of 0 is default, negative values mean more to the front and positive values are backwards. Minimum offset is -8, maximum is 7.

;VISUAL_EFFECT_DEFAULT
:No effect, unless for the default vehicles
;VISUAL_EFFECT_STEAM
:Steam like from steam engine
;VISUAL_EFFECT_DIESEL
:Steam from internal combustion engine
;VISUAL_EFFECT_ELECTRIC
:Electric sparks
;VISUAL_EFFECT_DISABLE
:No effect
|-
| length
| 1 ... 8
| yes
| Length of the vehicle in arbitrary units. Use a value of 8 (equal to the predefined constant VEHICLE_LENGTH) for a full-length vehicle.
|}

==Ship properties==

{| class="t"
! property
! value range
! comment
|-
| sprite_id
| SPRITE_ID_NEW_SHIP
| Set this property to enable new graphics
|-
| speed
| 0 ... 127 km/h (float, speed units)
|
|-
| misc_flags
| bitmask(SHIP_FLAG_XXX)
| Bitmask with to possible flags, set to 0 to disable all.

;SHIP_FLAG_2CC
:Enable use of the 2nd company colour
;SHIP_FLAG_AUTOREFIT
:llow autorefitting. To enable autorefit, furthermore the [[#Vehicle callbacks|refit_cost]]-callback has to allow it, or else (if this callback is not implemented or fails) the <code style="color:green">refit_cost</code>-property (see below) must be set to 0.
;SHIP_FLAG_NO_BREAKDOWN_SMOKE
:{{nml|0.3}} {{ottdp|1.3|no|ottdrev=r24124}} Disable breakdown smoke effect
|-
| refit_cost
| 0 ... 255
| in 1/32 of the default refit cost base
|-
| callback_flags
| bitmask(VEH_CBF_XXX, ...)
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| is_refittable
| [0 <nowiki>|</nowiki> 1]
| 0=false, 1=true. Note: if you do not set this property to 1, then refittable_cargo_classes / non_refittable_cargo_classes have no effect.
|-
| <code style="color:green">default_cargo_type</code>
| An identifier from the [[NML:Cargotable|cargo table]], or DEFAULT_CARGO_FIRST_REFITTABLE
| If the vehicle is refittable to at least one cargo, but the chosen default cargo is not available or is set to DEFAULT_CARGO_FIRST_REFITTABLE, then the first refittable cargo is used. The first refittable is chosen according to the order in your [[NML:Cargotable|cargo table]]. If this property is set to a valid cargo but the vehicle cannot refit to any cargo type, then the vehicle will be able to carry only this cargo, but it cannot be refitted (like e.g. the default train wagons).
|-
| cargo_capacity
| 0 ... 255
| For ships (unlike other vehicle types) the capacity set here is not affected by the cargo type.
|-
| sound_effect
| SOUND_XXX
|
See available [[NML:List of sound effects|sound effects]].
|-
| ocean_speed_fraction
| 0 ... 1 (float)
|
{{ottd|1.2|r22639}} fraction of base speed on ocean tiles (default: 1)
|-
| canal_speed_fraction
| 0 ... 1 (float)
|
{{ottd|1.2|r22639}} fraction of base speed on canal tiles (default: 1)
|-
| visual_effect
| visual_effect(VISUAL_EFFECT_XXX, offset)
| XXX=[DEFAULT <nowiki>|</nowiki> STEAM <nowiki>|</nowiki> DIESEL <nowiki>|</nowiki> ELECTRIC <nowiki>|</nowiki> DISABLE], it is the type of the visual effect you want for this ship. Default means no effect. Offset is the position of the effect. 0 is default, negative values mean more to the front and positive values are backwards. Minimum offset is -8, maximum is 7.
|}

==Aircraft properties==

{| class="t"
! property
! value range
! comment
|-
| sprite_id
| SPRITE_ID_NEW_AIRCRAFT
| Set this property to enable new graphics
|-
| speed
| 0 .. 3280 km/h (float, speed units)
|
|-
| range
| 0 .. 2894
| {{nml|0.3}} {{ottdp|1.2|no|ottdrev=r23504}} Maximum (euclidean) distance the aircraft can cover between two airports. Set to 0 for unlimited range.
|-
| misc_flags
| bitmask(AIRCRAFT_FLAG_2CC, AIRCRAFT_FLAG_AUTOREFIT)
| Bitmask with to possible flags, set to 0 to disable all.

;AIRCRAFT_FLAG_2CC
:Enable 2nd company colour
;AIRCRAFT_FLAG_AUTOREFIT
:Allow autorefitting. To enable autorefit, furthermore the [[#Vehicle callbacks|refit_cost]]-callback has to allow it, or else (if this callback is not implemented or fails) the <code style="color:green">refit_cost</code>-property (see below) must be set to 0.
;AIRCRAFT_FLAG_NO_BREAKDOWN_SMOKE
:{{nml|0.3}} {{ottdp|1.3|no|ottdrev=r24124}} Disable breakdown smoke effect
|-
| refit_cost
| 0 ... 255
| in 1/32 of default refit cost base
|-
| callback_flags
| bitmask(VEH_CBF_XXX, ...)
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| aircraft_type
| AIRCRAFT_TYPE_XXX
|
;AIRCRAFT_TYPE_HELICOPTER
:Can land on helipad
;AIRCRAFT_TYPE_SMALL
:Can land on all airports with runway
;AIRCRAFT_TYPE_LARGE
:Can land on all airports with runway. But have a high crash chance on small airports
|-
| acceleration
| 0 ... 255
| In arbitrary units
|-
| passenger_capacity
| 0 ... 65536
| Capacity for the passenger compartment. See also the notes at <code style="color:darkgreen">mail_capacity</code> below.
|-
| mail_capacity
| 0 ... 255
| Capacity for the mail compartment, if refitted to a cargo in the CC_PASSENGERS class. When refitted to other cargoes, this capacity is added to the passenger capacity to determine the base capacity. The actual capacity is set to this base capacity divided by 1 for mail, 2 for goods and 4 for all other cargoes. To override this effect, use the <code style="color:darkgreen">passenger_capacity</code> and <code style="color:darkgreen">mail_capacity</code> callbacks.
|-
| sound_effect
| SOUND_XXX
|
See available [[NML:List of sound effects|sound effects]].
|}

==Vehicle variables==

Below an overview of all vehicle-specific variables. Not that in the purchase list, the vehicle is not built yet and as such many variables are not available. All general variables are available, refer to the table for info on vehicle-specific variables. Trying to access a non-available variable invokes undefined behaviour. Please note that while all variables are available for all vehicles types, some of them only make sense for one or more vehicle types. For example checking current_railtype for a non-rail vehicle doesn't make sense at all.

===Variables without parameter===

{| class="t"
! name
! value range
! available in purchase list?
! comment
|-
| position_in_consist
| 0 ... 255
| No
| The position of the current vehicle-part from the start of the vehicle. The engine will get value 0, the first wagon (or second engine) gets value 1, etc.
|-
| position_in_consist_from_end
| 0 ... 255
| No
| Same as position_in_consist but counted from the end. The last wagon will get value 0.
|-
| num_vehs_in_consist
| 1 ... 256
| No
| The total number of vehicles-parts in this vehicle. For aircraft this will include the shadow and the rotor.
|-
| position_in_vehid_chain
| 0 ... 255
| No
| See position_in_consist, but not of the complete vehicle but only all consecutive parts with the same id.
|-
| position_in_vehid_chain_from_end
| 0 ... 255
| No
| See position_in_consist_from_end, but not of the complete vehicle but only all consecutive parts with the same id.
|-
| num_vehs_in_vehid_chain
| 1 ... 256
| No
| See num_vehs_in_consist, but not of the complete vehicle but only all consecutive parts with the same id.
|-
| cargo_classes_in_consist
| Bitmask of CC_XXX
| No
|
[[NML:Cargos#Cargo classes|cargo classes]]
|-
| most_common_refit
|
[[NML:Cargos#Cargo properties|cargo class]]
| No
| cargo class most often refit to
|-
| bitmask_consist_info
| Bitmask 8 bit
| No
|
Binary OR of the values of [[#bitmask vehicle info|bitmask_vehicle_info]] of all vehicles (engines, wagons) in the consist. Only available for rail vehicles.
|-
| company_num
| 0 ... 14
| Yes
| company number of the vehicle owner. TTDPatch only supports up to 8 companies (0 ... 7)
|-
| company_type
| PLAYERTYPE_XX
| Yes
|
;PLAYERTYPE_HUMAN
:human player
;PLAYERTYPE_AI
:AI player
;PLAYERTYPE_HUMAN_IN_AI
:human managing AI company
;PLAYERTYPE_AI_IN_HUMAN
:AI managing human company

OpenTTD only uses PLAYERTYPE_HUMAN and PLAYERTYPE_AI. If you cheat yourself to be part of an AI company OpenTTD will still report PLAYERTYPE_AI for the company with yourself and the AI and it'll report PLAYERTYPE_HUMAN for the now uncontrolled company.
|-
| company_colour1
| COLOUR_XXX
| Yes
|
Refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for possible values.
|-
| company_colour2
| COLOUR_XXX
| Yes
|
Same as company_colour1, if no 2nd company colour is chosen. Refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for possible values.
|-
| aircraft_height
| 0 ... 255
| No
| Height difference between the aircraft and its shadow. 8 Units are equivalent to one height level on the map.
|-
| airport_type
| AIRPORTTYPE_XX
| No
|
;AIRPORTTYPE_SMALL
;AIRPORTTYPE_LARGE
;AIRPORTTYPE_HELIPORT
;AIRPORTTYPE_OILRIG
|-
| curv_info_prev_cur
| -2 ... 2
| No
| Difference in direction between the previous (towards engine) vehicle and this vehicle. Curvature to the right is positive. 1 unit is 45 degrees.
|-
| curv_info_cur_next
| -2 ... 2
| No
| Difference in direction between this vehicle and the next (towards rear end) vehicle. Curvature to the right is positive. 1 unit is 45 degrees.
|-
| curv_info_prev_next
| -4 ... 4
| No
| Difference in direction between the previous (towards engine) and next (towards rear end) vehicle. Curvature to the right is positive. 1 unit is 45 degrees. Equal to <code style="color:darkgreen">curve_invo_prev_cur + curv_info_cur_next</code>.
|-
| curv_info
| vehicle_curv_info(''prev_cur'', ''cur_next'')''''
| No
|
Returns a magic number that represents the curvature state of the prev-cur-next vehicle triplet. Do not try to make sense of this magic number, use the [[NML:Builtin functions|builtin function]] <code style="color:darkgreen">vehicle_curv_info()</code> instead to make comparisons. <code style="color:darkgreen">curv_info == vehicle_curv_info(a, b)</code> is equivalent to <code style="color:darkgreen">(curv_info_prev_cur == a) && (curv_info_cur_next == b)</code>, however the former can easily be used in a switch-block.
|-
| motion_counter
| 0 ... 15
| Yes, always 0
| Is increased every time the vehicle moves a single step on the map. Useful for animations.
|-
| cargo_type_in_veh
| entry in cargo translation table
| Yes, for the default cargo
| 0xFF if not present in the table
|-
| cargo_unit_weight
| weight per unit in 1/16t
| Yes, for the default cargo
|
|-
| cargo_classes
| Bitmask of [[NML:Cargos#Cargo properties|cargo class]]
| Yes, for the default cargo
| class of the currently transported cargo
|-
| vehicle_is_available
| [0 <nowiki>|</nowiki> 1]
| Yes
| Value is 1 if the vehicle is available on the open market
|-
| vehicle_is_testing
| [0 <nowiki>|</nowiki> 1]
| Yes
| Value is 1 if the vehicle is currently being tested
|-
| vehicle_is_offered
| [0 <nowiki>|</nowiki> 1]
| Yes
| Value is 1 if the vehicle is currently being offered for exclusive preview
|-
| build_year
| 0 ... 5000000
| Yes
| 0-based year when the vehicle was built, current year if the vehicle is not built yet
|-
| direction
| DIRECTION_XX
| No
|
See [[NML:List of direction constants|here]] for an overview of possible values and their meaning.
|-
| cargo_capacity
| 0 ... 65535
| No
| Cargo capacity (number of units) of the vehicle
|-
| cargo_count
| 0 ... 65535
| No
| Number of cargo units of cargo in the vehicle
|-
| cargo_subtype
| 0 ... 255
| Yes, always 0
| Cargo subtype, used to provide more than one refit option for the same cargo type. See also the <code style="color:darkgreen">cargo_subtype_text</code> callback.
|-
| vehicle_is_powered
| [0 <nowiki>|</nowiki> 1]
| No
| Vehicle provides power and is on the correct track type
|-
| vehicle_is_not_powered
| [0 <nowiki>|</nowiki> 1]
| No
| Vehicle is either on a wrong track type or it doesn't provide power at all
|-
| vehicle_is_potentially_powered
| [0 <nowiki>|</nowiki> 1]
| No
| Vehicle provides power, if it is on a suitable track type
|-
| vehicle_is_reversed
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle has reversed an odd number of times
|-
| built_during_preview
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle was built during the exclusive preview stage
|-
| current_railtype
| No
| Entry from railtype translation table or 0xFF
| Don't use this variable unless you've defined a railtype translation table. If the train is running on a railtype that is not listed in your railtype translation table this variable will contain 0xFF. Available since OpenTTD r20164.
|-
| waiting_triggers
|
| No
|
Random triggers waiting to be matched. (see [[NML:Random switch|Random switch]])
|-
| random_bits
| 0 ... 255
| No
|
Random data that can be used to randomize certain descisions. (see [[NML:Random switch|Random switch]])
|-
| grfid
| 0 ... 0xFFFFFFFF
| No
|
GRFID that defined the [[NML:Graphics|graphics]]-block for this vehicle. To compare this with other grfids, use the [[NML:Builtin functions|builtin function]] <code style="color:darkgreen">str2number()</code> to convert the other GRFID to a number as well.
|-
| vehicle_type_id
| 0 ... 65535
| No
| GRF-local ID of the vehicle, equal to the item ID. Note that vehicles from other NewGRFs may have the same ID, so you'll generally have to check the <code style="color:darkgreen">grfid</code> as well.
|-
| vehicle_is_hidden
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle is hidden in a depot or tunnel.
|-
| vehicle_is_stopped
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle is stopped, or if it is braking for a stop (trains only).
|-
| vehicle_is_crashed
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle has crashed.
|-
| vehicle_is_broken
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle is broken down.
|-
| date_of_last_service
| date(year, month, day)
| No
|
|-
| breakdowns_since_last_service
| 0 ... 255
| No
| Number of breakdowns since the last service
|-
| reliability
| 0 ... 100
| No
| Reliability (percentage)
|-
| age_in_days
| 0 ... 65535
| No
| Vehicle age in days.
|-
| max_age_in_days
| 0 ... 65535
| No
| Maximum vehicle age in days.
|-
| current_speed
| (speed units)
| No
| The current speed of the vehicle in m/s
|-
| max_speed
| (speed units)
| No
| The maximum speed of the vehicle in m/s
|-
| current_max_speed
| (speed units)
| No
| {{nml|0.3}} {{ottdp|1.3|no|ottdrev=r24246}} Current maximum speed of the vehicle in m/s. This includes e.g. track or timetable limits. Only valid for front vehicle.
|-
| vehicle_is_in_depot
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle is inside a depot
|}

===Variables that require an argument===

{| class="t"
! name
! Argument
! value range
! available in purchase list?
! comment
|-
| count_veh_id
| The vehicle ID to look for.
| 0..255
| No
| The number of vehicles in the current consist that have the given ID.
|-
| other_veh_curv_info
| Offset in the chain from the current vehicle.<ref name="offset">Value range is -128..127. Positive values are interpreted as towards the end, negative values as towards the front. If the offset is outside the vehicle chain, the result value will be 0.</ref>
| -4..4
| No
| Difference in direction between the other vehicle and this vehicle. Curvature to the right is positive. 1 unit is 45 degrees.
|-
| other_veh_is_hidden
| Offset in the chain from the current vehicle.<ref name="offset"/>
| [0 <nowiki>|</nowiki> 1]
| No
| 1 the other vehicle is hidden in a depot or tunnel, 0 otherwise
|-
| other_veh_x_offset
| Offset in the chain from the current vehicle.<ref name="offset"/>
| -128..127
| No
| Signed difference in X-position (top-right to bottom-left) between the other vehicle and this vehicle.
|-
| other_veh_x_offset
| Offset in the chain from the current vehicle.<ref name="offset"/>
| -128..127
| No
| Signed difference in Y-position (top-left to bottom-right) between the other vehicle and this vehicle.
|-
| other_veh_is_hidden
| Offset in the chain from the current vehicle.<ref name="offset"/>
| -128..127
| No
| Signed difference in Z-position (upwards) between the other vehicle and this vehicle.
|}
<references/>

==Vehicle callbacks==
The following table contains a list of available vehicle callbacks. Additionally, it's possible to provide cargo-specific graphics, using the identifier from the [[NML:Cargotable|cargo table]] as callback name. These callbacks will be used if the vehicle is refitted to the corresponding cargo type. If no cargo-specific graphics match the cargo that the vehicle is carrying, the <code style="color:darkgreen">default</code> callback is used instead. Cargo-specific graphics callbacks are never called from the purchase menu, refer to the <code style="color:darkgreen">purchase</code> callback below instead.

Note that the above affects '''graphics only''', other callbacks are unaffected.

{| class="t"
! Name
! Available for
! In purchase menu?
! value range
! comment
|-
| default
| All
| Yes, unless <code style="color:darkgreen">purchase</code> is set separately
| Sprite group
| 'Normal' vehicle graphics, if no cargo-specific graphics apply. See also the section on [[#Sprites in GUI|GUI sprites]].
|-
| purchase
| All
| Yes, only
| Sprite group
| Graphics to show in the buy menu (only the horizontal view is needed, except for dual-headed trains. With the <code>dual_headed</code> property set, special rules for the purchase menu sprite apply: two sprites are drawn (for front and back) as if the vehicle is normally constructed. If you supply one purchase menu sprite, it will be used for both vehicle parts in the purchase menu. Provide a set of 8 sprites, and the 7th resp. 3rd sprite will be drawn; provide a set of 8 blank sprites except the 7th if you want to fully control a single purchase menu sprite for a dual-headed engine. ) See also the section on [[#Sprites in GUI|GUI sprites]].
|-
| rotor
| Aircraft (helicopters)
| No
| Sprite group
| Graphics for the helicopter rotor (4 sprites; 1 stopped and 3 moving)
|-
| random_trigger
| All
| No
| N/A
| See [[NML:Random switch|random switch]] for more information.
|-
| cargo_subtype_text
| All
| No
| String, or CB_RESULT_NO_TEXT
| With this callback, you can display extra text after the cargo in the vehicle information window. This callback is called during refitting, with succesively increased values of the <code style="color:darkgreen">cargo_subtype</code> variable, until the callback returns CB_RESULT_NO_TEXT. All returned strings are then displayed as refit options. The chosen refit option is saved in the <code style="color:darkgreen">cargo_subtype</code> variable, so it can be used later for other things. In the HEQS grf for example, this mechanism is used to let the user choose between different capacities of the same vehicle.
|-
| additional_text
| All
| Yes, only
| String
| Additional text to show in the purchase list.
|-
| colour_mapping
| All
| Yes, unless <code style="color:darkgreen">purchase_colour_mapping</code> is set separately
| Recolour sprite number
|
With this callback, you can use a different recolour sprite instead of the standard 1cc / 2cc company colour remappings. See [[NML:List of default colour translation palettes|here]] for a list of default palettes. See the [[NML:Builtin functions|builtin function]] <code style="color:darkgreen">reserve_sprites()</code> for info on how to allocate your own sprite. For performance, the result is cached and only updated if the <code style="color:darkgreen"> every_32_days</code> callback requires so. Add CB_RESULT_COLOUR_MAPPING_ADD_CC to the result to add the company colour to the sprites, this requires 16 (1cc) or 256 (2cc) sprites in total.
|-
| start_stop
| All
| No
| String or CB_RESULT_NO_TEXT
| Called when starting or stopping a vehicle. Mainly useful to prevent vehicles from leaving the depot unless a certain condition is met. Return CB_RESULT_NO_TEXT to allow or a string (containing an error message) to disallow starting/stopping.
|-
| every_32_days
| All
| No
| bitmask(CB_RESULT_32_DAYS_XXX, ...)
| Called every 32 days. Set CB_RESULT_32_DAYS_TRIGGER in the bitmask to trigger TRIGGER_VEHICLE_32_CALLBACK. Set CB_RESULT_32_DAYS_COLOUR_MAPPING in the bitmask to update the colour mapping by re-running the <code style="color:darkgreen">colour_mapping</code> callback.
|-
| sound_effect
| All
| No
| SOUND_XXX, sound("sound.wav"), import_sound(grfid, number) or CB_RESULT_NO_SOUND
|
Called to play various vehicle sounds. <code style="color:darkgreen">extra_callback_info1</code> contains the sound event, see the [[#Sound events|table]] below. Return SOUND_XXX (see [[NML:List_of_sound_effects|here]]) to return a default sound. <code style="color:darkgreen">sound("soundfile")</code> imports a sound from a .wav file. <code style="color:darkgreen">import_sound(grfid, number)</code> imports a sound from another grf. A failed (or not implemented) callback will cause the default sound to be played. Return CB_RESULT_NO_SOUND to play no sound at all.
|-
| articulated_part
| Trains, Road Vehicles
| Yes (no separate callback)
| Vehicle ID, or CB_RESULT_NO_MORE_ARTICULATED_PARTS
| With this callback, you can add articulated parts (e.g. tenders) to your vehicle. Called repeatedly, until CB_RESULT_NO_MORE_ARTICULATED_PARTS is returned. After each call, the returned vehicleID is added to your vehicle. <code style="color:darkgreen">extra_callback_info1</code> contains 1 during the first call, 2 during the second, etc. Note that callback may be called from the purchase list, using vehicle variables is not possible. Or CB_RESULT_REVERSED_VEHICLE to the returned vehicle ID to display the vehicle backwards.

For NML 0.2 and lower the vehicle ID of the articulated part must be in the range 0 .. 127.
|-
| can_attach_wagon
| Trains
| No
| String or CB_RESULT_ATTACH_XXX
| Called when a wagon is being attached, to allow or disallow attaching. This callback has to be defined at the engine. However, variables in the <code style="color:darkgreen">SELF</code> scope refer to the wagon being attached, the <code style="color:darkgreen">PARENT</code> scope refers to the engine that the wagon is being attached to. Return a string to disallow with the string as error message. Return CB_RESULT_ATTACH_DISALLOW to disallow with standard message ("incompatible railtypes"), CB_RESULT_ATTACH_ALLOW to allow or CB_RESULT_ATTACH_ALLOW_IF_RAILTYPES to allow if the railtypes match (default).
|-
| refit_cost
| {{ottdp|1.2|no|ottdrev=r23089}} All
| Yes
| -8192 .. 8191 as refit cost. Add <code style="color:darkgreen">CB_RESULT_AUTOREFIT</code> if you want to allow autorefit.
| When returning a negative value, encode the cost as (cost & <code style="color:darkgreen">CB_RESULT_REFIT_COST_MASK</code>) before (possibly) adding <code style="color:darkgreen">CB_RESULT_AUTOREFIT</code>. To allow autorefitting, the corresponding bit in the <code style="color:darkgreen">misc_flags</code> must be set as well. Variable <code style="color:darkgreen">extra_callback_info1</code> contains information about the target cargo type in the format 0xccccsstt, with tt being the new cargo type, ss the new cargo subtype (see <code style="color:darkgreen">cargo_subtype_text</code>-callback) and cccc a bitmask of the [[NML:Cargos#Cargo_classes|cargo classes]] of the target cargo type. Note that this callback may also be called when the vehicle does not exist yet, so the available variables are limited.
|}

The following callbacks all have an equivalent property. The property description applies here also, except where otherwise noted.

{| class="t"
! Name
! Available for
! In purchase menu?
! comment
|-
| loading_speed
| All
| No
|
|-
| speed
| All
| Yes, unless <code style="color:darkgreen">purchase_speed</code> is set separately
| Units are not (yet) available
|-
| cost_factor
| All
| Yes, only
|
|-
| running_cost_factor
| All
| Yes, unless <code style="color:darkgreen">purchase_running_cost_factor</code> is set separately
|
|-
| cargo_age_period
| All
| No
|
|-
| cargo_capacity
| All except aircraft
| Yes, unless <code style="color:darkgreen">purchase_cargo_capacity</code> is set separately
|
|-
| passenger_capacity
| Aircraft
| Yes, unless <code style="color:darkgreen">purchase_passenger_capacity</code> is set separately
|
|-
| mail_capacity
| Aircraft
| Yes, unless <code style="color:darkgreen">purchase_mail_capacity</code> is set separately
|
|-
| range
| Aircraft
| Yes, unless <code style="color:darkgreen">purchase_range</code> is set separately
|
|-
| visual_effect_and_powered
| Trains
| No
|
|-
| visual_effect
| Road Vehicles, Ships
| No
|
|-
| power
| Trains, Road Vehicles
| Yes, unless <code style="color:darkgreen">purchase_power</code> is set separately
| Units are not (yet) available
|-
| weight
| Trains, Road Vehicles
| Yes, unless <code style="color:darkgreen">purchase_weight</code> is set separately
| Units are not (yet) available
|-
| length
| Trains, Road vehicles
| No
|
|-
| tractive_effort_coefficient
| Trains, Road Vehicles
| Yes, unless <code style="color:darkgreen">purchase_tractive_effort_coefficient</code> is set separately
| Value range is 0 .. 255 instead of 0 .. 1.
|-
| bitmask_vehicle_info
| Trains
| No
|
|}

===Sprites in GUI===
{{ottdp|1.2|no|ottdrev=r23080}} Since OpenTTD r23080 you can use variable <code style="color:darkgreen">extra_callback_info1</code> to display different sprites in the GUI and on the map. Currently these cases are available:
{| |-
! Lowest byte of extra_callback_info1 !! Meaning
|-
| 0x00 || Vehicle is drawn in a viewport, i.e. on the map.
|-
| 0x01..0x0F || reserved
|-
| 0x10 || Vehicle is drawn in the depot GUI. <ref>OpenTTD also uses this value with the purchase-list chain (cargotype FF) to determine the gridsize in ship and aircraft depots.</ref>
|-
| 0x11 || Vehicle is drawn in the vehicle details GUI. (This includes the refit GUI.)
|-
| 0x12 || Vehicle is drawn in the vehicle list.
|-
| 0x13..0x1F || reserved for other future GUIs.
|-
| 0x20 || Vehicle is drawn in the purchase list. (This includes the autoreplace GUI.)
|-
| 0x21 || Vehicle is drawn in the exclusive preview GUI or in the advertisement news.
|-
| 0x22..0x2F || reserved for other future GUIs with non-purchased vehicles.
|-
| 0x30..0xFF || reserved
|}
<references/>
The other bytes of variable <code style="color:darkgreen">extra_callback_info1</code> are reserved, and must be masked.
The cases 0x20..0x2F are called using the <code style="color:darkgreen">purchase</code>-callback, the other cases are called for the <code style="color:darkgreen">default</code>- or cargo-specific callbacks. Exception is the the special depot-gridsize call, which uses the <code style="color:darkgreen">purchase</code>-callback.

===Sound events===

{| class="t"
! Event
! Description
|-
| SOUND_EVENT_START
| Vehicle leaves station or depot, plane takes off
|-
| SOUND_EVENT_TUNNEL
| Vehicle enters tunnel
|-
| SOUND_EVENT_BREAKDOWN
| Vehicle breaks down (not for planes)
|-
| SOUND_EVENT_RUNNING
| Once per engine tick, but no more than once per vehicle motion
|-
| SOUND_EVENT_TOUCHDOWN
| Aircraft touches down
|-
| SOUND_EVENT_VISUAL_EFFECT
| Visual effect is generated (steam plume, diesel smoke, electric spark)
|-
| SOUND_EVENT_RUNNING_16
| Every 16 engine ticks if in motion
|-
| SOUND_EVENT_STOPPED
| Every 16 engine ticks if stopped
|-
| SOUND_EVENT_LOAD_UNLOAD
| Consist loads or unloads cargo
|}

NML:Vehicles

2012-07-27T10:20:41Z

Hirundo: Add vehicle flag VEHTYPE_FLAG_NO_BREAKDOWN_SMOKE

{{NMLNavPropVarCB}}

==Properties common to all vehicle types==

{| class="t"
! property
! value range
! available for articulated vehicle
! comment
|-
| <code style="color:green">name</code>
| (string)
| yes
| for example <code style="color:darkgreen">string(STR_NAME_HEREFORD_TRAM)</code>
|-
| <code style="color:green">climates_available</code>
| bitmask(CLIMATE_XXX, CLIMATE_YYY, ...)
| set to <code style="color:green">NO_CLIMATE</code>
|
;CLIMATE_TEMPERATE
;CLIMATE_ARCTIC
;CLIMATE_TROPICAL
;CLIMATE_TOYLAND
;NO_CLIMATE
:Vehicle is availble in no climate (e.g. for articulated parts)
;ALL_CLIMATES
:Vehicle is available irrespective of climate

To make a vehicle available in all climates except toyland you could use: <code style="color:green">ALL_CLIMATES & ~bitmask(CLIMATE_TOYLAND)</code>.
|-
| <code style="color:green">introduction_date</code>
| <code style="color:green">date</code>(yyyy,mm,dd)
| no
| Valid range for yyyy is 0 ... 5000000. In TTDPatch, dates after 2044 will be limited to 2044. Unless the engine is introduced within two years after game-start (always 1920 in TTDPatch), a random number of days between 0 and 511 will be added to this.
|-
| <code style="color:green">model_life</code>
| 0 ... 254 (years) or <code style="color:green">VEHICLE_NEVER_EXPIRES</code>
| no
|
Number of years a model is "supported" by the manufacturer, see [[#Engine life cycle|below]].
|-
| <code style="color:green">retire_early</code>
| -128 ... 127 (years)
| no
|
Retire the vehicle (make it unavailable in the purchase menu) this many years before reliability starts dropping, see [[#Engine life cycle|below]]. May be negative.
|-
| <code style="color:green">vehicle_life</code>
| 0 ... 255 (years)
| no
| Life length of an individual vehicle, before it is considered too old and in need of replacement.
|-
| <code style="color:green">reliability_decay</code>
| 0 ... 255
| no
| Default vehicles use 20. The higher the value the faster reliability decays, the more frequent service is needed. 0 means reliability never decreases if the vehicle is not too old
|-
| <code style="color:green">refittable_cargo_classes</code>
|
bit set of [[NML:Cargos#Cargo classes|cargo classes]]
| yes
| for example: <code style="color:darkgreen">bitmask(CC_BULK, CC_COVERED)</code>
|-
| <code style="color:green">non_refittable_cargo_classes</code>
|
bit set of [[NML:Cargos#Cargo classes|cargo classes]]
| yes
| for example: <code style="color:darkgreen">bitmask(CC_OVERSIZED, CC_SPECIAL)</code>
|-
| <code style="color:green">refittable_cargo_types</code>
| bit mask of entries into the cargo translation table
| yes
| As of NML 0.3, do not use this. Use cargo_[dis]allow_refit (see below) instead.
|-
| <code style="color:green">cargo_allow_refit</code>
| Array of cargo labels from the [[NML:Cargotable|cargotable]]
| Yes
| {{ottdp|1.2|no|ottdrev=r23291}} A list of cargo types to allow refitting to, irrespective of cargo classes. Example: <code style="color:darkgreen">[COAL, IORE]</code>
|-
| <code style="color:green">cargo_disallow_refit</code>
| Array of cargo labels from the [[NML:Cargotable|cargotable]]
| Yes
| {{ottdp|1.2|no|ottdrev=r23291}} A list of cargo types to disallow refitting to, irrespective of cargo classes. Example: <code style="color:darkgreen">[MAIL]</code>
|-
| <code style="color:green">loading_speed</code>
| 0 ... 255 (cargo units)
| yes
| Units of cargo loaded per time unit. Default vehicles use 5 for trains and road vehicles, 10 for ships and 20 for aircraft. This amount of cargo is loaded to or unloaded from the vehicle every 40 ticks for trains, every 20 ticks for road vehicles and aircraft and every 10 ticks for ships.
|-
| <code style="color:green">cost_factor</code>
| 0 ... 255
| Set to 0
| multiplier to the base purchase cost
|-
| <code style="color:green">running_cost_factor</code>
| 0 ... 255
| Set to 0
| multiplier to the base running costs
|-
| <code style="color:green">cargo_age_period</code>
| 0 ... 65535
| yes
|
{{ottd|1.2|r22713}} This property specifies after how many ticks cargo is aged. Default value is 185. 74 ticks is equal to 1 day.
|}

===Refittability===

To determine whether your vehicle can be refitted to a certain cargo, OpenTTD uses the following table

{| class="t"
! Cargo matches refittable_cargo_classes
! Cargo matches non_refittable_cargo_classes
! Cargo in cargo_allow_refit
! Cargo in cargo_disallow_refit
! Result
|-
| Yes
| No
| Doesn't matter
| No
| Refittable
|-
| No
| Doesn't matter
| No
| Doesn't matter
| Not refittable
|-
| Doesn't matter
| Doesn't matter
| Yes
| No
| Refittable
|-
| Doesn't matter
| Doesn't matter
| Doesn't matter
| Yes
| Not refittable
|}

For those that prefer boolean logic, the formula is as follows:

refittable = ((cargo classes in refittable_cargo_classes AND NOT cargo classes in non_refittable_cargo_classes) OR cargo in cargo_allow_refit) AND NOT (cargo in cargo_disallow_refit)

In general, you should use refittable_cargo_classes and non_refittable_cargo_classes to decide to which cargos your vehicle is refittable, and only then use cargo_allow_refit and cargo_disallow_refit to allow/disallow specific cargos.

===Engine life cycle===

The life cycle of a vehicle model consists of three phases, as outlined in the following table.

{| class="t"
! phase
! duration
! reliability
|-
| 1
| 7 to 38 months
| increases from 48-73% to 75-100%
|-
| 2
| <code style="color:darkgreen">model_life</code> - 8 years
| stays constant at peak, 75-100%
|-
| 3
| 10 to 20.5 years
| decreases from peak to 25-50%
|}

If <code style="color:darkgreen">model_life</code> is set to <code style="color:darkgreen">VEHICLE_NEVER_EXPIRES</code>, the engine remains in phase 2 forever.

Normally, the vehicle is removed from the purchase menu at the and of phase 3. However if you set the <code style="color:darkgreen">retire_early</code> property, it will be retired this many years before (or after, if the value is negative) the end of phase 2.

==Sorting vehicles in the purchase list==
This is a special property that is not encoded in an item/property-block like most other properties but it has it's own block instead. The syntax is as follows:

sort(<feature>, [<ID>, <ID>, <ID>...]);

The engines will be sorted in the given order on the position where originally the first element was. Say the original engine sorting is this: A B C D E and you use this code <code style="color:darkgreen">sort(FEAT_TRAINS, [D, B, A]);</code> the final sorting will be this: C D B A E

==Train properties==

{| class="t"
! property
! value range
! available for articulated vehicle
! comment
|-
| <code style="color:green">sprite_id</code>
| <code style="color:green">SPRITE_ID_NEW_TRAIN</code>
| yes
| Set this property to enable new graphics
|-
| <code style="color:green">speed</code>
| 0 ... 65000 (float, speed units)
| no
| Max speed for engines, speed limit for wagons
|-
| <code style="color:green">misc_flags</code>
| bitmask(TRAIN_FLAG_XXX, ...)
| FLIP should not be set, TILT and MU TO the same value as the 1st part
|
;TRAIN_FLAG_TILT
: enable the tilt bonus (20% speed in curves, if all vehicles in consist have it set)
;TRAIN_FLAG_2CC
:Enable use of the 2nd company colour
;TRAIN_FLAG_MU
:act as multiple unit (used for livery selection only)
;TRAIN_FLAG_FLIP
:Allow vehicle to be flipped (reversed) in depot
;TRAIN_FLAG_AUTOREFIT
:Allow autoreffitting. To enable autorefit, furthermore the [[#Vehicle callbacks|refit_cost]]-callback has to allow it, or else (if this callback is not implemented or fails) the <code style="color:green">refit_cost</code>-property (see below) must be set to 0.
;TRAIN_FLAG_NO_BREAKDOWN_SMOKE
:{{nml|0.3}} {{ottdp|1.3|no|ottdrev=r24124}} Disable breakdown smoke effect
|-
| <code style="color:green">refit_cost</code>
| 0 ... 255
| yes
| in 50% units of the purchase price cost base
|-
| <code style="color:green">callback_flags</code>
| bitmask(VEH_CBF_XXX, ...)
| yes
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| <code style="color:green">track_type</code>
| item from railtypetable
| must be the same as front
| Default railtype table: RAIL, MONO, MGLV. If you install a railtypetable yourself you'll always get the railtype you specified. If you want a vehicle to run on electric rail and you don't have a railtypetable, set <code style="color:green">track_type</code> to RAIL and make sure that you set <code style="color:green">engine_class</code> to <code style="color:green">ENGINE_CLASS_ELECTRIC</code>.
|-
| <code style="color:green">ai_special_flag</code>
| [<code style="color:green">AI_FLAG_PASSENGER</code> <nowiki>|</nowiki> <code style="color:green">AI_FLAG_CARGO</code>]
| no
|
;<code style="color:green">AI_FLAG_PASSENGER</code>
:Tell computer players that it's an engine that should only be used for passenger service.
|-
| <code style="color:green">power</code>
| 0 ... 65000 hp (float, power units)
| Set to 0
|
|-
| <code style="color:green">running_cost_base</code>
| RUNNING_COST_XXX
| Set to RUNNING_COST_NONE
|
;RUNNING_COST_STEAM
;RUNNING_COST_DIESEL
;RUNNING_COST_ELECTRIC
;RUNNING_COST_ROADVEH
;RUNNING_COST_NONE
:no running costs
|-
| <code style="color:green">dual_headed</code>
| [0 <nowiki>|</nowiki> 1]
| Set to 0 for all parts of an articulated vehicle
| 1 = dual_headed, otherwise normal engine
|-
| <code style="color:green">default_cargo_type</code>
| An identifier from the [[NML:Cargotable|cargo table]], or DEFAULT_CARGO_FIRST_REFITTABLE
| Yes
| If the vehicle is refittable to at least one cargo, but the chosen default cargo is not available or is set to DEFAULT_CARGO_FIRST_REFITTABLE, then the first refittable cargo is used. The first refittable is chosen according to the order in your [[NML:Cargotable|cargo table]]. If this property is set to a valid cargo but the vehicle cannot refit to any cargo type, then the vehicle will be able to carry only this cargo, but it cannot be refitted (like e.g. the default train wagons).
|-
| <code style="color:green">cargo_capacity</code>
| 0 .. 255
| yes
| By default, passenger capacity is 4x, and mail/goods capacity 2x larger than capacity for other cargoes. The capacity set here is used for the default (i.e. first refittable) cargo. Use the <code style="color:green">cargo_capacity</code> callback to avoid this effect.
|-
| <code style="color:green">weight</code>
| 0 .. 1279 ton (float, mass units)
| Set to 0
|
|-
| <code style="color:green">ai_engine_rank</code>
| 0 ... 255
| no
| TTDPatch only: Higher values make the engine for the TTDPatch AI more attractive
|-
| <code style="color:green">engine_class</code>
| ENGINE_CLASS_XXX
| no
|
Defines which livery colour settings apply to the vehicle
;ENGINE_CLASS_STEAM
;ENGINE_CLASS_DIESEL
;ENGINE_CLASS_ELECTRIC
;ENGINE_CLASS_MONORAIL
;ENGINE_CLASS_MAGLEV
|-
| <code style="color:green">extra_power_per_wagon</code>
| 0 ... 65000 hp (float, power units)
| Set to 0
| Only wagons with a livery override for this engine will add power
|-
| <code style="color:green">tractive_effort_coefficient</code>
| 0 ... 1 (float)
| Set to 0
| Fraction of the vehicle weight that is available as tractive effort. Tractive effort (in kN) is calculated as (TE coefficient) * 10 * weight (in tons), with 10 being an approximation of the acceleration of gravity (9.81 m/s). Default value is 0.3.
|-
| <code style="color:green">air_drag_coefficient</code>
| 0 ... 1 (float)
| Set to 0
| Coefficient of the relative air drag, in arbitrary units. The default value is approximately (8 / max_speed), with max_speed in km/h, clamped to the range 0.004 .. 0.75.
|-
| <code style="color:green">length</code>
| 1 ... 8
| yes
| Length of the vehicle in arbitrary units. Use a value of 8 (equal to the predefined constant VEHICLE_LENGTH) for a full-length vehicle.
|-
| <code style="color:green">visual_effect_and_powered</code>
| <code style="color:green">visual_effect_and_powered</code> (VISUAL_EFFECT_XXX, offset, <code style="color:green">ENABLE_WAGON_POWER</code> or <code style="color:green">DISABLE_WAGON_POWER</code>)
| yes
|
Set the type of visual effect for the vehicle and its positional offset with respect to the vehicle. An offset of 0 is default, negative values mean more to the front and positive values are backwards. Minimum offset is -8, maximum is 7.

;VISUAL_EFFECT_DEFAULT
:No effect, unless for the default vehicles
;VISUAL_EFFECT_STEAM
:Steam like from steam engine
;VISUAL_EFFECT_DIESEL
:Steam from internal combustion engine
;VISUAL_EFFECT_ELECTRIC
:Electric sparks
;VISUAL_EFFECT_DISABLE
:No effect
|-
| <code style="color:green">extra_weight_per_wagon</code>
| 0 ... 255 ton (float, mass units)
| Set to 0
| Adds extra weight for powered wagons, see <code style="color:green">extra_power_per_wagon</code>
|-
| <code style="color:green">bitmask_vehicle_info</code>
| 8-bit bitmask
| yes
|
Used for obtaining [[#bitmask consist info|<code style="color:green">bitmask_consist_info</code>]]
|}

==Road vehicle properties==

{| class="t"
! property
! value range
! available for articulated vehicle
! comment
|-
| sprite_id
| SPRITE_ID_NEW_ROADVEH
| yes
| Set this property to enable new graphics
|-
| speed
| 0 ... 514km/h (float, speed units)
| no
|
|-
| misc_flags
| bitmask(ROADVEH_FLAG_XXX, ...)
| partly; tram flag must the same
|
;ROADVEH_FLAG_TRAM
:The vehicle requires tram tracks to run on
;ROADVEH_FLAG_2CC
:Enable 2nd company colour
;ROADVEH_FLAG_AUTOREFIT
:Allow autorefitting. To enable autorefit, furthermore the [[#Vehicle callbacks|refit_cost]]-callback has to allow it, or else (if this callback is not implemented or fails) the <code style="color:green">refit_cost</code>-property (see below) must be set to 0.
;ROADVEH_FLAG_NO_BREAKDOWN_SMOKE
:{{nml|0.3}} {{ottdp|1.3|no|ottdrev=r24124}} Disable breakdown smoke effect
|-
| refit_cost
| 0 ... 255
| yes
| in 25% units of the purchase price cost base
|-
| callback_flags
| bitmask(VEH_CBF_XXX, ...)
| yes
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| running_cost_base
| RUNNING_COST_XXX
| set to RUNNING_COST_NONE
|
;RUNNING_COST_STEAM
;RUNNING_COST_DIESEL
;RUNNING_COST_ELECTRIC
;RUNNING_COST_ROADVEH
;RUNNING_COST_NONE
:no running costs
|-
| power
| 0 ... 2550hp (float, power units)
| Set to 0
|
|-
| weight
| 0 ... 63.75ton (float, mass units)
| Set to 0
|
|-
| tractive_effort_coefficient
| 0 ... 1 (float)
| Set to 0
| Fraction of the vehicle weight that is available as tractive effort. Tractive effort (in kN) is calculated as (TE coefficient) * 10 * weight (in tons), with 10 being an approximation of the acceleration of gravity (9.81 m/s). Default value is 0.3.
|-
| air_drag_coefficient
| 0 ... 1 (float)
| Set to 0
| Coefficient of the relative air drag, in arbitrary units. The default value is approximately (8 / max_speed), with max_speed in km/h, clamped to the range 0.004 .. 0.75.
|-
| <code style="color:green">default_cargo_type</code>
| An identifier from the [[NML:Cargotable|cargo table]], or DEFAULT_CARGO_FIRST_REFITTABLE
| Yes
| If the vehicle is refittable to at least one cargo, but the chosen default cargo is not available or is set to DEFAULT_CARGO_FIRST_REFITTABLE, then the first refittable cargo is used. The first refittable is chosen according to the order in your [[NML:Cargotable|cargo table]]. If this property is set to a valid cargo but the vehicle cannot refit to any cargo type, then the vehicle will be able to carry only this cargo, but it cannot be refitted (like e.g. the default train wagons).
|-
| cargo_capacity
| 0 ... 255
| yes
| By default, passenger capacity is 4x, and mail/goods capacity 2x larger than capacity for other cargoes. The capacity set here is used for the default (i.e. first refittable) cargo. Use the <code style="color:green">cargo_capacity</code> callback to avoid this effect.
|-
| sound_effect
| SOUND_XXX
| no
|
See available [[NML:List of sound effects|sound effects]].
|-
| visual_effect
| visual_effect( VISUAL_EFFECT_XXX, offset)
| yes
|
Set the type of visual effect for the vehicle and its positional offset with respect to the vehicle. An offset of 0 is default, negative values mean more to the front and positive values are backwards. Minimum offset is -8, maximum is 7.

;VISUAL_EFFECT_DEFAULT
:No effect, unless for the default vehicles
;VISUAL_EFFECT_STEAM
:Steam like from steam engine
;VISUAL_EFFECT_DIESEL
:Steam from internal combustion engine
;VISUAL_EFFECT_ELECTRIC
:Electric sparks
;VISUAL_EFFECT_DISABLE
:No effect
|-
| length
| 1 ... 8
| yes
| Length of the vehicle in arbitrary units. Use a value of 8 (equal to the predefined constant VEHICLE_LENGTH) for a full-length vehicle.
|}

==Ship properties==

{| class="t"
! property
! value range
! comment
|-
| sprite_id
| SPRITE_ID_NEW_SHIP
| Set this property to enable new graphics
|-
| speed
| 0 ... 127 km/h (float, speed units)
|
|-
| misc_flags
| bitmask(SHIP_FLAG_XXX)
| Bitmask with to possible flags, set to 0 to disable all.

;SHIP_FLAG_2CC
:Enable use of the 2nd company colour
;SHIP_FLAG_AUTOREFIT
:llow autorefitting. To enable autorefit, furthermore the [[#Vehicle callbacks|refit_cost]]-callback has to allow it, or else (if this callback is not implemented or fails) the <code style="color:green">refit_cost</code>-property (see below) must be set to 0.
;SHIP_FLAG_NO_BREAKDOWN_SMOKE
:{{nml|0.3}} {{ottdp|1.3|no|ottdrev=r24124}} Disable breakdown smoke effect
|-
| refit_cost
| 0 ... 255
| in 1/32 of the default refit cost base
|-
| callback_flags
| bitmask(VEH_CBF_XXX, ...)
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| is_refittable
| [0 <nowiki>|</nowiki> 1]
| 0=false, 1=true. Note: if you do not set this property to 1, then refittable_cargo_classes / non_refittable_cargo_classes have no effect.
|-
| <code style="color:green">default_cargo_type</code>
| An identifier from the [[NML:Cargotable|cargo table]], or DEFAULT_CARGO_FIRST_REFITTABLE
| If the vehicle is refittable to at least one cargo, but the chosen default cargo is not available or is set to DEFAULT_CARGO_FIRST_REFITTABLE, then the first refittable cargo is used. The first refittable is chosen according to the order in your [[NML:Cargotable|cargo table]]. If this property is set to a valid cargo but the vehicle cannot refit to any cargo type, then the vehicle will be able to carry only this cargo, but it cannot be refitted (like e.g. the default train wagons).
|-
| cargo_capacity
| 0 ... 255
| For ships (unlike other vehicle types) the capacity set here is not affected by the cargo type.
|-
| sound_effect
| SOUND_XXX
|
See available [[NML:List of sound effects|sound effects]].
|-
| ocean_speed_fraction
| 0 ... 1 (float)
|
{{ottd|1.2|r22639}} fraction of base speed on ocean tiles (default: 1)
|-
| canal_speed_fraction
| 0 ... 1 (float)
|
{{ottd|1.2|r22639}} fraction of base speed on canal tiles (default: 1)
|-
| visual_effect
| visual_effect(VISUAL_EFFECT_XXX, offset)
| XXX=[DEFAULT <nowiki>|</nowiki> STEAM <nowiki>|</nowiki> DIESEL <nowiki>|</nowiki> ELECTRIC <nowiki>|</nowiki> DISABLE], it is the type of the visual effect you want for this ship. Default means no effect. Offset is the position of the effect. 0 is default, negative values mean more to the front and positive values are backwards. Minimum offset is -8, maximum is 7.
|}

==Aircraft properties==

{| class="t"
! property
! value range
! comment
|-
| sprite_id
| SPRITE_ID_NEW_AIRCRAFT
| Set this property to enable new graphics
|-
| speed
| 0 .. 3280 km/h (float, speed units)
|
|-
| range
| 0 .. 2894
| {{nml|0.3}} {{ottdp|1.2|no|ottdrev=r23504}} Maximum (euclidean) distance the aircraft can cover between two airports. Set to 0 for unlimited range.
|-
| misc_flags
| bitmask(AIRCRAFT_FLAG_2CC, AIRCRAFT_FLAG_AUTOREFIT)
| Bitmask with to possible flags, set to 0 to disable all.

;AIRCRAFT_FLAG_2CC
:Enable 2nd company colour
;AIRCRAFT_FLAG_AUTOREFIT
:Allow autorefitting. To enable autorefit, furthermore the [[#Vehicle callbacks|refit_cost]]-callback has to allow it, or else (if this callback is not implemented or fails) the <code style="color:green">refit_cost</code>-property (see below) must be set to 0.
;AIRCRAFT_FLAG_NO_BREAKDOWN_SMOKE
:{{nml|0.3}} {{ottdp|1.3|no|ottdrev=r24124}} Disable breakdown smoke effect
|-
| refit_cost
| 0 ... 255
| in 1/32 of default refit cost base
|-
| callback_flags
| bitmask(VEH_CBF_XXX, ...)
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| aircraft_type
| AIRCRAFT_TYPE_XXX
|
;AIRCRAFT_TYPE_HELICOPTER
:Can land on helipad
;AIRCRAFT_TYPE_SMALL
:Can land on all airports with runway
;AIRCRAFT_TYPE_LARGE
:Can land on all airports with runway. But have a high crash chance on small airports
|-
| acceleration
| 0 ... 255
| In arbitrary units
|-
| passenger_capacity
| 0 ... 65536
| Capacity for the passenger compartment. See also the notes at <code style="color:darkgreen">mail_capacity</code> below.
|-
| mail_capacity
| 0 ... 255
| Capacity for the mail compartment, if refitted to a cargo in the CC_PASSENGERS class. When refitted to other cargoes, this capacity is added to the passenger capacity to determine the base capacity. The actual capacity is set to this base capacity divided by 1 for mail, 2 for goods and 4 for all other cargoes. To override this effect, use the <code style="color:darkgreen">passenger_capacity</code> and <code style="color:darkgreen">mail_capacity</code> callbacks.
|-
| sound_effect
| SOUND_XXX
|
See available [[NML:List of sound effects|sound effects]].
|}

==Vehicle variables==

Below an overview of all vehicle-specific variables. Not that in the purchase list, the vehicle is not built yet and as such many variables are not available. All general variables are available, refer to the table for info on vehicle-specific variables. Trying to access a non-available variable invokes undefined behaviour. Please note that while all variables are available for all vehicles types, some of them only make sense for one or more vehicle types. For example checking current_railtype for a non-rail vehicle doesn't make sense at all.

===Variables without parameter===

{| class="t"
! name
! value range
! available in purchase list?
! comment
|-
| position_in_consist
| 0 ... 255
| No
| The position of the current vehicle-part from the start of the vehicle. The engine will get value 0, the first wagon (or second engine) gets value 1, etc.
|-
| position_in_consist_from_end
| 0 ... 255
| No
| Same as position_in_consist but counted from the end. The last wagon will get value 0.
|-
| num_vehs_in_consist
| 1 ... 256
| No
| The total number of vehicles-parts in this vehicle. For aircraft this will include the shadow and the rotor.
|-
| position_in_vehid_chain
| 0 ... 255
| No
| See position_in_consist, but not of the complete vehicle but only all consecutive parts with the same id.
|-
| position_in_vehid_chain_from_end
| 0 ... 255
| No
| See position_in_consist_from_end, but not of the complete vehicle but only all consecutive parts with the same id.
|-
| num_vehs_in_vehid_chain
| 1 ... 256
| No
| See num_vehs_in_consist, but not of the complete vehicle but only all consecutive parts with the same id.
|-
| cargo_classes_in_consist
| Bitmask of CC_XXX
| No
|
[[NML:Cargos#Cargo classes|cargo classes]]
|-
| most_common_refit
|
[[NML:Cargos#Cargo properties|cargo class]]
| No
| cargo class most often refit to
|-
| bitmask_consist_info
| Bitmask 8 bit
| No
|
Binary OR of the values of [[#bitmask vehicle info|bitmask_vehicle_info]] of all vehicles (engines, wagons) in the consist. Only available for rail vehicles.
|-
| company_num
| 0 ... 14
| Yes
| company number of the vehicle owner. TTDPatch only supports up to 8 companies (0 ... 7)
|-
| company_type
| PLAYERTYPE_XX
| Yes
|
;PLAYERTYPE_HUMAN
:human player
;PLAYERTYPE_AI
:AI player
;PLAYERTYPE_HUMAN_IN_AI
:human managing AI company
;PLAYERTYPE_AI_IN_HUMAN
:AI managing human company

OpenTTD only uses PLAYERTYPE_HUMAN and PLAYERTYPE_AI. If you cheat yourself to be part of an AI company OpenTTD will still report PLAYERTYPE_AI for the company with yourself and the AI and it'll report PLAYERTYPE_HUMAN for the now uncontrolled company.
|-
| company_colour1
| COLOUR_XXX
| Yes
|
Refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for possible values.
|-
| company_colour2
| COLOUR_XXX
| Yes
|
Same as company_colour1, if no 2nd company colour is chosen. Refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for possible values.
|-
| aircraft_height
| 0 ... 255
| No
| Height difference between the aircraft and its shadow. 8 Units are equivalent to one height level on the map.
|-
| airport_type
| AIRPORTTYPE_XX
| No
|
;AIRPORTTYPE_SMALL
;AIRPORTTYPE_LARGE
;AIRPORTTYPE_HELIPORT
;AIRPORTTYPE_OILRIG
|-
| curv_info_prev_cur
| -2 ... 2
| No
| Difference in direction between the previous (towards engine) vehicle and this vehicle. Curvature to the right is positive. 1 unit is 45 degrees.
|-
| curv_info_cur_next
| -2 ... 2
| No
| Difference in direction between this vehicle and the next (towards rear end) vehicle. Curvature to the right is positive. 1 unit is 45 degrees.
|-
| curv_info_prev_next
| -4 ... 4
| No
| Difference in direction between the previous (towards engine) and next (towards rear end) vehicle. Curvature to the right is positive. 1 unit is 45 degrees. Equal to <code style="color:darkgreen">curve_invo_prev_cur + curv_info_cur_next</code>.
|-
| curv_info
| vehicle_curv_info(''prev_cur'', ''cur_next'')''''
| No
|
Returns a magic number that represents the curvature state of the prev-cur-next vehicle triplet. Do not try to make sense of this magic number, use the [[NML:Builtin functions|builtin function]] <code style="color:darkgreen">vehicle_curv_info()</code> instead to make comparisons. <code style="color:darkgreen">curv_info == vehicle_curv_info(a, b)</code> is equivalent to <code style="color:darkgreen">(curv_info_prev_cur == a) && (curv_info_cur_next == b)</code>, however the former can easily be used in a switch-block.
|-
| motion_counter
| 0 ... 15
| Yes, always 0
| Is increased every time the vehicle moves a single step on the map. Useful for animations.
|-
| cargo_type_in_veh
| entry in cargo translation table
| Yes, for the default cargo
| 0xFF if not present in the table
|-
| cargo_unit_weight
| weight per unit in 1/16t
| Yes, for the default cargo
|
|-
| cargo_classes
| Bitmask of [[NML:Cargos#Cargo properties|cargo class]]
| Yes, for the default cargo
| class of the currently transported cargo
|-
| vehicle_is_available
| [0 <nowiki>|</nowiki> 1]
| Yes
| Value is 1 if the vehicle is available on the open market
|-
| vehicle_is_testing
| [0 <nowiki>|</nowiki> 1]
| Yes
| Value is 1 if the vehicle is currently being tested
|-
| vehicle_is_offered
| [0 <nowiki>|</nowiki> 1]
| Yes
| Value is 1 if the vehicle is currently being offered for exclusive preview
|-
| build_year
| 0 ... 5000000
| Yes
| 0-based year when the vehicle was built, current year if the vehicle is not built yet
|-
| direction
| DIRECTION_XX
| No
|
See [[NML:List of direction constants|here]] for an overview of possible values and their meaning.
|-
| cargo_capacity
| 0 ... 65535
| No
| Cargo capacity (number of units) of the vehicle
|-
| cargo_count
| 0 ... 65535
| No
| Number of cargo units of cargo in the vehicle
|-
| cargo_subtype
| 0 ... 255
| Yes, always 0
| Cargo subtype, used to provide more than one refit option for the same cargo type. See also the <code style="color:darkgreen">cargo_subtype_text</code> callback.
|-
| vehicle_is_powered
| [0 <nowiki>|</nowiki> 1]
| No
| Vehicle provides power and is on the correct track type
|-
| vehicle_is_not_powered
| [0 <nowiki>|</nowiki> 1]
| No
| Vehicle is either on a wrong track type or it doesn't provide power at all
|-
| vehicle_is_potentially_powered
| [0 <nowiki>|</nowiki> 1]
| No
| Vehicle provides power, if it is on a suitable track type
|-
| vehicle_is_reversed
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle has reversed an odd number of times
|-
| built_during_preview
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle was built during the exclusive preview stage
|-
| current_railtype
| No
| Entry from railtype translation table or 0xFF
| Don't use this variable unless you've defined a railtype translation table. If the train is running on a railtype that is not listed in your railtype translation table this variable will contain 0xFF. Available since OpenTTD r20164.
|-
| waiting_triggers
|
| No
|
Random triggers waiting to be matched. (see [[NML:Random switch|Random switch]])
|-
| random_bits
| 0 ... 255
| No
|
Random data that can be used to randomize certain descisions. (see [[NML:Random switch|Random switch]])
|-
| grfid
| 0 ... 0xFFFFFFFF
| No
|
GRFID that defined the [[NML:Graphics|graphics]]-block for this vehicle. To compare this with other grfids, use the [[NML:Builtin functions|builtin function]] <code style="color:darkgreen">str2number()</code> to convert the other GRFID to a number as well.
|-
| vehicle_type_id
| 0 ... 65535
| No
| GRF-local ID of the vehicle, equal to the item ID. Note that vehicles from other NewGRFs may have the same ID, so you'll generally have to check the <code style="color:darkgreen">grfid</code> as well.
|-
| vehicle_is_hidden
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle is hidden in a depot or tunnel.
|-
| vehicle_is_stopped
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle is stopped, or if it is braking for a stop (trains only).
|-
| vehicle_is_crashed
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle has crashed.
|-
| vehicle_is_broken
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle is broken down.
|-
| date_of_last_service
| date(year, month, day)
| No
|
|-
| breakdowns_since_last_service
| 0 ... 255
| No
| Number of breakdowns since the last service
|-
| reliability
| 0 ... 100
| No
| Reliability (percentage)
|-
| age_in_days
| 0 ... 65535
| No
| Vehicle age in days.
|-
| max_age_in_days
| 0 ... 65535
| No
| Maximum vehicle age in days.
|-
| current_speed
| (speed units)
| No
| The current speed of the vehicle in m/s
|-
| max_speed
| (speed units)
| No
| The maximum speed of the vehicle in m/s
|-
| current_max_speed
| (speed units)
| No
| {{nml|0.3}} {{ottdp|1.3|no|ottdrev=r24246}} Current maximum speed of the vehicle in m/s. This includes e.g. track or timetable limits. Only valid for front vehicle.
|-
| vehicle_is_in_depot
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle is inside a depot
|}

===Variables that require an argument===

{| class="t"
! name
! Argument
! value range
! available in purchase list?
! comment
|-
| count_veh_id
| The vehicle ID to look for.
| 0..255
| No
| The number of vehicles in the current consist that have the given ID.
|}

==Vehicle callbacks==
The following table contains a list of available vehicle callbacks. Additionally, it's possible to provide cargo-specific graphics, using the identifier from the [[NML:Cargotable|cargo table]] as callback name. These callbacks will be used if the vehicle is refitted to the corresponding cargo type. If no cargo-specific graphics match the cargo that the vehicle is carrying, the <code style="color:darkgreen">default</code> callback is used instead. Cargo-specific graphics callbacks are never called from the purchase menu, refer to the <code style="color:darkgreen">purchase</code> callback below instead.

Note that the above affects '''graphics only''', other callbacks are unaffected.

{| class="t"
! Name
! Available for
! In purchase menu?
! value range
! comment
|-
| default
| All
| Yes, unless <code style="color:darkgreen">purchase</code> is set separately
| Sprite group
| 'Normal' vehicle graphics, if no cargo-specific graphics apply. See also the section on [[#Sprites in GUI|GUI sprites]].
|-
| purchase
| All
| Yes, only
| Sprite group
| Graphics to show in the buy menu (only the horizontal view is needed, except for dual-headed trains. With the <code>dual_headed</code> property set, special rules for the purchase menu sprite apply: two sprites are drawn (for front and back) as if the vehicle is normally constructed. If you supply one purchase menu sprite, it will be used for both vehicle parts in the purchase menu. Provide a set of 8 sprites, and the 7th resp. 3rd sprite will be drawn; provide a set of 8 blank sprites except the 7th if you want to fully control a single purchase menu sprite for a dual-headed engine. ) See also the section on [[#Sprites in GUI|GUI sprites]].
|-
| rotor
| Aircraft (helicopters)
| No
| Sprite group
| Graphics for the helicopter rotor (4 sprites; 1 stopped and 3 moving)
|-
| random_trigger
| All
| No
| N/A
| See [[NML:Random switch|random switch]] for more information.
|-
| cargo_subtype_text
| All
| No
| String, or CB_RESULT_NO_TEXT
| With this callback, you can display extra text after the cargo in the vehicle information window. This callback is called during refitting, with succesively increased values of the <code style="color:darkgreen">cargo_subtype</code> variable, until the callback returns CB_RESULT_NO_TEXT. All returned strings are then displayed as refit options. The chosen refit option is saved in the <code style="color:darkgreen">cargo_subtype</code> variable, so it can be used later for other things. In the HEQS grf for example, this mechanism is used to let the user choose between different capacities of the same vehicle.
|-
| additional_text
| All
| Yes, only
| String
| Additional text to show in the purchase list.
|-
| colour_mapping
| All
| Yes, unless <code style="color:darkgreen">purchase_colour_mapping</code> is set separately
| Recolour sprite number
|
With this callback, you can use a different recolour sprite instead of the standard 1cc / 2cc company colour remappings. See [[NML:List of default colour translation palettes|here]] for a list of default palettes. See the [[NML:Builtin functions|builtin function]] <code style="color:darkgreen">reserve_sprites()</code> for info on how to allocate your own sprite. For performance, the result is cached and only updated if the <code style="color:darkgreen"> every_32_days</code> callback requires so. Add CB_RESULT_COLOUR_MAPPING_ADD_CC to the result to add the company colour to the sprites, this requires 16 (1cc) or 256 (2cc) sprites in total.
|-
| start_stop
| All
| No
| String or CB_RESULT_NO_TEXT
| Called when starting or stopping a vehicle. Mainly useful to prevent vehicles from leaving the depot unless a certain condition is met. Return CB_RESULT_NO_TEXT to allow or a string (containing an error message) to disallow starting/stopping.
|-
| every_32_days
| All
| No
| bitmask(CB_RESULT_32_DAYS_XXX, ...)
| Called every 32 days. Set CB_RESULT_32_DAYS_TRIGGER in the bitmask to trigger TRIGGER_VEHICLE_32_CALLBACK. Set CB_RESULT_32_DAYS_COLOUR_MAPPING in the bitmask to update the colour mapping by re-running the <code style="color:darkgreen">colour_mapping</code> callback.
|-
| sound_effect
| All
| No
| SOUND_XXX, sound("sound.wav"), import_sound(grfid, number) or CB_RESULT_NO_SOUND
|
Called to play various vehicle sounds. <code style="color:darkgreen">extra_callback_info1</code> contains the sound event, see the [[#Sound events|table]] below. Return SOUND_XXX (see [[NML:List_of_sound_effects|here]]) to return a default sound. <code style="color:darkgreen">sound("soundfile")</code> imports a sound from a .wav file. <code style="color:darkgreen">import_sound(grfid, number)</code> imports a sound from another grf. A failed (or not implemented) callback will cause the default sound to be played. Return CB_RESULT_NO_SOUND to play no sound at all.
|-
| articulated_part
| Trains, Road Vehicles
| Yes (no separate callback)
| Vehicle ID, or CB_RESULT_NO_MORE_ARTICULATED_PARTS
| With this callback, you can add articulated parts (e.g. tenders) to your vehicle. Called repeatedly, until CB_RESULT_NO_MORE_ARTICULATED_PARTS is returned. After each call, the returned vehicleID is added to your vehicle. <code style="color:darkgreen">extra_callback_info1</code> contains 1 during the first call, 2 during the second, etc. Note that callback may be called from the purchase list, using vehicle variables is not possible. Or CB_RESULT_REVERSED_VEHICLE to the returned vehicle ID to display the vehicle backwards.

For NML 0.2 and lower the vehicle ID of the articulated part must be in the range 0 .. 127.
|-
| can_attach_wagon
| Trains
| No
| String or CB_RESULT_ATTACH_XXX
| Called when a wagon is being attached, to allow or disallow attaching. This callback has to be defined at the engine. However, variables in the <code style="color:darkgreen">SELF</code> scope refer to the wagon being attached, the <code style="color:darkgreen">PARENT</code> scope refers to the engine that the wagon is being attached to. Return a string to disallow with the string as error message. Return CB_RESULT_ATTACH_DISALLOW to disallow with standard message ("incompatible railtypes"), CB_RESULT_ATTACH_ALLOW to allow or CB_RESULT_ATTACH_ALLOW_IF_RAILTYPES to allow if the railtypes match (default).
|-
| refit_cost
| {{ottdp|1.2|no|ottdrev=r23089}} All
| Yes
| -8192 .. 8191 as refit cost. Add <code style="color:darkgreen">CB_RESULT_AUTOREFIT</code> if you want to allow autorefit.
| When returning a negative value, encode the cost as (cost & <code style="color:darkgreen">CB_RESULT_REFIT_COST_MASK</code>) before (possibly) adding <code style="color:darkgreen">CB_RESULT_AUTOREFIT</code>. To allow autorefitting, the corresponding bit in the <code style="color:darkgreen">misc_flags</code> must be set as well. Variable <code style="color:darkgreen">extra_callback_info1</code> contains information about the target cargo type in the format 0xccccsstt, with tt being the new cargo type, ss the new cargo subtype (see <code style="color:darkgreen">cargo_subtype_text</code>-callback) and cccc a bitmask of the [[NML:Cargos#Cargo_classes|cargo classes]] of the target cargo type. Note that this callback may also be called when the vehicle does not exist yet, so the available variables are limited.
|}

The following callbacks all have an equivalent property. The property description applies here also, except where otherwise noted.

{| class="t"
! Name
! Available for
! In purchase menu?
! comment
|-
| loading_speed
| All
| No
|
|-
| speed
| All
| Yes, unless <code style="color:darkgreen">purchase_speed</code> is set separately
| Units are not (yet) available
|-
| cost_factor
| All
| Yes, only
|
|-
| running_cost_factor
| All
| Yes, unless <code style="color:darkgreen">purchase_running_cost_factor</code> is set separately
|
|-
| cargo_age_period
| All
| No
|
|-
| cargo_capacity
| All except aircraft
| Yes, unless <code style="color:darkgreen">purchase_cargo_capacity</code> is set separately
|
|-
| passenger_capacity
| Aircraft
| Yes, unless <code style="color:darkgreen">purchase_passenger_capacity</code> is set separately
|
|-
| mail_capacity
| Aircraft
| Yes, unless <code style="color:darkgreen">purchase_mail_capacity</code> is set separately
|
|-
| range
| Aircraft
| Yes, unless <code style="color:darkgreen">purchase_range</code> is set separately
|
|-
| visual_effect_and_powered
| Trains
| No
|
|-
| visual_effect
| Road Vehicles, Ships
| No
|
|-
| power
| Trains, Road Vehicles
| Yes, unless <code style="color:darkgreen">purchase_power</code> is set separately
| Units are not (yet) available
|-
| weight
| Trains, Road Vehicles
| Yes, unless <code style="color:darkgreen">purchase_weight</code> is set separately
| Units are not (yet) available
|-
| length
| Trains, Road vehicles
| No
|
|-
| tractive_effort_coefficient
| Trains, Road Vehicles
| Yes, unless <code style="color:darkgreen">purchase_tractive_effort_coefficient</code> is set separately
| Value range is 0 .. 255 instead of 0 .. 1.
|-
| bitmask_vehicle_info
| Trains
| No
|
|}

===Sprites in GUI===
{{ottdp|1.2|no|ottdrev=r23080}} Since OpenTTD r23080 you can use variable <code style="color:darkgreen">extra_callback_info1</code> to display different sprites in the GUI and on the map. Currently these cases are available:
{| |-
! Lowest byte of extra_callback_info1 !! Meaning
|-
| 0x00 || Vehicle is drawn in a viewport, i.e. on the map.
|-
| 0x01..0x0F || reserved
|-
| 0x10 || Vehicle is drawn in the depot GUI. <ref>OpenTTD also uses this value with the purchase-list chain (cargotype FF) to determine the gridsize in ship and aircraft depots.</ref>
|-
| 0x11 || Vehicle is drawn in the vehicle details GUI. (This includes the refit GUI.)
|-
| 0x12 || Vehicle is drawn in the vehicle list.
|-
| 0x13..0x1F || reserved for other future GUIs.
|-
| 0x20 || Vehicle is drawn in the purchase list. (This includes the autoreplace GUI.)
|-
| 0x21 || Vehicle is drawn in the exclusive preview GUI or in the advertisement news.
|-
| 0x22..0x2F || reserved for other future GUIs with non-purchased vehicles.
|-
| 0x30..0xFF || reserved
|}
<references/>
The other bytes of variable <code style="color:darkgreen">extra_callback_info1</code> are reserved, and must be masked.
The cases 0x20..0x2F are called using the <code style="color:darkgreen">purchase</code>-callback, the other cases are called for the <code style="color:darkgreen">default</code>- or cargo-specific callbacks. Exception is the the special depot-gridsize call, which uses the <code style="color:darkgreen">purchase</code>-callback.

===Sound events===

{| class="t"
! Event
! Description
|-
| SOUND_EVENT_START
| Vehicle leaves station or depot, plane takes off
|-
| SOUND_EVENT_TUNNEL
| Vehicle enters tunnel
|-
| SOUND_EVENT_BREAKDOWN
| Vehicle breaks down (not for planes)
|-
| SOUND_EVENT_RUNNING
| Once per engine tick, but no more than once per vehicle motion
|-
| SOUND_EVENT_TOUCHDOWN
| Aircraft touches down
|-
| SOUND_EVENT_VISUAL_EFFECT
| Visual effect is generated (steam plume, diesel smoke, electric spark)
|-
| SOUND_EVENT_RUNNING_16
| Every 16 engine ticks if in motion
|-
| SOUND_EVENT_STOPPED
| Every 16 engine ticks if stopped
|-
| SOUND_EVENT_LOAD_UNLOAD
| Consist loads or unloads cargo
|}

NML:Getting started

2012-07-24T17:46:25Z

Hirundo: Update list of command-line options

{{NMLNavNoSubpages}}

NML is a a python-based compiler, capable to compile NML files (along with their associated language, sound and graphic files) into grf and / or nfo files. Windows users can install the [http://bundles.openttdcoop.org/nml/nightlies/LATEST/ windows binary] which contains a binary which bundles all required libraries. Users on other OS need to install them separately, best by means of their packet manager. In order to work, the following items are required:

* '''python'''
** any version from 2.5 through 2.7 will do, but not 3.x
** downloadable from from http://www.python.org/)
** Advise for windows users: apparently you can prevent a lot of problems by installing the 32bit version of python, even if you have a 64bit windows installation. Installing PIL might be troublesome if you do install the 64bit version of python.
* '''python image library'''
** downloadable from http://www.pythonware.com/products/pil/
* '''ply'''
** downloadable from http://www.dabeaz.com/ply/
* '''NML itself'''
** the latest (nightly) build can be downloaded from http://bundles.openttdcoop.org/nml/nightlies/LATEST/

If you don't install these with the packet manager of your choice (or there is none like on windows and you don't use the pre-compiled binary file), you should install these libraries as well as NML itself using <code style="color:darkgreen">python setup.py install</code> from your command prompt.

OS X users have two choices: install the dependencies manually as described above, for use with the python version that ships with OS X. Or install everything from macports, including a new python version (using macports eases upgrading). However using macports to install the dependencies for the bundled system python is likely to fail.

To verify that everything is installed, enter <code style="color:darkgreen">nmlc --version</code> in your command line. This should output the version of NML as well as the version of the installed libraries.

Examples for small NML "projects" are found in the <code style="color:darkgreen">examples</code> and <code style="color:darkgreen">regression</code> folder of NML. Generally it's assumed that the language files are in a separate language folder <code style="color:darkgreen">lang</code>, thus a simple project may look like this:

mynewgrf.nml
graphics.png
funny_sound.wav

lang/english.lng

The compiler itself <code style="color:darkgreen">nmlc</code> is a command line tool and can take a number of parameters, at least the nml filename which it shall process, e.g. <code style="color:darkgreen">nmlc mynewgrf.nml</code> will compile your nml file into the grf-file <code style="color:darkgreen">mynewgrf.grf</code>.

The full syntax is:

Usage: nmlc [options] <filename>
Where <filename> is the nml file to parse

Options:
--version show program's version number and exit
-h, --help show this help message and exit
-d, --debug write the AST to stdout
-s, --stack Dump stack when an error occurs
--grf=<file> write the resulting grf to <file>
--md5=<file> Write an md5sum of the resulting grf to <file>
--nfo=<file> write nfo output to <file>
-M output a rule suitable for make describing the
graphics dependencies of the main grf file (requires
input file or --grf)
--MF=<file> When used with -M, specifies a file to write the
dependencies to
--MT=<file> target of the rule emitted by dependency generation
(requires -M)
-c crop extraneous transparent blue from real sprites
-u save uncompressed data in the grf file
--nml=<file> write optimized nml to <file>
-o <file>, --output=<file>
write output(nfo/grf) to <file>
-t <file>, --custom-tags=<file>
Load custom tags from <file> [default:
custom_tags.txt]
-l <dir>, --lang-dir=<dir>
Load language files from directory <dir> [default:
lang]
--default-lang=<file>
The default language is stored in <file> [default:
english.lng]
--start-sprite=<num> Set the first sprite number to write (do not use
except when you output nfo that you want to include in
other files)
-p <palette>, --palette=<palette>
Force nml to use the palette <pal> [default: ANY].
Valid values are 'DOS', 'WIN', 'ANY'
--quiet Disable all warnings. Errors will be printed normally.
-n, --no-cache Disable caching of sprites in .cache[index] files,
which may reduce compilation time.

== Installing manually ==
We assume that you have a python setup (2.5 ... 2.7) where the distutils are available so that setup.py can be executed. You'll additionally need a gcc compiler in your path. On linux it is strongly recommended to use your package manager to install these packages.

=== Install PLY ===
This is easy. Get the library from the link as mentioned above.
Install it from the unpacked PLY directory via
sudo python setup.py install

=== Install the Python Imaging Library (PIL) ===
Get the library from the above mentioned link (the source kit for PIL 1.1.7). From the PIL source directory, test the setup for all available dependencies:
python setup.py build_ext -i
You should get an output like which concludes with a summary of the available dependencies:
PIL 1.1.7 SETUP SUMMARY
--------------------------------------------------------------------
--- TKINTER support available
--- JPEG support available
--- ZLIB (PNG/ZIP) support available
--- FREETYPE2 support available
--- LITTLECMS support available
--------------------------------------------------------------------
If you're missing zlib or jpeg support, install those libraries, too.

If that build shows everything available, test the setup:
python selftest.py
A successful selftest will result in
--------------------------------------------------------------------
PIL 1.1.7 TEST SUMMARY
--------------------------------------------------------------------
Python modules loaded from ./PIL
Binary modules loaded from ./PIL
--------------------------------------------------------------------
--- PIL CORE support ok
--- TKINTER support ok
--- JPEG support ok
--- ZLIB (PNG/ZIP) support ok
--- FREETYPE2 support ok
--- LITTLECMS support ok
--------------------------------------------------------------------
Running selftest:
--- 57 tests passed.
If all is successful, finally install the library:
sudo python setup.py install

=== Install NML ===
Now, that you have installed ply and pil, then you can install NML from the unpacked nml directory:
sudo python setup.py install

NML:Houses

2012-07-22T21:18:37Z

Hirundo: Restore navbar as well

NML:Houses

2012-07-22T21:17:16Z

Hirundo: Restore accidentally removed callback information

==House properties==

{| class="t"
! property
! value range
! comment
|-
| name
| string
| for example string(STR_NAME_EIFFEL_TOWER)
|-
| substitute
| 0 ... 109
| Number of the default house that replaces this one, if this house 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 ... 109
| id of the default house which this house replaces. This will cause your house to be placed instead of the default house. This is ignored, if the default house has already been overridden. You can define this property multiple times
|-
| building_flags
| bitmask(HOUSE_FLAG_XXX,...)
|
;HOUSE_FLAG_SIZE_1x1
;HOUSE_FLAG_SIZE_2x1
;HOUSE_FLAG_SIZE_1x2
;HOUSE_FLAG_SIZE_2x2
;HOUSE_FLAG_NOT_SLOPED
:Can only be built on flat terrain
;HOUSE_FLAG_ANIMATE
:Enable animation
;HOUSE_FLAG_CHURCH
:House is a church
;HOUSE_FLAG_STADIUM
:House is a stadium
;HOUSE_FLAG_ONLY_SE
:Can only be built in the scenario editor
;HOUSE_FLAG_PROTECTED
:Will not be removed by the game
;HOUSE_FLAG_SYNC_CALLBACK
:Callbacks for tiles are synchronised
;HOUSE_FLAG_RANDOM_ANIMATION
:Enable random animation
|-
| population
| 0 ... 255
| number of inhabitants the building adds to the town, if present
|-
| mail_multiplier
| 0 ... 255
|
|-
| pax_acceptance
| 0 ... 1
| Can be increased in steps of 0.125. A station accepts a cargo, if the combined acceptance of all houses in range is at least 1.
|-
| mail_acceptance
| 0 ... 1
|
|-
| cargo_acceptance
| 0 ... 1
| Like passenger acceptance. Additionally flag can be added which defines one of the cargo type
;HOUSE_ACCEPT_GOODS
;HOUSE_ACCEPT_FOOD
;HOUSE_ACCEPT_FIZZY_DRINKS
:FIZZY_DRINKS has in toyland the same meaning as FOOD in other climates.
|-
| accepted_cargo
|
| up to three cargo labels, e.g. MAIL, PASS, COAL
|-
| local_authority_impact
| 0 ... 65525
| amount of happiness increase of the city council, if the building is destroyed
|-
| removal_cost_multiplier
| 0 ... 255
|
|-
| probability
| 0 ... 16 (float)
| Probability with respect to the default houses (=1). Mind that these are relative probabilities with respect to all houses defined. If all probabilities are defined as 16, they'll all have the same probability as if they had all a probability of 1.
|-
| years_available
| array of two int
| [xx, yy] where xx and yy indicate the introduction year and the last year the building can be built
|-
| minimum_lifetime
| 0 ... 255
| number of years the building will remain at least
|-
| availability_mask
|
[bitmask([[NML:List of town zones|town zones]]), bitmask(CLIMATE_XXX, ...)]
|
An array with two bitmasks, the first bitmask is a mask of town zones where this house is available. The second bitmask is a mask of climates combined with the special value ABOVE_SNOWLINE which you need to set for houses available in the arctic climate above the snowline. Examples:

* Available in the centre town zone in toyland only: <code>[bitmask(TOWNZONE_CENTRE), bitmask(CLIMATE_TOYLAND)]</code>
* Available in all town zones in the arctic climate both above and below the snowline: <code>[ALL_TOWNZONES, bitmask(CLIMATE_ARCTIC, ABOVE_SNOWLINE)]</code>
* Available everywhere except on the town edge: <code>[ALL_TOWNZONES & ~bitmask(TOWNZONE_EDGE), ALL_CLIMATES | bitmask(ABOVE_SNOWLINE)</code>
|-
| callback_flags
| bitmask(HOUSE_CBF_XX)
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| random_colours
| array of 4, each COLOUR_XXX
|
colour values in an array, refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for a list of possible values.
|-
| refresh_multiplier
| 0 ... 63
| Defines the frequency with which the tile will be re-randomized which has an impact for random animation.
|-
| animation_info
| Array [ANIMATION_XXX, frame-count]
|
Type of animation and its length (1...128 frames):

;ANIMATION_LOOPING
;ANIMATION_NON_LOOPING
|-
| animation_speed
| 2 ... 16
|
Speed of animation, see [[NML:Animation speed|animation speed table]] for the meaning of the values.
|-
| building_class
| 0 .. 255
| An arbitrary number. You can check for the presence of buildings of the same class when building new buildings or using animation
|
|-
| watched_cargo_types
| array of values from your [[NML:Cargotable|cargo table]]
| {{ottdp|1.2|2.6|ottdrev=r23072|ttdprev=r1677}}List of cargo types to watch, to be used with the <code style:darkgreen>watched_cargo_accepted</code> callback.
|}
==House variables==

House variables are not yet implemented in NML

==House callbacks==

{| class="t"
! callback
! return value
! comment
|-
| default
| Sprite layout
| Graphics for the house tile
|-
| random_trigger
| N/A
|
See [[NML:Random switch|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. <code>extra_callback_info1</code> contains random bits, if enabled in the <code>special_flags</code> property. Returning a sound effect in the high byte will cause that sound effect to be played.
|-
| anim_control
| Next animation frame or CB_RESULT_XXX
| Called every 256 ticks. 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. <code>extra_callback_info1</code> contains random bits, if enabled in the <code>building_flags</code> property. Returning a sound effect in the high byte will cause that sound effect to be played.
|-
| construction_anim
| Same as <code>anim_control</code>
| Works the same as the <code>anim_control</code> callback, except that it's called when the construction state changes.
|-
| watched_cargo_accepted
| Same as <code>anim_control</code>
| Works the same as the <code>anim_control</code> callback, except that it's called when one of the watched cargo types is accepted.
|-
| 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 <code>accepted_cargo</code> 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 the acceptance properties are used instead. Cargo types are from the <code>cargo_type_accept</code> callback, or the <code>accepted_cargo</code> 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.
|-
| cargo_production
| (cargo_type * 256) + amount
| Called every 256 ticks. Called multiple times until 0x20FF is returned. The high byte of the result contains a cargo type, the low byte contains the amount of that cargo to produce. <code>extra_callback_info1</code> contains the number of iterations so far, <code>extra_callback_info2</code> contains random bits.
|-
| 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.
|-
| name
| String
| Name of the building (when using tile query tool)
|-
| colour
| Palette number
|
Used to recolour the building. See here [[NML:List of default colour translation palettes|here]] for an overview of default palettes.
|-
| construction_check
| 0 or 1
| Return 1 to allow building the house or 0 to disallow.
|-
| destruction
| 0 or 1
| Called periodically. Return 0 to keep the building or 1 to destroy it.
|-
| protection
| 0 or 1
| Return 0 to allow destruction, or 1 to disallow
|}

NML:Vehicles

2012-07-22T16:12:09Z

Hirundo: /* Sprites in GUI */ depot grid size

{{NMLNavPropVarCB}}

==Properties common to all vehicle types==

{| class="t"
! property
! value range
! available for articulated vehicle
! comment
|-
| <code style="color:green">name</code>
| (string)
| yes
| for example <code style="color:darkgreen">string(STR_NAME_HEREFORD_TRAM)</code>
|-
| <code style="color:green">climates_available</code>
| bitmask(CLIMATE_XXX, CLIMATE_YYY, ...)
| set to <code style="color:green">NO_CLIMATE</code>
|
;CLIMATE_TEMPERATE
;CLIMATE_ARCTIC
;CLIMATE_TROPICAL
;CLIMATE_TOYLAND
;NO_CLIMATE
:Vehicle is availble in no climate (e.g. for articulated parts)
;ALL_CLIMATES
:Vehicle is available irrespective of climate

To make a vehicle available in all climates except toyland you could use: <code style="color:green">ALL_CLIMATES & ~bitmask(CLIMATE_TOYLAND)</code>.
|-
| <code style="color:green">introduction_date</code>
| <code style="color:green">date</code>(yyyy,mm,dd)
| no
| Valid range for yyyy is 0 ... 5000000. In TTDPatch, dates after 2044 will be limited to 2044. Unless the engine is introduced within two years after game-start (always 1920 in TTDPatch), a random number of days between 0 and 511 will be added to this.
|-
| <code style="color:green">model_life</code>
| 0 ... 254 (years) or <code style="color:green">VEHICLE_NEVER_EXPIRES</code>
| no
|
Number of years a model is "supported" by the manufacturer, see [[#Engine life cycle|below]].
|-
| <code style="color:green">retire_early</code>
| -128 ... 127 (years)
| no
|
Retire the vehicle (make it unavailable in the purchase menu) this many years before reliability starts dropping, see [[#Engine life cycle|below]]. May be negative.
|-
| <code style="color:green">vehicle_life</code>
| 0 ... 255 (years)
| no
| Life length of an individual vehicle, before it is considered too old and in need of replacement.
|-
| <code style="color:green">reliability_decay</code>
| 0 ... 255
| no
| Default vehicles use 20. The higher the value the faster reliability decays, the more frequent service is needed. 0 means reliability never decreases if the vehicle is not too old
|-
| <code style="color:green">refittable_cargo_classes</code>
|
bit set of [[NML:Cargos#Cargo classes|cargo classes]]
| yes
| for example: <code style="color:darkgreen">bitmask(CC_BULK, CC_COVERED)</code>
|-
| <code style="color:green">non_refittable_cargo_classes</code>
|
bit set of [[NML:Cargos#Cargo classes|cargo classes]]
| yes
| for example: <code style="color:darkgreen">bitmask(CC_OVERSIZED, CC_SPECIAL)</code>
|-
| <code style="color:green">refittable_cargo_types</code>
| bit mask of entries into the cargo translation table
| yes
| As of NML 0.3, do not use this. Use cargo_[dis]allow_refit (see below) instead.
|-
| <code style="color:green">cargo_allow_refit</code>
| Array of cargo labels from the [[NML:Cargotable|cargotable]]
| Yes
| {{ottdp|1.2|no|ottdrev=r23291}} A list of cargo types to allow refitting to, irrespective of cargo classes. Example: <code style="color:darkgreen">[COAL, IORE]</code>
|-
| <code style="color:green">cargo_disallow_refit</code>
| Array of cargo labels from the [[NML:Cargotable|cargotable]]
| Yes
| {{ottdp|1.2|no|ottdrev=r23291}} A list of cargo types to disallow refitting to, irrespective of cargo classes. Example: <code style="color:darkgreen">[MAIL]</code>
|-
| <code style="color:green">loading_speed</code>
| 0 ... 255 (cargo units)
| yes
| Units of cargo loaded per time unit. Default vehicles use 5 for trains and road vehicles, 10 for ships and 20 for aircraft. This amount of cargo is loaded to or unloaded from the vehicle every 40 ticks for trains, every 20 ticks for road vehicles and aircraft and every 10 ticks for ships.
|-
| <code style="color:green">cost_factor</code>
| 0 ... 255
| Set to 0
| multiplier to the base purchase cost
|-
| <code style="color:green">running_cost_factor</code>
| 0 ... 255
| Set to 0
| multiplier to the base running costs
|-
| <code style="color:green">cargo_age_period</code>
| 0 ... 65535
| yes
|
{{ottd|1.2|r22713}} This property specifies after how many ticks cargo is aged. Default value is 185. 74 ticks is equal to 1 day.
|}

===Refittability===

To determine whether your vehicle can be refitted to a certain cargo, OpenTTD uses the following table

{| class="t"
! Cargo matches refittable_cargo_classes
! Cargo matches non_refittable_cargo_classes
! Cargo in cargo_allow_refit
! Cargo in cargo_disallow_refit
! Result
|-
| Yes
| No
| Doesn't matter
| No
| Refittable
|-
| No
| Doesn't matter
| No
| Doesn't matter
| Not refittable
|-
| Doesn't matter
| Doesn't matter
| Yes
| No
| Refittable
|-
| Doesn't matter
| Doesn't matter
| Doesn't matter
| Yes
| Not refittable
|}

For those that prefer boolean logic, the formula is as follows:

refittable = ((cargo classes in refittable_cargo_classes AND NOT cargo classes in non_refittable_cargo_classes) OR cargo in cargo_allow_refit) AND NOT (cargo in cargo_disallow_refit)

In general, you should use refittable_cargo_classes and non_refittable_cargo_classes to decide to which cargos your vehicle is refittable, and only then use cargo_allow_refit and cargo_disallow_refit to allow/disallow specific cargos.

===Engine life cycle===

The life cycle of a vehicle model consists of three phases, as outlined in the following table.

{| class="t"
! phase
! duration
! reliability
|-
| 1
| 7 to 38 months
| increases from 48-73% to 75-100%
|-
| 2
| <code style="color:darkgreen">model_life</code> - 8 years
| stays constant at peak, 75-100%
|-
| 3
| 10 to 20.5 years
| decreases from peak to 25-50%
|}

If <code style="color:darkgreen">model_life</code> is set to <code style="color:darkgreen">VEHICLE_NEVER_EXPIRES</code>, the engine remains in phase 2 forever.

Normally, the vehicle is removed from the purchase menu at the and of phase 3. However if you set the <code style="color:darkgreen">retire_early</code> property, it will be retired this many years before (or after, if the value is negative) the end of phase 2.

==Sorting vehicles in the purchase list==
This is a special property that is not encoded in an item/property-block like most other properties but it has it's own block instead. The syntax is as follows:

sort(<feature>, [<ID>, <ID>, <ID>...]);

The engines will be sorted in the given order on the position where originally the first element was. Say the original engine sorting is this: A B C D E and you use this code <code style="color:darkgreen">sort(FEAT_TRAINS, [D, B, A]);</code> the final sorting will be this: C D B A E

==Train properties==

{| class="t"
! property
! value range
! available for articulated vehicle
! comment
|-
| <code style="color:green">sprite_id</code>
| <code style="color:green">SPRITE_ID_NEW_TRAIN</code>
| yes
| Set this property to enable new graphics
|-
| <code style="color:green">speed</code>
| 0 ... 65000 (float, speed units)
| no
| Max speed for engines, speed limit for wagons
|-
| <code style="color:green">misc_flags</code>
| bitmask(TRAIN_FLAG_XXX, ...)
| FLIP should not be set, TILT and MU TO the same value as the 1st part
|
;TRAIN_FLAG_TILT
: enable the tilt bonus (20% speed in curves, if all vehicles in consist have it set)
;TRAIN_FLAG_2CC
:Enable use of the 2nd company colour
;TRAIN_FLAG_MU
:act as multiple unit (used for livery selection only)
;TRAIN_FLAG_FLIP
:Allow vehicle to be flipped (reversed) in depot
;TRAIN_FLAG_AUTOREFIT
:Allow autoreffitting. To enable autorefit, furthermore the [[#Vehicle callbacks|refit_cost]]-callback has to allow it, or else (if this callback is not implemented or fails) the <code style="color:green">refit_cost</code>-property (see below) must be set to 0.
|-
| <code style="color:green">refit_cost</code>
| 0 ... 255
| yes
| in 50% units of the purchase price cost base
|-
| <code style="color:green">callback_flags</code>
| bitmask(VEH_CBF_XXX, ...)
| yes
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| <code style="color:green">track_type</code>
| item from railtypetable
| must be the same as front
| Default railtype table: RAIL, MONO, MGLV. If you install a railtypetable yourself you'll always get the railtype you specified. If you want a vehicle to run on electric rail and you don't have a railtypetable, set <code style="color:green">track_type</code> to RAIL and make sure that you set <code style="color:green">engine_class</code> to <code style="color:green">ENGINE_CLASS_ELECTRIC</code>.
|-
| <code style="color:green">ai_special_flag</code>
| [<code style="color:green">AI_FLAG_PASSENGER</code> <nowiki>|</nowiki> <code style="color:green">AI_FLAG_CARGO</code>]
| no
|
;<code style="color:green">AI_FLAG_PASSENGER</code>
:Tell computer players that it's an engine that should only be used for passenger service.
|-
| <code style="color:green">power</code>
| 0 ... 65000 hp (float, power units)
| Set to 0
|
|-
| <code style="color:green">running_cost_base</code>
| RUNNING_COST_XXX
| Set to RUNNING_COST_NONE
|
;RUNNING_COST_STEAM
;RUNNING_COST_DIESEL
;RUNNING_COST_ELECTRIC
;RUNNING_COST_ROADVEH
;RUNNING_COST_NONE
:no running costs
|-
| <code style="color:green">dual_headed</code>
| [0 <nowiki>|</nowiki> 1]
| Set to 0 for all parts of an articulated vehicle
| 1 = dual_headed, otherwise normal engine
|-
| <code style="color:green">default_cargo_type</code>
| An identifier from the [[NML:Cargotable|cargo table]], or DEFAULT_CARGO_FIRST_REFITTABLE
| Yes
| If the vehicle is refittable to at least one cargo, but the chosen default cargo is not available or is set to DEFAULT_CARGO_FIRST_REFITTABLE, then the first refittable cargo is used. The first refittable is chosen according to the order in your [[NML:Cargotable|cargo table]]. If this property is set to a valid cargo but the vehicle cannot refit to any cargo type, then the vehicle will be able to carry only this cargo, but it cannot be refitted (like e.g. the default train wagons).
|-
| <code style="color:green">cargo_capacity</code>
| 0 .. 255
| yes
| By default, passenger capacity is 4x, and mail/goods capacity 2x larger than capacity for other cargoes. The capacity set here is used for the default (i.e. first refittable) cargo. Use the <code style="color:green">cargo_capacity</code> callback to avoid this effect.
|-
| <code style="color:green">weight</code>
| 0 .. 1279 ton (float, mass units)
| Set to 0
|
|-
| <code style="color:green">ai_engine_rank</code>
| 0 ... 255
| no
| TTDPatch only: Higher values make the engine for the TTDPatch AI more attractive
|-
| <code style="color:green">engine_class</code>
| ENGINE_CLASS_XXX
| no
|
Defines which livery colour settings apply to the vehicle
;ENGINE_CLASS_STEAM
;ENGINE_CLASS_DIESEL
;ENGINE_CLASS_ELECTRIC
;ENGINE_CLASS_MONORAIL
;ENGINE_CLASS_MAGLEV
|-
| <code style="color:green">extra_power_per_wagon</code>
| 0 ... 65000 hp (float, power units)
| Set to 0
| Only wagons with a livery override for this engine will add power
|-
| <code style="color:green">tractive_effort_coefficient</code>
| 0 ... 1 (float)
| Set to 0
| Fraction of the vehicle weight that is available as tractive effort. Tractive effort (in kN) is calculated as (TE coefficient) * 10 * weight (in tons), with 10 being an approximation of the acceleration of gravity (9.81 m/s). Default value is 0.3.
|-
| <code style="color:green">air_drag_coefficient</code>
| 0 ... 1 (float)
| Set to 0
| Coefficient of the relative air drag, in arbitrary units. The default value is approximately (8 / max_speed), with max_speed in km/h, clamped to the range 0.004 .. 0.75.
|-
| <code style="color:green">length</code>
| 1 ... 8
| yes
| Length of the vehicle in arbitrary units. Use a value of 8 (equal to the predefined constant VEHICLE_LENGTH) for a full-length vehicle.
|-
| <code style="color:green">visual_effect_and_powered</code>
| <code style="color:green">visual_effect_and_powered</code> (VISUAL_EFFECT_XXX, offset, <code style="color:green">ENABLE_WAGON_POWER</code> or <code style="color:green">DISABLE_WAGON_POWER</code>)
| yes
|
Set the type of visual effect for the vehicle and its positional offset with respect to the vehicle. An offset of 0 is default, negative values mean more to the front and positive values are backwards. Minimum offset is -8, maximum is 7.

;VISUAL_EFFECT_DEFAULT
:No effect, unless for the default vehicles
;VISUAL_EFFECT_STEAM
:Steam like from steam engine
;VISUAL_EFFECT_DIESEL
:Steam from internal combustion engine
;VISUAL_EFFECT_ELECTRIC
:Electric sparks
;VISUAL_EFFECT_DISABLE
:No effect
|-
| <code style="color:green">extra_weight_per_wagon</code>
| 0 ... 255 ton (float, mass units)
| Set to 0
| Adds extra weight for powered wagons, see <code style="color:green">extra_power_per_wagon</code>
|-
| <code style="color:green">bitmask_vehicle_info</code>
| 8-bit bitmask
| yes
|
Used for obtaining [[#bitmask consist info|<code style="color:green">bitmask_consist_info</code>]]
|}

==Road vehicle properties==

{| class="t"
! property
! value range
! available for articulated vehicle
! comment
|-
| sprite_id
| SPRITE_ID_NEW_ROADVEH
| yes
| Set this property to enable new graphics
|-
| speed
| 0 ... 514km/h (float, speed units)
| no
|
|-
| misc_flags
| bitmask(ROADVEH_FLAG_XXX, ...)
| partly; tram flag must the same
|
;ROADVEH_FLAG_TRAM
:The vehicle requires tram tracks to run on
;ROADVEH_FLAG_2CC
:Enable 2nd company colour
;ROADVEH_FLAG_AUTOREFIT
:Allow autorefitting. To enable autorefit, furthermore the [[#Vehicle callbacks|refit_cost]]-callback has to allow it, or else (if this callback is not implemented or fails) the <code style="color:green">refit_cost</code>-property (see below) must be set to 0.
|-
| refit_cost
| 0 ... 255
| yes
| in 25% units of the purchase price cost base
|-
| callback_flags
| bitmask(VEH_CBF_XXX, ...)
| yes
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| running_cost_base
| RUNNING_COST_XXX
| set to RUNNING_COST_NONE
|
;RUNNING_COST_STEAM
;RUNNING_COST_DIESEL
;RUNNING_COST_ELECTRIC
;RUNNING_COST_ROADVEH
;RUNNING_COST_NONE
:no running costs
|-
| power
| 0 ... 2550hp (float, power units)
| Set to 0
|
|-
| weight
| 0 ... 63.75ton (float, mass units)
| Set to 0
|
|-
| tractive_effort_coefficient
| 0 ... 1 (float)
| Set to 0
| Fraction of the vehicle weight that is available as tractive effort. Tractive effort (in kN) is calculated as (TE coefficient) * 10 * weight (in tons), with 10 being an approximation of the acceleration of gravity (9.81 m/s). Default value is 0.3.
|-
| air_drag_coefficient
| 0 ... 1 (float)
| Set to 0
| Coefficient of the relative air drag, in arbitrary units. The default value is approximately (8 / max_speed), with max_speed in km/h, clamped to the range 0.004 .. 0.75.
|-
| <code style="color:green">default_cargo_type</code>
| An identifier from the [[NML:Cargotable|cargo table]], or DEFAULT_CARGO_FIRST_REFITTABLE
| Yes
| If the vehicle is refittable to at least one cargo, but the chosen default cargo is not available or is set to DEFAULT_CARGO_FIRST_REFITTABLE, then the first refittable cargo is used. The first refittable is chosen according to the order in your [[NML:Cargotable|cargo table]]. If this property is set to a valid cargo but the vehicle cannot refit to any cargo type, then the vehicle will be able to carry only this cargo, but it cannot be refitted (like e.g. the default train wagons).
|-
| cargo_capacity
| 0 ... 255
| yes
| By default, passenger capacity is 4x, and mail/goods capacity 2x larger than capacity for other cargoes. The capacity set here is used for the default (i.e. first refittable) cargo. Use the <code style="color:green">cargo_capacity</code> callback to avoid this effect.
|-
| sound_effect
| SOUND_XXX
| no
|
See available [[NML:List of sound effects|sound effects]].
|-
| visual_effect
| visual_effect( VISUAL_EFFECT_XXX, offset)
| yes
|
Set the type of visual effect for the vehicle and its positional offset with respect to the vehicle. An offset of 0 is default, negative values mean more to the front and positive values are backwards. Minimum offset is -8, maximum is 7.

;VISUAL_EFFECT_DEFAULT
:No effect, unless for the default vehicles
;VISUAL_EFFECT_STEAM
:Steam like from steam engine
;VISUAL_EFFECT_DIESEL
:Steam from internal combustion engine
;VISUAL_EFFECT_ELECTRIC
:Electric sparks
;VISUAL_EFFECT_DISABLE
:No effect
|-
| length
| 1 ... 8
| yes
| Length of the vehicle in arbitrary units. Use a value of 8 (equal to the predefined constant VEHICLE_LENGTH) for a full-length vehicle.
|}

==Ship properties==

{| class="t"
! property
! value range
! comment
|-
| sprite_id
| SPRITE_ID_NEW_SHIP
| Set this property to enable new graphics
|-
| speed
| 0 ... 127 km/h (float, speed units)
|
|-
| misc_flags
| bitmask(SHIP_FLAG_XXX)
| Bitmask with to possible flags, set to 0 to disable both.

;SHIP_FLAG_2CC
:Enable use of the 2nd company colour
;SHIP_FLAG_AUTOREFIT
:llow autorefitting. To enable autorefit, furthermore the [[#Vehicle callbacks|refit_cost]]-callback has to allow it, or else (if this callback is not implemented or fails) the <code style="color:green">refit_cost</code>-property (see below) must be set to 0.
|-
| refit_cost
| 0 ... 255
| in 1/32 of the default refit cost base
|-
| callback_flags
| bitmask(VEH_CBF_XXX, ...)
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| is_refittable
| [0 <nowiki>|</nowiki> 1]
| 0=false, 1=true. Note: if you do not set this property to 1, then refittable_cargo_classes / non_refittable_cargo_classes have no effect.
|-
| <code style="color:green">default_cargo_type</code>
| An identifier from the [[NML:Cargotable|cargo table]], or DEFAULT_CARGO_FIRST_REFITTABLE
| If the vehicle is refittable to at least one cargo, but the chosen default cargo is not available or is set to DEFAULT_CARGO_FIRST_REFITTABLE, then the first refittable cargo is used. The first refittable is chosen according to the order in your [[NML:Cargotable|cargo table]]. If this property is set to a valid cargo but the vehicle cannot refit to any cargo type, then the vehicle will be able to carry only this cargo, but it cannot be refitted (like e.g. the default train wagons).
|-
| cargo_capacity
| 0 ... 255
| For ships (unlike other vehicle types) the capacity set here is not affected by the cargo type.
|-
| sound_effect
| SOUND_XXX
|
See available [[NML:List of sound effects|sound effects]].
|-
| ocean_speed_fraction
| 0 ... 1 (float)
|
{{ottd|1.2|r22639}} fraction of base speed on ocean tiles (default: 1)
|-
| canal_speed_fraction
| 0 ... 1 (float)
|
{{ottd|1.2|r22639}} fraction of base speed on canal tiles (default: 1)
|-
| visual_effect
| visual_effect(VISUAL_EFFECT_XXX, offset)
| XXX=[DEFAULT <nowiki>|</nowiki> STEAM <nowiki>|</nowiki> DIESEL <nowiki>|</nowiki> ELECTRIC <nowiki>|</nowiki> DISABLE], it is the type of the visual effect you want for this ship. Default means no effect. Offset is the position of the effect. 0 is default, negative values mean more to the front and positive values are backwards. Minimum offset is -8, maximum is 7.
|}

==Aircraft properties==

{| class="t"
! property
! value range
! comment
|-
| sprite_id
| SPRITE_ID_NEW_AIRCRAFT
| Set this property to enable new graphics
|-
| speed
| 0 .. 3280 km/h (float, speed units)
|
|-
| range
| 0 .. 2894
| {{nml|0.3}} {{ottdp|1.2|no|ottdrev=r23504}} Maximum (euclidean) distance the aircraft can cover between two airports. Set to 0 for unlimited range.
|-
| misc_flags
| bitmask(AIRCRAFT_FLAG_2CC, AIRCRAFT_FLAG_AUTOREFIT)
| Bitmask with to possible flags, set to 0 to disable both.

;AIRCRAFT_FLAG_2CC
:Enable 2nd company colour
;AIRCRAFT_FLAG_AUTOREFIT
:Allow autorefitting. To enable autorefit, furthermore the [[#Vehicle callbacks|refit_cost]]-callback has to allow it, or else (if this callback is not implemented or fails) the <code style="color:green">refit_cost</code>-property (see below) must be set to 0.
|-
| refit_cost
| 0 ... 255
| in 1/32 of default refit cost base
|-
| callback_flags
| bitmask(VEH_CBF_XXX, ...)
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| aircraft_type
| AIRCRAFT_TYPE_XXX
|
;AIRCRAFT_TYPE_HELICOPTER
:Can land on helipad
;AIRCRAFT_TYPE_SMALL
:Can land on all airports with runway
;AIRCRAFT_TYPE_LARGE
:Can land on all airports with runway. But have a high crash chance on small airports
|-
| acceleration
| 0 ... 255
| In arbitrary units
|-
| passenger_capacity
| 0 ... 65536
| Capacity for the passenger compartment. See also the notes at <code style="color:darkgreen">mail_capacity</code> below.
|-
| mail_capacity
| 0 ... 255
| Capacity for the mail compartment, if refitted to a cargo in the CC_PASSENGERS class. When refitted to other cargoes, this capacity is added to the passenger capacity to determine the base capacity. The actual capacity is set to this base capacity divided by 1 for mail, 2 for goods and 4 for all other cargoes. To override this effect, use the <code style="color:darkgreen">passenger_capacity</code> and <code style="color:darkgreen">mail_capacity</code> callbacks.
|-
| sound_effect
| SOUND_XXX
|
See available [[NML:List of sound effects|sound effects]].
|}

==Vehicle variables==

Below an overview of all vehicle-specific variables. Not that in the purchase list, the vehicle is not built yet and as such many variables are not available. All general variables are available, refer to the table for info on vehicle-specific variables. Trying to access a non-available variable invokes undefined behaviour. Please note that while all variables are available for all vehicles types, some of them only make sense for one or more vehicle types. For example checking current_railtype for a non-rail vehicle doesn't make sense at all.

===Variables without parameter===

{| class="t"
! name
! value range
! available in purchase list?
! comment
|-
| position_in_consist
| 0 ... 255
| No
| The position of the current vehicle-part from the start of the vehicle. The engine will get value 0, the first wagon (or second engine) gets value 1, etc.
|-
| position_in_consist_from_end
| 0 ... 255
| No
| Same as position_in_consist but counted from the end. The last wagon will get value 0.
|-
| num_vehs_in_consist
| 1 ... 256
| No
| The total number of vehicles-parts in this vehicle. For aircraft this will include the shadow and the rotor.
|-
| position_in_vehid_chain
| 0 ... 255
| No
| See position_in_consist, but not of the complete vehicle but only all consecutive parts with the same id.
|-
| position_in_vehid_chain_from_end
| 0 ... 255
| No
| See position_in_consist_from_end, but not of the complete vehicle but only all consecutive parts with the same id.
|-
| num_vehs_in_vehid_chain
| 1 ... 256
| No
| See num_vehs_in_consist, but not of the complete vehicle but only all consecutive parts with the same id.
|-
| cargo_classes_in_consist
| Bitmask of CC_XXX
| No
|
[[NML:Cargos#Cargo classes|cargo classes]]
|-
| most_common_refit
|
[[NML:Cargos#Cargo properties|cargo class]]
| No
| cargo class most often refit to
|-
| bitmask_consist_info
| Bitmask 8 bit
| No
|
Binary OR of the values of [[#bitmask vehicle info|bitmask_vehicle_info]] of all vehicles (engines, wagons) in the consist. Only available for rail vehicles.
|-
| company_num
| 0 ... 14
| Yes
| company number of the vehicle owner. TTDPatch only supports up to 8 companies (0 ... 7)
|-
| company_type
| PLAYERTYPE_XX
| Yes
|
;PLAYERTYPE_HUMAN
:human player
;PLAYERTYPE_AI
:AI player
;PLAYERTYPE_HUMAN_IN_AI
:human managing AI company
;PLAYERTYPE_AI_IN_HUMAN
:AI managing human company

OpenTTD only uses PLAYERTYPE_HUMAN and PLAYERTYPE_AI. If you cheat yourself to be part of an AI company OpenTTD will still report PLAYERTYPE_AI for the company with yourself and the AI and it'll report PLAYERTYPE_HUMAN for the now uncontrolled company.
|-
| company_colour1
| COLOUR_XXX
| Yes
|
Refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for possible values.
|-
| company_colour2
| COLOUR_XXX
| Yes
|
Same as company_colour1, if no 2nd company colour is chosen. Refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for possible values.
|-
| aircraft_height
| 0 ... 255
| No
| Height difference between the aircraft and its shadow. 8 Units are equivalent to one height level on the map.
|-
| airport_type
| AIRPORTTYPE_XX
| No
|
;AIRPORTTYPE_SMALL
;AIRPORTTYPE_LARGE
;AIRPORTTYPE_HELIPORT
;AIRPORTTYPE_OILRIG
|-
| curv_info_prev_cur
| -2 ... 2
| No
| Difference in direction between the previous (towards engine) vehicle and this vehicle. Curvature to the right is positive. 1 unit is 45 degrees.
|-
| curv_info_cur_next
| -2 ... 2
| No
| Difference in direction between this vehicle and the next (towards rear end) vehicle. Curvature to the right is positive. 1 unit is 45 degrees.
|-
| curv_info_prev_next
| -4 ... 4
| No
| Difference in direction between the previous (towards engine) and next (towards rear end) vehicle. Curvature to the right is positive. 1 unit is 45 degrees. Equal to <code style="color:darkgreen">curve_invo_prev_cur + curv_info_cur_next</code>.
|-
| curv_info
| vehicle_curv_info(''prev_cur'', ''cur_next'')''''
| No
|
Returns a magic number that represents the curvature state of the prev-cur-next vehicle triplet. Do not try to make sense of this magic number, use the [[NML:Builtin functions|builtin function]] <code style="color:darkgreen">vehicle_curv_info()</code> instead to make comparisons. <code style="color:darkgreen">curv_info == vehicle_curv_info(a, b)</code> is equivalent to <code style="color:darkgreen">(curv_info_prev_cur == a) && (curv_info_cur_next == b)</code>, however the former can easily be used in a switch-block.
|-
| motion_counter
| 0 ... 15
| Yes, always 0
| Is increased every time the vehicle moves a single step on the map. Useful for animations.
|-
| cargo_type_in_veh
| entry in cargo translation table
| Yes, for the default cargo
| 0xFF if not present in the table
|-
| cargo_unit_weight
| weight per unit in 1/16t
| Yes, for the default cargo
|
|-
| cargo_classes
| Bitmask of [[NML:Cargos#Cargo properties|cargo class]]
| Yes, for the default cargo
| class of the currently transported cargo
|-
| vehicle_is_available
| [0 <nowiki>|</nowiki> 1]
| Yes
| Value is 1 if the vehicle is available on the open market
|-
| vehicle_is_testing
| [0 <nowiki>|</nowiki> 1]
| Yes
| Value is 1 if the vehicle is currently being tested
|-
| vehicle_is_offered
| [0 <nowiki>|</nowiki> 1]
| Yes
| Value is 1 if the vehicle is currently being offered for exclusive preview
|-
| build_year
| 0 ... 5000000
| Yes
| 0-based year when the vehicle was built, current year if the vehicle is not built yet
|-
| direction
| DIRECTION_XX
| No
|
See [[NML:List of direction constants|here]] for an overview of possible values and their meaning.
|-
| cargo_capacity
| 0 ... 65535
| No
| Cargo capacity (number of units) of the vehicle
|-
| cargo_count
| 0 ... 65535
| No
| Number of cargo units of cargo in the vehicle
|-
| cargo_subtype
| 0 ... 255
| Yes, always 0
| Cargo subtype, used to provide more than one refit option for the same cargo type. See also the <code style="color:darkgreen">cargo_subtype_text</code> callback.
|-
| vehicle_is_powered
| [0 <nowiki>|</nowiki> 1]
| No
| Vehicle provides power and is on the correct track type
|-
| vehicle_is_not_powered
| [0 <nowiki>|</nowiki> 1]
| No
| Vehicle is either on a wrong track type or it doesn't provide power at all
|-
| vehicle_is_potentially_powered
| [0 <nowiki>|</nowiki> 1]
| No
| Vehicle provides power, if it is on a suitable track type
|-
| vehicle_is_reversed
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle has reversed an odd number of times
|-
| built_during_preview
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle was built during the exclusive preview stage
|-
| current_railtype
| No
| Entry from railtype translation table or 0xFF
| Don't use this variable unless you've defined a railtype translation table. If the train is running on a railtype that is not listed in your railtype translation table this variable will contain 0xFF. Available since OpenTTD r20164.
|-
| waiting_triggers
|
| No
|
Random triggers waiting to be matched. (see [[NML:Random switch|Random switch]])
|-
| random_bits
| 0 ... 255
| No
|
Random data that can be used to randomize certain descisions. (see [[NML:Random switch|Random switch]])
|-
| grfid
| 0 ... 0xFFFFFFFF
| No
|
GRFID that defined the [[NML:Graphics|graphics]]-block for this vehicle. To compare this with other grfids, use the [[NML:Builtin functions|builtin function]] <code style="color:darkgreen">str2number()</code> to convert the other GRFID to a number as well.
|-
| vehicle_type_id
| 0 ... 65535
| No
| GRF-local ID of the vehicle, equal to the item ID. Note that vehicles from other NewGRFs may have the same ID, so you'll generally have to check the <code style="color:darkgreen">grfid</code> as well.
|-
| vehicle_is_hidden
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle is hidden in a depot or tunnel.
|-
| vehicle_is_stopped
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle is stopped, or if it is braking for a stop (trains only).
|-
| vehicle_is_crashed
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle has crashed.
|-
| vehicle_is_broken
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle is broken down.
|-
| date_of_last_service
| date(year, month, day)
| No
|
|-
| breakdowns_since_last_service
| 0 ... 255
| No
| Number of breakdowns since the last service
|-
| reliability
| 0 ... 100
| No
| Reliability (percentage)
|-
| age_in_days
| 0 ... 65535
| No
| Vehicle age in days.
|-
| max_age_in_days
| 0 ... 65535
| No
| Maximum vehicle age in days.
|-
| current_speed
| (speed units)
| No
| The current speed of the vehicle in m/s
|-
| max_speed
| (speed units)
| No
| The maximum speed of the vehicle in m/s
|-
| current_max_speed
| (speed units)
| No
| {{nml|0.3}} {{ottdp|1.3|no|ottdrev=r24246}} Current maximum speed of the vehicle in m/s. This includes e.g. track or timetable limits. Only valid for front vehicle.
|-
| vehicle_is_in_depot
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle is inside a depot
|}

===Variables that require an argument===

{| class="t"
! name
! Argument
! value range
! available in purchase list?
! comment
|-
| count_veh_id
| The vehicle ID to look for.
| 0..255
| No
| The number of vehicles in the current consist that have the given ID.
|}

==Vehicle callbacks==
The following table contains a list of available vehicle callbacks. Additionally, it's possible to provide cargo-specific graphics, using the identifier from the [[NML:Cargotable|cargo table]] as callback name. These callbacks will be used if the vehicle is refitted to the corresponding cargo type. If no cargo-specific graphics match the cargo that the vehicle is carrying, the <code style="color:darkgreen">default</code> callback is used instead. Cargo-specific graphics callbacks are never called from the purchase menu, refer to the <code style="color:darkgreen">purchase</code> callback below instead.

Note that the above affects '''graphics only''', other callbacks are unaffected.

{| class="t"
! Name
! Available for
! In purchase menu?
! value range
! comment
|-
| default
| All
| Yes, unless <code style="color:darkgreen">purchase</code> is set separately
| Sprite group
| 'Normal' vehicle graphics, if no cargo-specific graphics apply. See also the section on [[#Sprites in GUI|GUI sprites]].
|-
| purchase
| All
| Yes, only
| Sprite group
| Graphics to show in the buy menu (only the horizontal view is needed, except for dual-headed trains. With the <code>dual_headed</code> property set, special rules for the purchase menu sprite apply: two sprites are drawn (for front and back) as if the vehicle is normally constructed. If you supply one purchase menu sprite, it will be used for both vehicle parts in the purchase menu. Provide a set of 8 sprites, and the 7th resp. 3rd sprite will be drawn; provide a set of 8 blank sprites except the 7th if you want to fully control a single purchase menu sprite for a dual-headed engine. ) See also the section on [[#Sprites in GUI|GUI sprites]].
|-
| rotor
| Aircraft (helicopters)
| No
| Sprite group
| Graphics for the helicopter rotor (4 sprites; 1 stopped and 3 moving)
|-
| random_trigger
| All
| No
| N/A
| See [[NML:Random switch|random switch]] for more information.
|-
| cargo_subtype_text
| All
| No
| String, or CB_RESULT_NO_TEXT
| With this callback, you can display extra text after the cargo in the vehicle information window. This callback is called during refitting, with succesively increased values of the <code style="color:darkgreen">cargo_subtype</code> variable, until the callback returns CB_RESULT_NO_TEXT. All returned strings are then displayed as refit options. The chosen refit option is saved in the <code style="color:darkgreen">cargo_subtype</code> variable, so it can be used later for other things. In the HEQS grf for example, this mechanism is used to let the user choose between different capacities of the same vehicle.
|-
| additional_text
| All
| Yes, only
| String
| Additional text to show in the purchase list.
|-
| colour_mapping
| All
| Yes, unless <code style="color:darkgreen">purchase_colour_mapping</code> is set separately
| Recolour sprite number
|
With this callback, you can use a different recolour sprite instead of the standard 1cc / 2cc company colour remappings. See [[NML:List of default colour translation palettes|here]] for a list of default palettes. See the [[NML:Builtin functions|builtin function]] <code style="color:darkgreen">reserve_sprites()</code> for info on how to allocate your own sprite. For performance, the result is cached and only updated if the <code style="color:darkgreen"> every_32_days</code> callback requires so. Add CB_RESULT_COLOUR_MAPPING_ADD_CC to the result to add the company colour to the sprites, this requires 16 (1cc) or 256 (2cc) sprites in total.
|-
| start_stop
| All
| No
| String or CB_RESULT_NO_TEXT
| Called when starting or stopping a vehicle. Mainly useful to prevent vehicles from leaving the depot unless a certain condition is met. Return CB_RESULT_NO_TEXT to allow or a string (containing an error message) to disallow starting/stopping.
|-
| every_32_days
| All
| No
| bitmask(CB_RESULT_32_DAYS_XXX, ...)
| Called every 32 days. Set CB_RESULT_32_DAYS_TRIGGER in the bitmask to trigger TRIGGER_VEHICLE_32_CALLBACK. Set CB_RESULT_32_DAYS_COLOUR_MAPPING in the bitmask to update the colour mapping by re-running the <code style="color:darkgreen">colour_mapping</code> callback.
|-
| sound_effect
| All
| No
| SOUND_XXX, sound("sound.wav"), import_sound(grfid, number) or CB_RESULT_NO_SOUND
|
Called to play various vehicle sounds. <code style="color:darkgreen">extra_callback_info1</code> contains the sound event, see the [[#Sound events|table]] below. Return SOUND_XXX (see [[NML:List_of_sound_effects|here]]) to return a default sound. <code style="color:darkgreen">sound("soundfile")</code> imports a sound from a .wav file. <code style="color:darkgreen">import_sound(grfid, number)</code> imports a sound from another grf. A failed (or not implemented) callback will cause the default sound to be played. Return CB_RESULT_NO_SOUND to play no sound at all.
|-
| articulated_part
| Trains, Road Vehicles
| Yes (no separate callback)
| Vehicle ID, or CB_RESULT_NO_MORE_ARTICULATED_PARTS
| With this callback, you can add articulated parts (e.g. tenders) to your vehicle. Called repeatedly, until CB_RESULT_NO_MORE_ARTICULATED_PARTS is returned. After each call, the returned vehicleID is added to your vehicle. <code style="color:darkgreen">extra_callback_info1</code> contains 1 during the first call, 2 during the second, etc. Note that callback may be called from the purchase list, using vehicle variables is not possible. Or CB_RESULT_REVERSED_VEHICLE to the returned vehicle ID to display the vehicle backwards.

For NML 0.2 and lower the vehicle ID of the articulated part must be in the range 0 .. 127.
|-
| can_attach_wagon
| Trains
| No
| String or CB_RESULT_ATTACH_XXX
| Called when a wagon is being attached, to allow or disallow attaching. This callback has to be defined at the engine. However, variables in the <code style="color:darkgreen">SELF</code> scope refer to the wagon being attached, the <code style="color:darkgreen">PARENT</code> scope refers to the engine that the wagon is being attached to. Return a string to disallow with the string as error message. Return CB_RESULT_ATTACH_DISALLOW to disallow with standard message ("incompatible railtypes"), CB_RESULT_ATTACH_ALLOW to allow or CB_RESULT_ATTACH_ALLOW_IF_RAILTYPES to allow if the railtypes match (default).
|-
| refit_cost
| {{ottdp|1.2|no|ottdrev=r23089}} All
| Yes
| -8192 .. 8191 as refit cost. Add <code style="color:darkgreen">CB_RESULT_AUTOREFIT</code> if you want to allow autorefit.
| When returning a negative value, encode the cost as (cost & <code style="color:darkgreen">CB_RESULT_REFIT_COST_MASK</code>) before (possibly) adding <code style="color:darkgreen">CB_RESULT_AUTOREFIT</code>. To allow autorefitting, the corresponding bit in the <code style="color:darkgreen">misc_flags</code> must be set as well. Variable <code style="color:darkgreen">extra_callback_info1</code> contains information about the target cargo type in the format 0xccccsstt, with tt being the new cargo type, ss the new cargo subtype (see <code style="color:darkgreen">cargo_subtype_text</code>-callback) and cccc a bitmask of the [[NML:Cargos#Cargo_classes|cargo classes]] of the target cargo type. Note that this callback may also be called when the vehicle does not exist yet, so the available variables are limited.
|}

The following callbacks all have an equivalent property. The property description applies here also, except where otherwise noted.

{| class="t"
! Name
! Available for
! In purchase menu?
! comment
|-
| loading_speed
| All
| No
|
|-
| speed
| All
| Yes, unless <code style="color:darkgreen">purchase_speed</code> is set separately
| Units are not (yet) available
|-
| cost_factor
| All
| Yes, only
|
|-
| running_cost_factor
| All
| Yes, unless <code style="color:darkgreen">purchase_running_cost_factor</code> is set separately
|
|-
| cargo_age_period
| All
| No
|
|-
| cargo_capacity
| All except aircraft
| Yes, unless <code style="color:darkgreen">purchase_cargo_capacity</code> is set separately
|
|-
| passenger_capacity
| Aircraft
| Yes, unless <code style="color:darkgreen">purchase_passenger_capacity</code> is set separately
|
|-
| mail_capacity
| Aircraft
| Yes, unless <code style="color:darkgreen">purchase_mail_capacity</code> is set separately
|
|-
| range
| Aircraft
| Yes, unless <code style="color:darkgreen">purchase_range</code> is set separately
|
|-
| visual_effect_and_powered
| Trains
| No
|
|-
| visual_effect
| Road Vehicles, Ships
| No
|
|-
| power
| Trains, Road Vehicles
| Yes, unless <code style="color:darkgreen">purchase_power</code> is set separately
| Units are not (yet) available
|-
| weight
| Trains, Road Vehicles
| Yes, unless <code style="color:darkgreen">purchase_weight</code> is set separately
| Units are not (yet) available
|-
| length
| Trains, Road vehicles
| No
|
|-
| tractive_effort_coefficient
| Trains, Road Vehicles
| Yes, unless <code style="color:darkgreen">purchase_tractive_effort_coefficient</code> is set separately
| Value range is 0 .. 255 instead of 0 .. 1.
|-
| bitmask_vehicle_info
| Trains
| No
|
|}

===Sprites in GUI===
{{ottdp|1.2|no|ottdrev=r23080}} Since OpenTTD r23080 you can use variable <code style="color:darkgreen">extra_callback_info1</code> to display different sprites in the GUI and on the map. Currently these cases are available:
{| |-
! Lowest byte of extra_callback_info1 !! Meaning
|-
| 0x00 || Vehicle is drawn in a viewport, i.e. on the map.
|-
| 0x01..0x0F || reserved
|-
| 0x10 || Vehicle is drawn in the depot GUI. <ref>OpenTTD also uses this value with the purchase-list chain (cargotype FF) to determine the gridsize in ship and aircraft depots.</ref>
|-
| 0x11 || Vehicle is drawn in the vehicle details GUI. (This includes the refit GUI.)
|-
| 0x12 || Vehicle is drawn in the vehicle list.
|-
| 0x13..0x1F || reserved for other future GUIs.
|-
| 0x20 || Vehicle is drawn in the purchase list. (This includes the autoreplace GUI.)
|-
| 0x21 || Vehicle is drawn in the exclusive preview GUI or in the advertisement news.
|-
| 0x22..0x2F || reserved for other future GUIs with non-purchased vehicles.
|-
| 0x30..0xFF || reserved
|}
<references/>
The other bytes of variable <code style="color:darkgreen">extra_callback_info1</code> are reserved, and must be masked.
The cases 0x20..0x2F are called using the <code style="color:darkgreen">purchase</code>-callback, the other cases are called for the <code style="color:darkgreen">default</code>- or cargo-specific callbacks. Exception is the the special depot-gridsize call, which uses the <code style="color:darkgreen">purchase</code>-callback.

===Sound events===

{| class="t"
! Event
! Description
|-
| SOUND_EVENT_START
| Vehicle leaves station or depot, plane takes off
|-
| SOUND_EVENT_TUNNEL
| Vehicle enters tunnel
|-
| SOUND_EVENT_BREAKDOWN
| Vehicle breaks down (not for planes)
|-
| SOUND_EVENT_RUNNING
| Once per engine tick, but no more than once per vehicle motion
|-
| SOUND_EVENT_TOUCHDOWN
| Aircraft touches down
|-
| SOUND_EVENT_VISUAL_EFFECT
| Visual effect is generated (steam plume, diesel smoke, electric spark)
|-
| SOUND_EVENT_RUNNING_16
| Every 16 engine ticks if in motion
|-
| SOUND_EVENT_STOPPED
| Every 16 engine ticks if stopped
|-
| SOUND_EVENT_LOAD_UNLOAD
| Consist loads or unloads cargo
|}