GRFSpecs - User contributions [en-gb]

NML:Roadstops

2026-06-09T21:20:06Z

Rito12: /* Road stop properties */ Fix some value ranges.

{{NMLNavPropVarCB}}

Road stops can only be defined in OpenTTD {{ottd|14.0}} or later.

==Road stop IDs==
OpenTTD supports 64000 road stop types per game.

Rpad stop IDs are NewGRF-local and can therefore freely be chosen within the ID ranges.

A road stop is allocated by setting the 'class'-property, which should therefore be set first.

Road stop sprite layouts should always set a suitable ground tile sprite, and should not assume that a road type GRF will provide suitable overlay sprites.
Suggested ground sprite IDs include: GROUNDSPRITE_ROAD_X/GROUNDSPRITE_ROAD_Y (straight road on grass), 1314/1313 (straight road with pavement), 2692 - 2695 (bay road stop ground).

==Road stop properties==

{| class="wikitable sortable"
! property
! value range
! comment
|-
| class
| String literal of length 4
|
'''This property ''must'' be set first, before any other properties or graphics.''' 
Road stops belonging to the same class are grouped in the GUI. 
There is one special class:
* "WAYP": {{ottdp|15.0|no}} The road stop type will be shown in the waypoint construction window, instead of the station construction window.
{{ottdp|15}} Station classes which start with the byte FF are considered waypoint classes, and will appear in the waypoint construction window instead of the station construction window.
|-
| classname
| string
| You only need to set this for one road stop in every class.
|-
| name
| string
|
|-
| availability_type
| RST_AVAILABILITY_TYPE_XXX
| XXX = [PASSENGER <nowiki>|</nowiki> FREIGHT <nowiki>|</nowiki> ALL]
The default value is RST_AVAILABILITY_TYPE_ALL
|-
| draw_mode
| bitmask(RST_DRAW_FLAG_XXX, ...)
| See [[#List of draw mode flags|list of draw mode flags]]
The default value is bitmask(RST_DRAW_FLAG_BAY_ROAD, RST_DRAW_FLAG_DRIVE_THROUGH_ROAD_OVERLAY)
|-
| cargo_random_triggers
| cargo bitmask
| Cargo types, which will [[NML:Random_switch#Stations|trigger re-randomization]] when delivered, loaded or unloaded at the station.
|-
| 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_ROAD_STOP_XXX, ...)
|
See [[#Animation_triggers|list of animation triggers]]
|-
| general_flags
| bitmask(RST_GENERAL_FLAG_XXX, ...)
| See [[#List of general flags|list of general flags]]
|-
| cost_multipliers
| [build_cost, clear_cost]
| Build and clear cost multipliers, 16 is the same as a non-NewGRF road stop
|-
| badges
| Array of badge labels from the [[NML:Badgetable|badgetable]].
| Since {{ottd|15.0}}
|-
| heights
| Array of unsigned ints
| Since {{ottd|15.0}} {{nml|0.8.1}} 
Each element of array corresponds to one [[#List of road stop views|view]]. 
Specifies the bridge height so bridges can be build above the road stop.
The bridge height defines minimum clearances required for a bridge for the sprite layouts of this road stop (or zero to not allow any bridge).
Values are given in "height level" units (1 level == 8px).
|-
| blocked_pillars
| Array of <code>bitmask(BRIDGE_PILLAR_XXX, ...)</code>
| Since {{ottd|15.0}} {{nml|0.8.1}} 
Each element of array corresponds to one [[#List of road stop views|view]]. 
Allows information to provided about blocked bridge pillars to assist the game in hiding pillars if necessary depending on what is above the road stop tile. Blocking a pillar prevents the pillar from being drawn. It does not prevent the road stop being bridgeable.
See [[#List_of_bridge_pillar_flags|list of bridge pillar flags]].
|}

===List of draw mode flags===

{| class="wikitable sortable"
! Name
! Meaning
|-
| RST_DRAW_FLAG_BAY_ROAD
| Draw road type ground sprite for bay stops.
|-
| RST_DRAW_FLAG_DRIVE_THROUGH_ROAD_OVERLAY
| Draw road overlays for drive-through stops.
|-
| RST_DRAW_FLAG_WAYPOINT_GROUND
| {{ottdp|15.0|no}} Draw spritelayout ground sprite on top of underlying road (if unset, the spritelayout ground sprite is not drawn).
|}

===List of general flags===

{| class="wikitable sortable"
! Name
! Meaning
|-
| RST_GENERAL_FLAG_RANDOM_ANIMATION
| Animation callback requires random bits in variable extra_callback_info1.
|-
| RST_GENERAL_FLAG_NO_CATENARY
| Do not show catenary graphics.
|-
| RST_GENERAL_FLAG_DRIVE_THROUGH_ONLY
| Only allow drive-through stops (not bay stops).
|-
| RST_GENERAL_FLAG_NO_AUTO_ROAD_CONNECTION
| Do not automatically build connecting road pieces.
|-
| RST_GENERAL_FLAG_BUILD_MENU_ROAD_ONLY
| Only show in the road build menu (not tram).
|-
| RST_GENERAL_FLAG_BUILD_MENU_TRAM_ONLY
| Only show in the tram build menu (not road).
|-
| RST_GENERAL_FLAG_DRAW_MODE_REGISTER
| {{ottdp|15.0|no}} Read the road stop draw mode from variable 0x100 (set using STORE_TEMP), this overrides the draw_mode property.
|}

===List of bridge pillar flags===

{| class="wikitable sortable"
! Name
! Meaning
|-
| BRIDGE_PILLAR_CORNER_W
| Tile layout blocks a pillar on the west corner of the tile.
|-
| BRIDGE_PILLAR_CORNER_S
| Tile layout blocks a pillar on the south corner of the tile.
|-
| BRIDGE_PILLAR_CORNER_E
| Tile layout blocks a pillar on the east corner of the tile.
|-
| BRIDGE_PILLAR_CORNER_N
| Tile layout blocks a pillar on the north corner of the tile.
|-
| BRIDGE_PILLAR_EDGE_NE
| Tile layout blocks a wall on the north east side of the tile.
|-
| BRIDGE_PILLAR_EDGE_SE
| Tile layout blocks a wall on the south east side of the tile.
|-
| BRIDGE_PILLAR_EDGE_SW
| Tile layout blocks a wall on the south west side of the tile.
|-
| BRIDGE_PILLAR_EDGE_NW
| Tile layout blocks a wall on the north west side of the tile.
|}

==Road stop variables==

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

{| class="wikitable sortable"
! name
! value range
! comment
|-
| random_bits_station
| 0..65535
| 16 random bits, shared between all station sections (rail station sections, airports, ...)
|-
| 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:Stations|stations]] and [[NML:Airports|airports]]. They all require a single argument: a cargo type from your [[NML:Cargotable|cargo translation table]].

{| class="wikitable sortable"
! 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="wikitable sortable"
! name
! value range
! comment
|-
| view
| RST_VIEW_XXX
| The view/rotation of the road stop. See [[#List of road stop views|list of road stop views]]
|-
| stop_type
| RST_TYPE_XXX
| XXX = [BUS <nowiki>|</nowiki> TRUCK <nowiki>|</nowiki> {{ottdp|15}}WAYPOINT]
|-
| 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
|-
| has_road
| [0 <nowiki>|</nowiki> 1]
| 1 if this road stop has road
|-
| has_tram
| [0 <nowiki>|</nowiki> 1]
| 1 if this road stop has tram
|-
| road_type
| [Road type <nowiki>|</nowiki> 0xFF]
| Entry from [[NML:Railtypetable|roadtype translation table]], or 0xFF if there is no road
|-
| tram_type
| [Tram type <nowiki>|</nowiki> 0xFF]
| Entry from [[NML:Railtypetable|tramtype translation table]], or 0xFF if there is no tram
|-
| animation_frame
| 0 .. (frame_count - 1)
| Current animation frame, with the maximum defined in the <code style="color:darkgreen">animation_info</code> property.
|-
| 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.
|-
| company_num
| 0 ... 14
| Company number of the roadstop owner.
|-
| 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.
|-
| random_bits_tile
| 0..255
| 8 random bits, specific to this road stop tile.
|-
| waiting_triggers
| 0..255
| Random triggers waiting to be matched. (see [[NML:Random switch|Random switch]])
|-
| drawn_in_gui
| [0 <nowiki>|</nowiki> 1]
| {{ottdp|15}} 1 if this road stop is being drawn in the build window
|}

===Variables that require one or more parameters===

{| class="wikitable sortable"
! name
! arguments
! value range
! comment
|-
| nearby_tile_slope
| x, y offset (-8..7)
|
| See tile_slope
|-
| 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. Only valid for tiles of the same object.
|-
| nearby_tile_is_road_stop
| x, y offset (-8..7)
| 0 .. 1
| Is the given tile a road stop?
|-
| nearby_tile_road_stop_id
| x, y offset (-8..7)
|
| If nearby_tile_same_grf is true, ID of a road stop on a nearby tile
|-
| nearby_tile_same_grf
| x, y offset (-8..7)
| 0 .. 1
| Is a road stop on a nearby tile defined by the same GRF?
|-
| nearby_tile_other_grf
| x, y offset (-8..7)
| 0 .. 1
| Is a road stop on a nearby tile defined by another GRF?
|-
| nearby_tile_original_gfx
| x, y offset (-8..7)
| 0 .. 1
| Is a road stop on a nearby tile using original graphics?
|-
| nearby_tile_same_station
| x, y offset (-8..7)
| 0 .. 1
| Is a road stop on a nearby tile the same station as this?
|-
| nearby_tile_view
| x, y offset (-8..7)
| RST_VIEW_XXX
| The view/rotation of a nearby road stop tile. See [[#List of road stop views|list of road stop views]]
|-
| nearby_tile_different_view
| x, y offset (-8..7)
| 0 .. 1
| Is the view/rotation of a road stop on a nearby tile different to that of this tile?
|-
| nearby_tile_is_drive_through
| x, y offset (-8..7)
| 0 .. 1
| Is nearby road stop tile a drive-through road stop?
|-
| nearby_tile_stop_type
| x, y offset (-8..7)
| RST_TYPE_XXX
| Road stop type of a nearby tile. See stop_type
|-
| nearby_tile_same_stop_type
| x, y offset (-8..7)
| 0 .. 1
| Is the stop type of a nearby road stop tile the same as this tile?
|-
| nearby_tile_grfid
| x, y offset (-8..7)
| [0xFFFFFFFF <nowiki>|</nowiki> 0 <nowiki>|</nowiki> GRFID]
| 0xFFFFFFFF if the nearby tile is not a road stop, 0 if the nearby tile is a non-custom road stop, or else the GRFID of the NewGRF defining the road stop on the nearby tile
|-
| has_badge
| Label from the [[NML:Badgetable|badgetable]].
| [0 <nowiki>|</nowiki> 1]
| {{ottd|15.0}} Check if the road stop has that specific badge attached.
|}

===List of road stop views===

{| class="wikitable sortable"
! Name
! Type
! Meaning
! Value
|-
| RST_VIEW_BAY_NE
| Bay
| Facing north-east
| 0
|-
| RST_VIEW_BAY_SE
| Bay
| Facing south-east
| 1
|-
| RST_VIEW_BAY_SW
| Bay
| Facing south-west
| 2
|-
| RST_VIEW_BAY_NW
| Bay
| Facing north-west
| 3
|-
| RST_VIEW_DRIVE_THROUGH_X
| Drive-through
| X-axis: north-east to south-west
| 4
|-
| RST_VIEW_DRIVE_THROUGH_Y
| Drive-through
| Y-axis: north-west to south-east
| 5
|}

==Road stop callbacks==

{| class="wikitable sortable"
! callback
! return value
! comment
|-
| default
| Sprite layout
| Normal graphics for a road stop placed on the map
|-
| purchase <ref name="notyetbuilt">These callbacks are called when the road stop is not yet built</ref>
| Sprite layout
| Graphics shown in the build menu
|-
| availability
| 0 <nowiki>|</nowiki> 1
| Whether this road stop type is available in the build menu, 1 is available, 0 is unavailable
|-
| 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. 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>).
* <code style="color:darkgreen">extra_callback_info1</code>: 32 random bits, if the object flag OBJ_FLAG_RANDOM_ANIMATION is set.
|-
| 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 = [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. Returning a sound effect in the high byte will cause that sound effect to be played.
* <code style="color:darkgreen">extra_callback_info1</code>: 32 random bits, if the object flag OBJ_FLAG_RANDOM_ANIMATION is set.
* <code style="color:darkgreen">getbits(extra_callback_info2, 0, 8)</code>: Reason for the callback trigger, see the [[#Animation triggers| table]] below.
|-
| 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.
|}

===Animation triggers===

{| class="wikitable sortable"
! Animation trigger
! Description
! Happens on
! extra_callback_info2
|-
| ANIM_TRIGGER_ROAD_STOP_BUILT
| Road stop is built
| Newly built tile
|
|-
| ANIM_TRIGGER_ROAD_STOP_NEW_CARGO
| New cargo arrives at station
| All tiles
| Bits 8..15 contain the triggering cargo type
|-
| ANIM_TRIGGER_ROAD_STOP_CARGO_TAKEN
| CRGO removed from station
| All tiles
| Bits 8..15 contain the triggering cargo type
|-
| ANIM_TRIGGER_ROAD_STOP_VEH_ENTER
| Road vehicle enters stop (starts loading/unloading)
| Tile where the vehicle is
|
|-
| ANIM_TRIGGER_ROAD_STOP_VEH_LEAVE
| Road vehicle leaves stop (done loading/unloading)
| Tile where the vehicle is
|
|-
| ANIM_TRIGGER_ROAD_STOP_VEH_LOAD
| Road vehicle loads/unloads cargo
| Tile where the vehicle is
|
|-
| ANIM_TRIGGER_ROAD_STOP_250_TICKS
| Every 250 ticks
| All tiles
|
|-
| {{ottd|15.0}} ANIM_TRIGGER_ROAD_STOP_TILELOOP
| Tile is processed in the periodic processing loop
|
|
|}

NML:Animation speed

2026-06-09T20:25:01Z

Rito12: Fix: 'as' and 'length' used twice in single sentence.

{{NMLNavAdditionalreferences}}

House, industry and airport tiles can define an animation speed. This property gives the animation speed in ticks, spaced by powers of two. For houses the minimum value is 2 (=4 ticks). Both the ingame and real lengths are given as rounded values for reference only, assuming normal game speed.

{| class="t"
! value
! animation length in ticks
! ingame
! real time
|-
| 0
| 1
|
| 0.03 s
|-
| 1
| 2
|
| 0.06 s
|-
| 2
| 4
|
| 0.11 s
|-
| 3
| 8
|
| 0.22 s
|-
| 4
| 16
|
| 0.45 s
|-
| 5
| 32
| half a day
| 0.9 s
|-
| 6
| 64
| nearly 1 day
| 1.8 s
|-
| 7
| 128
| 2 days
| 3½ s
|-
| 8
| 256
| 3½ days
| 7 s
|-
| 9
| 512
| 7 days
| 15 s
|-
| 10
| 1024
| 14 days
| 30 s
|-
| 11
| 2048
| 28 days
| 1 min
|-
| 12
| 4096
| 55 days
| 2 min
|-
| 13
| 8192
| 3½ months
| 4 min
|-
| 14
| 16384
| 7½ months
| 7½ min
|-
| 15
| 32768
| 15 months
| 15 min
|-
| 16
| 65536
| 2½ years
| 30 min
|}

NML:Roadstops

2026-06-09T15:44:16Z

Rito12: /* Road stop callbacks */ CB_RESULT_CB_RESULT_START_ANIMATION is wrong.

{{NMLNavPropVarCB}}

Road stops can only be defined in OpenTTD {{ottd|14.0}} or later.

==Road stop IDs==
OpenTTD supports 64000 road stop types per game.

Rpad stop IDs are NewGRF-local and can therefore freely be chosen within the ID ranges.

A road stop is allocated by setting the 'class'-property, which should therefore be set first.

Road stop sprite layouts should always set a suitable ground tile sprite, and should not assume that a road type GRF will provide suitable overlay sprites.
Suggested ground sprite IDs include: GROUNDSPRITE_ROAD_X/GROUNDSPRITE_ROAD_Y (straight road on grass), 1314/1313 (straight road with pavement), 2692 - 2695 (bay road stop ground).

==Road stop properties==

{| class="wikitable sortable"
! property
! value range
! comment
|-
| class
| String literal of length 4
|
'''This property ''must'' be set first, before any other properties or graphics.''' 
Road stops belonging to the same class are grouped in the GUI. 
There is one special class:
* "WAYP": {{ottdp|15.0|no}} The road stop type will be shown in the waypoint construction window, instead of the station construction window.
{{ottdp|15}} Station classes which start with the byte FF are considered waypoint classes, and will appear in the waypoint construction window instead of the station construction window.
|-
| classname
| string
| You only need to set this for one road stop in every class.
|-
| name
| string
|
|-
| availability_type
| RST_AVAILABILITY_TYPE_XXX
| XXX = [PASSENGER <nowiki>|</nowiki> FREIGHT <nowiki>|</nowiki> ALL]
The default value is RST_AVAILABILITY_TYPE_ALL
|-
| draw_mode
| bitmask(RST_DRAW_FLAG_XXX, ...)
| See [[#List of draw mode flags|list of draw mode flags]]
The default value is bitmask(RST_DRAW_FLAG_BAY_ROAD, RST_DRAW_FLAG_DRIVE_THROUGH_ROAD_OVERLAY)
|-
| cargo_random_triggers
| Array of cargo labels from the [[NML:Cargotable|cargotable]]
| Cargo types, which will [[NML:Random_switch#Stations|trigger re-randomization]] when delivered, loaded or unloaded at the station.
|-
| 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
|
|
See [[#Animation_triggers|list of animation triggers]]
|-
| general_flags
| bitmask(RST_GENERAL_FLAG_XXX, ...)
| See [[#List of general flags|list of general flags]]
|-
| cost_multipliers
| [build_cost, clear_cost]
| Build and clear cost multipliers, 16 is the same as a non-NewGRF road stop
|-
| badges
| Array of badge labels from the [[NML:Badgetable|badgetable]].
| Since {{ottd|15.0}}
|-
| heights
| Array of unsigned ints
| Since {{ottd|15.0}} {{nml|0.8.1}} 
Each element of array corresponds to one [[#List of road stop views|view]]. 
Specifies the bridge height so bridges can be build above the road stop.
The bridge height defines minimum clearances required for a bridge for the sprite layouts of this road stop (or zero to not allow any bridge).
Values are given in "height level" units (1 level == 8px).
|-
| blocked_pillars
| Array of <code>bitmask(BRIDGE_PILLAR_XXX, ...)</code>
| Since {{ottd|15.0}} {{nml|0.8.1}} 
Each element of array corresponds to one [[#List of road stop views|view]]. 
Allows information to provided about blocked bridge pillars to assist the game in hiding pillars if necessary depending on what is above the road stop tile. Blocking a pillar prevents the pillar from being drawn. It does not prevent the road stop being bridgeable.
See [[#List_of_bridge_pillar_flags|list of bridge pillar flags]].
|}

===List of draw mode flags===

{| class="wikitable sortable"
! Name
! Meaning
|-
| RST_DRAW_FLAG_BAY_ROAD
| Draw road type ground sprite for bay stops.
|-
| RST_DRAW_FLAG_DRIVE_THROUGH_ROAD_OVERLAY
| Draw road overlays for drive-through stops.
|-
| RST_DRAW_FLAG_WAYPOINT_GROUND
| {{ottdp|15.0|no}} Draw spritelayout ground sprite on top of underlying road (if unset, the spritelayout ground sprite is not drawn).
|}

===List of general flags===

{| class="wikitable sortable"
! Name
! Meaning
|-
| RST_GENERAL_FLAG_RANDOM_ANIMATION
| Animation callback requires random bits in variable extra_callback_info1.
|-
| RST_GENERAL_FLAG_NO_CATENARY
| Do not show catenary graphics.
|-
| RST_GENERAL_FLAG_DRIVE_THROUGH_ONLY
| Only allow drive-through stops (not bay stops).
|-
| RST_GENERAL_FLAG_NO_AUTO_ROAD_CONNECTION
| Do not automatically build connecting road pieces.
|-
| RST_GENERAL_FLAG_BUILD_MENU_ROAD_ONLY
| Only show in the road build menu (not tram).
|-
| RST_GENERAL_FLAG_BUILD_MENU_TRAM_ONLY
| Only show in the tram build menu (not road).
|-
| RST_GENERAL_FLAG_DRAW_MODE_REGISTER
| {{ottdp|15.0|no}} Read the road stop draw mode from variable 0x100 (set using STORE_TEMP), this overrides the draw_mode property.
|}

===List of bridge pillar flags===

{| class="wikitable sortable"
! Name
! Meaning
|-
| BRIDGE_PILLAR_CORNER_W
| Tile layout blocks a pillar on the west corner of the tile.
|-
| BRIDGE_PILLAR_CORNER_S
| Tile layout blocks a pillar on the south corner of the tile.
|-
| BRIDGE_PILLAR_CORNER_E
| Tile layout blocks a pillar on the east corner of the tile.
|-
| BRIDGE_PILLAR_CORNER_N
| Tile layout blocks a pillar on the north corner of the tile.
|-
| BRIDGE_PILLAR_EDGE_NE
| Tile layout blocks a wall on the north east side of the tile.
|-
| BRIDGE_PILLAR_EDGE_SE
| Tile layout blocks a wall on the south east side of the tile.
|-
| BRIDGE_PILLAR_EDGE_SW
| Tile layout blocks a wall on the south west side of the tile.
|-
| BRIDGE_PILLAR_EDGE_NW
| Tile layout blocks a wall on the north west side of the tile.
|}

==Road stop variables==

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

{| class="wikitable sortable"
! name
! value range
! comment
|-
| random_bits_station
| 0..65535
| 16 random bits, shared between all station sections (rail station sections, airports, ...)
|-
| 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:Stations|stations]] and [[NML:Airports|airports]]. They all require a single argument: a cargo type from your [[NML:Cargotable|cargo translation table]].

{| class="wikitable sortable"
! 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="wikitable sortable"
! name
! value range
! comment
|-
| view
| RST_VIEW_XXX
| The view/rotation of the road stop. See [[#List of road stop views|list of road stop views]]
|-
| stop_type
| RST_TYPE_XXX
| XXX = [BUS <nowiki>|</nowiki> TRUCK <nowiki>|</nowiki> {{ottdp|15}}WAYPOINT]
|-
| 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
|-
| has_road
| [0 <nowiki>|</nowiki> 1]
| 1 if this road stop has road
|-
| has_tram
| [0 <nowiki>|</nowiki> 1]
| 1 if this road stop has tram
|-
| road_type
| [Road type <nowiki>|</nowiki> 0xFF]
| Entry from [[NML:Railtypetable|roadtype translation table]], or 0xFF if there is no road
|-
| tram_type
| [Tram type <nowiki>|</nowiki> 0xFF]
| Entry from [[NML:Railtypetable|tramtype translation table]], or 0xFF if there is no tram
|-
| animation_frame
| 0 .. (frame_count - 1)
| Current animation frame, with the maximum defined in the <code style="color:darkgreen">animation_info</code> property.
|-
| 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.
|-
| company_num
| 0 ... 14
| Company number of the roadstop owner.
|-
| 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.
|-
| random_bits_tile
| 0..255
| 8 random bits, specific to this road stop tile.
|-
| waiting_triggers
| 0..255
| Random triggers waiting to be matched. (see [[NML:Random switch|Random switch]])
|-
| drawn_in_gui
| [0 <nowiki>|</nowiki> 1]
| {{ottdp|15}} 1 if this road stop is being drawn in the build window
|}

===Variables that require one or more parameters===

{| class="wikitable sortable"
! name
! arguments
! value range
! comment
|-
| nearby_tile_slope
| x, y offset (-8..7)
|
| See tile_slope
|-
| 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. Only valid for tiles of the same object.
|-
| nearby_tile_is_road_stop
| x, y offset (-8..7)
| 0 .. 1
| Is the given tile a road stop?
|-
| nearby_tile_road_stop_id
| x, y offset (-8..7)
|
| If nearby_tile_same_grf is true, ID of a road stop on a nearby tile
|-
| nearby_tile_same_grf
| x, y offset (-8..7)
| 0 .. 1
| Is a road stop on a nearby tile defined by the same GRF?
|-
| nearby_tile_other_grf
| x, y offset (-8..7)
| 0 .. 1
| Is a road stop on a nearby tile defined by another GRF?
|-
| nearby_tile_original_gfx
| x, y offset (-8..7)
| 0 .. 1
| Is a road stop on a nearby tile using original graphics?
|-
| nearby_tile_same_station
| x, y offset (-8..7)
| 0 .. 1
| Is a road stop on a nearby tile the same station as this?
|-
| nearby_tile_view
| x, y offset (-8..7)
| RST_VIEW_XXX
| The view/rotation of a nearby road stop tile. See [[#List of road stop views|list of road stop views]]
|-
| nearby_tile_different_view
| x, y offset (-8..7)
| 0 .. 1
| Is the view/rotation of a road stop on a nearby tile different to that of this tile?
|-
| nearby_tile_is_drive_through
| x, y offset (-8..7)
| 0 .. 1
| Is nearby road stop tile a drive-through road stop?
|-
| nearby_tile_stop_type
| x, y offset (-8..7)
| RST_TYPE_XXX
| Road stop type of a nearby tile. See stop_type
|-
| nearby_tile_same_stop_type
| x, y offset (-8..7)
| 0 .. 1
| Is the stop type of a nearby road stop tile the same as this tile?
|-
| nearby_tile_grfid
| x, y offset (-8..7)
| [0xFFFFFFFF <nowiki>|</nowiki> 0 <nowiki>|</nowiki> GRFID]
| 0xFFFFFFFF if the nearby tile is not a road stop, 0 if the nearby tile is a non-custom road stop, or else the GRFID of the NewGRF defining the road stop on the nearby tile
|-
| has_badge
| Label from the [[NML:Badgetable|badgetable]].
| [0 <nowiki>|</nowiki> 1]
| {{ottd|15.0}} Check if the road stop has that specific badge attached.
|}

===List of road stop views===

{| class="wikitable sortable"
! Name
! Type
! Meaning
! Value
|-
| RST_VIEW_BAY_NE
| Bay
| Facing north-east
| 0
|-
| RST_VIEW_BAY_SE
| Bay
| Facing south-east
| 1
|-
| RST_VIEW_BAY_SW
| Bay
| Facing south-west
| 2
|-
| RST_VIEW_BAY_NW
| Bay
| Facing north-west
| 3
|-
| RST_VIEW_DRIVE_THROUGH_X
| Drive-through
| X-axis: north-east to south-west
| 4
|-
| RST_VIEW_DRIVE_THROUGH_Y
| Drive-through
| Y-axis: north-west to south-east
| 5
|}

==Road stop callbacks==

{| class="wikitable sortable"
! callback
! return value
! comment
|-
| default
| Sprite layout
| Normal graphics for a road stop placed on the map
|-
| purchase <ref name="notyetbuilt">These callbacks are called when the road stop is not yet built</ref>
| Sprite layout
| Graphics shown in the build menu
|-
| availability
| 0 <nowiki>|</nowiki> 1
| Whether this road stop type is available in the build menu, 1 is available, 0 is unavailable
|-
| 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. 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>).
* <code style="color:darkgreen">extra_callback_info1</code>: 32 random bits, if the object flag OBJ_FLAG_RANDOM_ANIMATION is set.
|-
| 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 = [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. Returning a sound effect in the high byte will cause that sound effect to be played.
* <code style="color:darkgreen">extra_callback_info1</code>: 32 random bits, if the object flag OBJ_FLAG_RANDOM_ANIMATION is set.
* <code style="color:darkgreen">getbits(extra_callback_info2, 0, 8)</code>: Reason for the callback trigger, see the [[#Animation triggers| table]] below.
|-
| 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.
|}

===Animation triggers===

{| class="wikitable sortable"
! Animation trigger
! Description
! Happens on
! extra_callback_info2
|-
| ANIM_TRIGGER_ROAD_STOP_BUILT
| Road stop is built
| Newly built tile
|
|-
| ANIM_TRIGGER_ROAD_STOP_NEW_CARGO
| New cargo arrives at station
| All tiles
| Bits 8..15 contain the triggering cargo type
|-
| ANIM_TRIGGER_ROAD_STOP_CARGO_TAKEN
| CRGO removed from station
| All tiles
| Bits 8..15 contain the triggering cargo type
|-
| ANIM_TRIGGER_ROAD_STOP_VEH_ENTER
| Road vehicle enters stop (starts loading/unloading)
| Tile where the vehicle is
|
|-
| ANIM_TRIGGER_ROAD_STOP_VEH_LEAVE
| Road vehicle leaves stop (done loading/unloading)
| Tile where the vehicle is
|
|-
| ANIM_TRIGGER_ROAD_STOP_VEH_LOAD
| Road vehicle loads/unloads cargo
| Tile where the vehicle is
|
|-
| ANIM_TRIGGER_ROAD_STOP_250_TICKS
| Every 250 ticks
| All tiles
|
|-
| {{ottd|15.0}} ANIM_TRIGGER_ROAD_STOP_TILELOOP
| Tile is processed in the periodic processing loop
|
|
|}

NML:Parameter assignment

2026-06-08T09:14:23Z

Rito12: Named parameters and constants.

{{NMLNavBlocksyntax}}

==Parameters==

param[<expression>] = <expression>;

Set a parameter to the given [[NML:Block syntax#Syntax|expression]]. Neither of the two expressions has to be constant, the following is perfectly valid:

<pre style="color:blue">
param[param[2] + 1] = param[3] * param[4];
</pre>

Parameters can also be named, then it is possible to access them by that name instead of index.

<pre style="color:blue">
custom_bit_mask = add_trains + (add_planes << 1);
</pre>

'''Note:''' When assigning value to named parameter that has not been used/defined earlier it is given an unused index, therefore it is better not to mix named parameters with unnamed ones in one grf.

==Compile time values==

Since {{nml|0.7.6}} it is possible to create user defined constants. They work the same way as default ones.

<pre>
const <expression> = <expression>;
</pre>

<pre style="color:blue">
const CC_WEIRD = 12;
</pre>

It is adviced to use screaming snake case for constants to distinguish them from runtime expressions.

NML:Stations

2026-06-08T07:22:04Z

Rito12: /* Variables without a parameter */ It is station not vehicle.

{{NMLNavPropVarCB}}
Stations are supported since {{nml|0.7}}.

==Station sections==

Stations can be built from multiple sections. Station tiles will remember, which tiles were built together in one action.
* Building a 2x5 station in one action creates a single station section of size 2x5.
* Building a 2x5 station by placing two 1x5 areas next to each other in two actions creates two station sections of size 1x5; even when using the same station type from the same NewGRF.

[[File:station_sections.png|800px]]

Overbuilding stations and removing station tiles will remove tiles from station sections.
* On construction all station sections are contiguous rectangular NxM tile ares. (regular station section)
* When tiles are overbuilt or tiles are removed, station sections may end up non-rectangular and non-contiguous. (irregular station section)
Station tiles can query their position inside a contiguous line of tiles from the same section.
* This is great as long as the section remains regular.
* If tiles are non-contiguous, they are indistinguishable from tiles of other sections.

For irregular sections the "position" inside the section will become rather arbitrary.
The picture shows the perspective of each tile of a irregular section as "(platform, position)/(num-platforms, length)":

[[File:station_sections_irregular.png|800px]]

==Tile types==

When station sections are built, they can store a "tile type" for each tile using the <code style="color:darkgreen">select_tile_type</code> callback.

Tile types have multiple usages:
* The type can be read via the <code style="color:darkgreen">tile_type</code> variable, and can act as persistent storage.
* It decides whether the tile is traversible by trains, or whether it is a building without tracks.
* It decides whether catenary pylons and/or wires shall be drawn/hidden on the tile. Note: even non-track station buildings have a rail type, and can draw catenary.

The tile type is immutable after construction. So, unlike the platform/position information, the tile type will never change after construction, even if tiles of the station section are removed or overbuilt.

The number of tile types is quite limited: 4 per orientation, 8 in total.
'''Note:''' Since {{ottd|15.0}} {{nml|0.7.6}} it is possible to register up to 256 tile types.
* Tile types 0, 2, 4 and 6 are used for station sections with tracks in X direction (⤢).
* Tile types 1, 3, 5 and 7 are used for station sections with tracks in Y direciton (⤡).
* Callback <code style="color:darkgreen">select_tile_type</code> decides between the pairs (0,1), (2,3), (4,5), (6,7) during construction. The orientation is always picked by the player.

==Station properties==

{| class="wikitable sortable"
! property
! value range
! comment
|-
| class
| String literal of length 4
|
'''This property ''must'' be set first, before any other properties or graphics.''' 
Stations belonging to the same class are grouped in the GUI. 
There is one special class:
* "WAYP": The station type will be shown in the waypoint construction window, instead of the station construction window.
{{ottdp|15.0}} Station classes which start with the byte FF are considered waypoint classes, and will appear in the waypoint construction window instead of the station construction window.
|-
| classname
| string
| You only need to set this for one station in every class.
|-
| name
| string
| For example: string(STR_50S_STATION)
|-
| disabled_platforms disabled_length
| bitmask(1, 2, 3, 4, 5, 6, 7, 8)
|
Restricts the possible number-of-platforms and platform-lengths the player can build as one section.
* Sizes 1 to 7 can be disabled individually,
* "size 8" is used for anything bigger than 7.
To put restrictions on sizes bigger than 7 (for example, only allow even sizes), you can use callback <code style="color:darkgreen">tile_check</code>.
 Note: Players can remove single tiles from any station, so stations sections can end up with forbidden sizes anyway.
|-
| cargo_threshold
| 0..4095
| Threshold between <code style="color:darkgreen">little</code> and <code style="color:darkgreen">lots</code> spritesets, see [[NML:Spritegroup#Stations|spritegroup]] for details.
|-
| draw_pylon_tiles hide_wire_tiles non_traversable_tiles 
| bitmask(0, 1, 2, 3, 4, 5, 6, 7)
| '''Deprecated since '''{{nml|0.7.6}}''' , replaced by '''<code style="color:darkgreen">tile_flags</code>'''.''' 
Specifies which [[#Tile_types|tile types]] are traversible/non-traversible, and whether pylons and/or catenary shall be drawn for electrified rail types.
Note: it is common that all tile types behave the same, you may want to use the short cuts
* <code style="color:darkgreen">0</code> for no tile types, and
* <code style="color:darkgreen">STAT_ALL_TILES</code> for all tile types.
|-
| cargo_random_triggers
| Array of cargo labels from the [[NML:Cargotable|cargotable]]
| Cargo types, which will [[NML:Random_switch#Stations|trigger re-randomization]] when delivered, loaded or unloaded at the station.
|-
| general_flags
| bitmask(STAT_FLAG_XXX, STAT_FLAG_YYY, ...)
|
;STAT_FLAG_DISTRIBUTED_CARGO_BY_PERIMETER {{nml|0.9.0}}
:Specifies whether waiting cargo amounts are scaled by station '''perimeter''' for spriteset selection, see [[NML:Spritegroup#Stations|spritegroup]] for details.
:Since {{ottd|16.0}} if <code style="color:darkgreen">STAT_FLAG_DISTRIBUTED_CARGO_BY_AREA</code> is also set it does not do anything.
;STAT_FLAG_DISTRIBUTED_CARGO_BY_AREA {{ottd|16.0}} {{nml|0.9.0}}
:Specifies whether waiting cargo amounts are scaled by station '''area''' for spriteset selection, see [[NML:Spritegroup#Stations|spritegroup]] for details.
;STAT_FLAG_RANDOM_ANIMATION
:If set, callback <code style="color:darkgreen">anim_next_frame</code> will get random data in <code style="color:darkgreen">extra_callback_info1</code>
;STAT_FLAG_CUSTOM_FOUNDATIONS
:Enables callback <code style="color:darkgreen">foundations</code>, see below.
;STAT_FLAG_EXTENDED_FOUNDATIONS
:Selects between two possible spriteset formats for callback <code style="color:darkgreen">foundations</code>, see below.
;STAT_FLAG_DISTRIBUTED_CARGO
:Deprecated since {{nml|0.9.0}}.
|-
| 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(STAT_ANIM_XXX, ANIM_TRIGGER_STAT_YYY, ...)
| Enables callback <code style="color:darkgreen">anim_control</code> for specified triggers:
;STAT_ANIM_IS_BUILT
:Tile is built. (all new-built/overbuilt tiles)
;STAT_ANIM_CARGO_ARRIVES
:Cargo is deliverd from industry to station. (all station tiles)
;STAT_ANIM_CARGO_REMOVED
:All cargo was loaded onto a vehicle, no more cargo (of this type) is waiting. (all station tiles)
;STAT_ANIM_TRAIN_ENTERS
:Train stops at station. (all tiles of platform)
;STAT_ANIM_TRAIN_LEAVES
:Train leaves station. (all tiles of platform)
;STAT_ANIM_TRAIN_LOAD_UNLOAD
:Train is loading or unloading. (all tiles of platform)
;STAT_ANIM_250_TICKS
:Every 250 ticks. (synchronized for all tiles of the station)
;{{ottd|15.0}} ANIM_TRIGGER_STAT_TILELOOP
:Tile is processed in the periodic processing loop
;{{ottd|15.0}} ANIM_TRIGGER_STAT_TRAIN_RESERVES
:Train reserves platform (using PBS)
|-
| badges
| Array of badge labels from the [[NML:Badgetable|badgetable]].
| Since {{ottd|15.0}}
|-
| tile_flags
| Array of <code>bitmask(STAT_TILE_XXX, ...)</code>
| Since {{ottd|15.0}} {{nml|0.7.6}} 
Each element of array corresponds to one tile type. Array should always have even number of elements. 
'''XXX''' should be replaced by one of the following:
; PYLON
: Draw pylon on tile with that type.
; NOWIRE
: Hide wire on tile with that type.
; BLOCKED
: Do not allow trains to enter tile with that type.
|-
| heights
| Array of unsigned ints
| Since {{ottd|15.0}} {{nml|0.8.1}} 
Each element of array corresponds to one tile type. Array should always have even number of elements. 
Specifies the bridge height so bridges can be build above the station.
The bridge height defines minimum clearances required for a bridge for the sprite layouts of this station (or zero to not allow any bridge).
Values are given in "height level" units (1 level == 8px).
|-
| blocked_pillars
| Array of <code>bitmask(BRIDGE_PILLAR_XXX, ...)</code>
| Since {{ottd|15.0}} {{nml|0.8.1}} 
Each element of array corresponds to one tile type. Array should always have even number of elements. 
Allows information to provided about blocked bridge pillars to assist the game in hiding pillars if necessary depending on what is above the station tile. Blocking a pillar prevents the pillar from being drawn. It does not prevent the station being bridgeable.
 '''XXX''' should be replaced by one of the following:
;CORNER_W : Tile layout blocks a pillar on the west corner of the tile.
;CORNER_S : Tile layout blocks a pillar on the south corner of the tile.
;CORNER_E : Tile layout blocks a pillar on the east corner of the tile.
;CORNER_N : Tile layout blocks a pillar on the north corner of the tile.
;EDGE_NE : Tile layout blocks a wall on the north east side of the tile.
;EDGE_SE : Tile layout blocks a wall on the south east side of the tile.
;EDGE_SW : Tile layout blocks a wall on the south west side of the tile.
;EDGE_NW : Tile layout blocks a wall on the north west side of the tile.
|}

==Station variables==

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

{| class="wikitable sortable"
! name
! value range
! comment
|-
| random_bits_station
| 0..65535
| 16 random bits, shared between all station sections (rail station sections, airports, ...)
|-
| 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="wikitable sortable"
! 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="wikitable sortable"
! name
! value range
! comment
|-
| tile_type
| 0..7
; 0..255 {{ottd|15.0}}
| The type of tile, as decided by <code style="color:darkgreen">select_tile_type</code>. Bit 0 also tells the orientation.
|-
| 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 station 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.
|-
| random_bits_tile
| 0..15
| 4 random bits, specific to this station 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="wikitable sortable"
! 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_grfid
| tile- and platform-offset <ref name="offset"/>
| 32-bit GRFID
| GRFID of the NewGRF defining the given station tile.
|-
| 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_tile_type
| tile- and platform-offset <ref name="offset"/>
| 0..7
; 0..255 {{ottd|15.0}}
| [[#Tile_types|Tile type]] of the given tile. The orientation bit is adjusted to be relative to the current tile's orientation:
* 0, 2, 4, 6: Tracks are parallel.
* 1, 3, 5, 7: Tracks are perpendicular.
|-
| 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 [[#Station_sections|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.
|-
| has_badge
| Label from the [[NML:Badgetable|badgetable]].
| [0 <nowiki>|</nowiki> 1]
| {{ottd|15.0}} Check if the rail station has that specific badge attached.
|}
<references/>

==Station callbacks==

The following table contains a list of available station 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 cargo is waiting at the station. If multiple cargo types are waiting at the station, OpenTTD will pick one of the options the station provides.
If none of the listed cargo types is waiting at the station, the <code style="color:darkgreen">default</code> callback will be used.

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="wikitable sortable"
! callback
! return value
! comment
|-
| default
| spritegroup
| See [[#Graphics|below]].
|-
| purchase
| spritegroup or spriteset
| See [[#Graphics|below]]. If a spritegroup is linked instead of a spriteset, the "zero cargo amount" spriteset is used.
|-
| custom_spritesets
| Array of spritesets
| See [[#Graphics|below]].
|-
| sprite_layouts
| Array of spritelayouts
| See [[#Graphics|below]]. The number of sprite_layouts must be even, alternating X (⤢) and Y (⤡) orientations.
|-
| select_sprite_layout
| index into sprite_layouts[]
| See [[#Graphics|below]]. The result's even-/oddness is ignored. The orientation is always adjusted by OpenTTD.
|-
| purchase_select_sprite_layout
| index into sprite_layouts[]
| See [[#Graphics|below]]. The result's even-/oddness is ignored. The orientation is always adjusted by OpenTTD.
|-
| prepare_layout
| expression list
| See [[#Graphics|below]].
|-
| purchase_prepare_layout
| expression list
| See [[#Graphics|below]].
|-
| foundations
| sprite set
| See [[#foundations|below]].
|-
| availability
| [0 <nowiki>|</nowiki> 1]
| Return 1 to make the station show up in the build window
|-
| tile_check
| Same as for the [[NML:IndustryTiles#Location check results|location_check]] industry callback
| Decide whether station may be built on this tile. This is an additional check to all built-in checks (like slope checks), you can only further restrict construction, not lessen conditions.

Called before constructing the station section, so nothing exists on the map yet. Since the station isn't built yet, so you can't access station variables.
Only these variables are available: company-information, and the class, height, slope, terrain type and water status of nearby tiles.
* <code style="color:darkgreen">getbits(extra_callback_info1, 4, 4)</code>: The [[NML:List_of_tile_slopes|tile slope]] of the tile.
* <code style="color:darkgreen">getbits(extra_callback_info1, 0, 4)</code>: The [[NML:List_of_tile_slopes|tile slope]] of the tile, adjusted by station orientation:
** unmodified in X direction (⤢)
** mirrored in Y direction (⤡)
* <code style="color:darkgreen">getbits(extra_callback_info2, 0, 8)</code>: Tile position along the new-built platform. (0 = north tile)
* <code style="color:darkgreen">getbits(extra_callback_info2, 8, 8)</code>: Platform number within the new-built section. (0 = north platform)
* <code style="color:darkgreen">getbits(extra_callback_info2, 16, 8)</code>: Length of the new section being built.
* <code style="color:darkgreen">getbits(extra_callback_info2, 24, 8)</code>: Number of platforms in the new section being built.

|-
| select_tile_type
| [0 <nowiki>|</nowiki> 2 <nowiki>|</nowiki> 4 <nowiki>|</nowiki> 6]

Since {{ottdp|15}}, even values up to FE can be returned as long as the tile is defined.
| Decides which tile type to store for each tile during construction. The lowest bit is always defined by the station orientation, no matter the callback result. See also [[#Tile_types|tile type above]].

Called before constructing the station section, so nothing exists on the map yet. Since the station isn't built yet, so you can't access station variables.
Only these variables are available: company-information, and the class, height, slope, terrain type and water status of nearby tiles.
* <code style="color:darkgreen">getbits(extra_callback_info1, 0, 4)</code>: Tile position along the new-built platform. (0 = north tile)
* <code style="color:darkgreen">getbits(extra_callback_info1, 4, 4)</code>: Tile position along the new-built platform. (0 = south tile)
* <code style="color:darkgreen">getbits(extra_callback_info1, 8, 4)</code>: Platform number within the new-built section. (0 = north platform)
* <code style="color:darkgreen">getbits(extra_callback_info1, 12, 4)</code>: Platform number within the new-built section. (0 = south platform)
* <code style="color:darkgreen">getbits(extra_callback_info1, 16, 4)</code>: Length of the new section being built.
* <code style="color:darkgreen">getbits(extra_callback_info1, 20, 4)</code>: Number of platforms in the new section being built.
* <code style="color:darkgreen">getbits(extra_callback_info1, 24, 8)</code>: Original tile type in static layout.

|-
| 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>: 32 random bits, if enabled in the <code style="color:darkgreen">general_flags</code> property.
Returning a sound effect in the high byte will cause that sound effect to be played.

Note: Every time the animation frame is changed the map tile will be refreshed, even if the selected graphics stay the same. Therefore using the animation frame as a timer should be avoided, and animation triggers should be preferred instead.
|-
| anim_control
| Next animation frame or CB_RESULT_XXX
|
Called whenever an animation trigger happens. Return the animation frame to show, or CB_RESULT_XXX with XXX = [CB_RESULT_START_ANIMATION <nowiki>|</nowiki> STOP_ANIMATION <nowiki>|</nowiki> DO_NOTHING] to respectively start the animation in its current frame, stop the animation or do nothing. Returning a sound effect in the high byte will cause that sound effect to be played.
* <code style="color:darkgreen">extra_callback_info1</code>: 32 random bits. The low 16 bits are always different for each station tile, but the high 16 bits are the same for all triggered tiles.
* <code style="color:darkgreen">getbits(extra_callback_info2, 0, 8)</code>: Reason for the callback trigger (STAT_ANIM_xxx). Note that you need to enable the wanted triggers in the <code style="color:darkgreen">animation_triggers</code> property.
* <code style="color:darkgreen">getbits(extra_callback_info2, 8, 8)</code>: Cargo-type involved in the trigger. Only applies to STAT_ANIM_CARGO_ARRIVES, STAT_ANIM_CARGO_REMOVED, STAT_ANIM_TRAIN_LOAD_UNLOAD.
Note: Every time the animation frame is changed the map tile will be refreshed, even if the selected graphics stay the same. Therefore using the animation frame as a timer should be avoided, and animation triggers should be preferred instead.
|-
| anim_speed
| 0 .. 16
| Decide the time an animation frame should last. Return value is interpreted as (num_ticks = 2^anim_speed), which each tick lasting 30 ms. Avoid using this callback if possible, since it has to be called each tick for every animated tile. This can be used to create animation frames that last between 30 ms and 33 minutes.
|}

=== Graphics ===

[[File:Nml_station_graphics.dot.png|1000px]]

=== foundations ===

If <code style="color:darkgreen">STAT_FLAG_CUSTOM_FOUNDATIONS</code> is enabled in <code style="color:darkgreen">general_flags</code> you can draw custom foundation for station tiles on sloped terrain.

There are two options for providing foundation sprites:

==== STAT_FLAG_EXTENDED_FOUNDATIONS not set ====
The callback should return a spriteset looking like this:

[[File:simple_foundations.png]]

The foundations will be drawn by combining multiple sprites, as needed for the slope.

==== STAT_FLAG_EXTENDED_FOUNDATIONS ====
The callback should return a spritset looking like this:

[[File:extended_foundations.png]]

In addition you will have to check
* <code style="color:darkgreen">getbits(extra_callback_info2, 16, 2)</code>:
** 0: sprites as in template above.
** 1: sprites like before, but with no wall on NW edge.
** 2: sprites like before, but with no wall on NE edge.
** 3: sprites like before, but with no walls on either north edge.

NML:Roadstops

2026-06-08T07:21:06Z

Rito12: /* Variables without a parameter */ TTDP does not support roadstops at all, and probably will never do.

{{NMLNavPropVarCB}}

Road stops can only be defined in OpenTTD {{ottd|14.0}} or later.

==Road stop IDs==
OpenTTD supports 64000 road stop types per game.

Rpad stop IDs are NewGRF-local and can therefore freely be chosen within the ID ranges.

A road stop is allocated by setting the 'class'-property, which should therefore be set first.

Road stop sprite layouts should always set a suitable ground tile sprite, and should not assume that a road type GRF will provide suitable overlay sprites.
Suggested ground sprite IDs include: GROUNDSPRITE_ROAD_X/GROUNDSPRITE_ROAD_Y (straight road on grass), 1314/1313 (straight road with pavement), 2692 - 2695 (bay road stop ground).

==Road stop properties==

{| class="wikitable sortable"
! property
! value range
! comment
|-
| class
| String literal of length 4
|
'''This property ''must'' be set first, before any other properties or graphics.''' 
Road stops belonging to the same class are grouped in the GUI. 
There is one special class:
* "WAYP": {{ottdp|15.0|no}} The road stop type will be shown in the waypoint construction window, instead of the station construction window.
{{ottdp|15}} Station classes which start with the byte FF are considered waypoint classes, and will appear in the waypoint construction window instead of the station construction window.
|-
| classname
| string
| You only need to set this for one road stop in every class.
|-
| name
| string
|
|-
| availability_type
| RST_AVAILABILITY_TYPE_XXX
| XXX = [PASSENGER <nowiki>|</nowiki> FREIGHT <nowiki>|</nowiki> ALL]
The default value is RST_AVAILABILITY_TYPE_ALL
|-
| draw_mode
| bitmask(RST_DRAW_FLAG_XXX, ...)
| See [[#List of draw mode flags|list of draw mode flags]]
The default value is bitmask(RST_DRAW_FLAG_BAY_ROAD, RST_DRAW_FLAG_DRIVE_THROUGH_ROAD_OVERLAY)
|-
| cargo_random_triggers
| Array of cargo labels from the [[NML:Cargotable|cargotable]]
| Cargo types, which will [[NML:Random_switch#Stations|trigger re-randomization]] when delivered, loaded or unloaded at the station.
|-
| 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
|
|
See [[#Animation_triggers|list of animation triggers]]
|-
| general_flags
| bitmask(RST_GENERAL_FLAG_XXX, ...)
| See [[#List of general flags|list of general flags]]
|-
| cost_multipliers
| [build_cost, clear_cost]
| Build and clear cost multipliers, 16 is the same as a non-NewGRF road stop
|-
| badges
| Array of badge labels from the [[NML:Badgetable|badgetable]].
| Since {{ottd|15.0}}
|-
| heights
| Array of unsigned ints
| Since {{ottd|15.0}} {{nml|0.8.1}} 
Each element of array corresponds to one [[#List of road stop views|view]]. 
Specifies the bridge height so bridges can be build above the road stop.
The bridge height defines minimum clearances required for a bridge for the sprite layouts of this road stop (or zero to not allow any bridge).
Values are given in "height level" units (1 level == 8px).
|-
| blocked_pillars
| Array of <code>bitmask(BRIDGE_PILLAR_XXX, ...)</code>
| Since {{ottd|15.0}} {{nml|0.8.1}} 
Each element of array corresponds to one [[#List of road stop views|view]]. 
Allows information to provided about blocked bridge pillars to assist the game in hiding pillars if necessary depending on what is above the road stop tile. Blocking a pillar prevents the pillar from being drawn. It does not prevent the road stop being bridgeable.
See [[#List_of_bridge_pillar_flags|list of bridge pillar flags]].
|}

===List of draw mode flags===

{| class="wikitable sortable"
! Name
! Meaning
|-
| RST_DRAW_FLAG_BAY_ROAD
| Draw road type ground sprite for bay stops.
|-
| RST_DRAW_FLAG_DRIVE_THROUGH_ROAD_OVERLAY
| Draw road overlays for drive-through stops.
|-
| RST_DRAW_FLAG_WAYPOINT_GROUND
| {{ottdp|15.0|no}} Draw spritelayout ground sprite on top of underlying road (if unset, the spritelayout ground sprite is not drawn).
|}

===List of general flags===

{| class="wikitable sortable"
! Name
! Meaning
|-
| RST_GENERAL_FLAG_RANDOM_ANIMATION
| Animation callback requires random bits in variable extra_callback_info1.
|-
| RST_GENERAL_FLAG_NO_CATENARY
| Do not show catenary graphics.
|-
| RST_GENERAL_FLAG_DRIVE_THROUGH_ONLY
| Only allow drive-through stops (not bay stops).
|-
| RST_GENERAL_FLAG_NO_AUTO_ROAD_CONNECTION
| Do not automatically build connecting road pieces.
|-
| RST_GENERAL_FLAG_BUILD_MENU_ROAD_ONLY
| Only show in the road build menu (not tram).
|-
| RST_GENERAL_FLAG_BUILD_MENU_TRAM_ONLY
| Only show in the tram build menu (not road).
|-
| RST_GENERAL_FLAG_DRAW_MODE_REGISTER
| {{ottdp|15.0|no}} Read the road stop draw mode from variable 0x100 (set using STORE_TEMP), this overrides the draw_mode property.
|}

===List of bridge pillar flags===

{| class="wikitable sortable"
! Name
! Meaning
|-
| BRIDGE_PILLAR_CORNER_W
| Tile layout blocks a pillar on the west corner of the tile.
|-
| BRIDGE_PILLAR_CORNER_S
| Tile layout blocks a pillar on the south corner of the tile.
|-
| BRIDGE_PILLAR_CORNER_E
| Tile layout blocks a pillar on the east corner of the tile.
|-
| BRIDGE_PILLAR_CORNER_N
| Tile layout blocks a pillar on the north corner of the tile.
|-
| BRIDGE_PILLAR_EDGE_NE
| Tile layout blocks a wall on the north east side of the tile.
|-
| BRIDGE_PILLAR_EDGE_SE
| Tile layout blocks a wall on the south east side of the tile.
|-
| BRIDGE_PILLAR_EDGE_SW
| Tile layout blocks a wall on the south west side of the tile.
|-
| BRIDGE_PILLAR_EDGE_NW
| Tile layout blocks a wall on the north west side of the tile.
|}

==Road stop variables==

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

{| class="wikitable sortable"
! name
! value range
! comment
|-
| random_bits_station
| 0..65535
| 16 random bits, shared between all station sections (rail station sections, airports, ...)
|-
| 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:Stations|stations]] and [[NML:Airports|airports]]. They all require a single argument: a cargo type from your [[NML:Cargotable|cargo translation table]].

{| class="wikitable sortable"
! 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="wikitable sortable"
! name
! value range
! comment
|-
| view
| RST_VIEW_XXX
| The view/rotation of the road stop. See [[#List of road stop views|list of road stop views]]
|-
| stop_type
| RST_TYPE_XXX
| XXX = [BUS <nowiki>|</nowiki> TRUCK <nowiki>|</nowiki> {{ottdp|15}}WAYPOINT]
|-
| 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
|-
| has_road
| [0 <nowiki>|</nowiki> 1]
| 1 if this road stop has road
|-
| has_tram
| [0 <nowiki>|</nowiki> 1]
| 1 if this road stop has tram
|-
| road_type
| [Road type <nowiki>|</nowiki> 0xFF]
| Entry from [[NML:Railtypetable|roadtype translation table]], or 0xFF if there is no road
|-
| tram_type
| [Tram type <nowiki>|</nowiki> 0xFF]
| Entry from [[NML:Railtypetable|tramtype translation table]], or 0xFF if there is no tram
|-
| animation_frame
| 0 .. (frame_count - 1)
| Current animation frame, with the maximum defined in the <code style="color:darkgreen">animation_info</code> property.
|-
| 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.
|-
| company_num
| 0 ... 14
| Company number of the roadstop owner.
|-
| 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.
|-
| random_bits_tile
| 0..255
| 8 random bits, specific to this road stop tile.
|-
| waiting_triggers
| 0..255
| Random triggers waiting to be matched. (see [[NML:Random switch|Random switch]])
|-
| drawn_in_gui
| [0 <nowiki>|</nowiki> 1]
| {{ottdp|15}} 1 if this road stop is being drawn in the build window
|}

===Variables that require one or more parameters===

{| class="wikitable sortable"
! name
! arguments
! value range
! comment
|-
| nearby_tile_slope
| x, y offset (-8..7)
|
| See tile_slope
|-
| 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. Only valid for tiles of the same object.
|-
| nearby_tile_is_road_stop
| x, y offset (-8..7)
| 0 .. 1
| Is the given tile a road stop?
|-
| nearby_tile_road_stop_id
| x, y offset (-8..7)
|
| If nearby_tile_same_grf is true, ID of a road stop on a nearby tile
|-
| nearby_tile_same_grf
| x, y offset (-8..7)
| 0 .. 1
| Is a road stop on a nearby tile defined by the same GRF?
|-
| nearby_tile_other_grf
| x, y offset (-8..7)
| 0 .. 1
| Is a road stop on a nearby tile defined by another GRF?
|-
| nearby_tile_original_gfx
| x, y offset (-8..7)
| 0 .. 1
| Is a road stop on a nearby tile using original graphics?
|-
| nearby_tile_same_station
| x, y offset (-8..7)
| 0 .. 1
| Is a road stop on a nearby tile the same station as this?
|-
| nearby_tile_view
| x, y offset (-8..7)
| RST_VIEW_XXX
| The view/rotation of a nearby road stop tile. See [[#List of road stop views|list of road stop views]]
|-
| nearby_tile_different_view
| x, y offset (-8..7)
| 0 .. 1
| Is the view/rotation of a road stop on a nearby tile different to that of this tile?
|-
| nearby_tile_is_drive_through
| x, y offset (-8..7)
| 0 .. 1
| Is nearby road stop tile a drive-through road stop?
|-
| nearby_tile_stop_type
| x, y offset (-8..7)
| RST_TYPE_XXX
| Road stop type of a nearby tile. See stop_type
|-
| nearby_tile_same_stop_type
| x, y offset (-8..7)
| 0 .. 1
| Is the stop type of a nearby road stop tile the same as this tile?
|-
| nearby_tile_grfid
| x, y offset (-8..7)
| [0xFFFFFFFF <nowiki>|</nowiki> 0 <nowiki>|</nowiki> GRFID]
| 0xFFFFFFFF if the nearby tile is not a road stop, 0 if the nearby tile is a non-custom road stop, or else the GRFID of the NewGRF defining the road stop on the nearby tile
|-
| has_badge
| Label from the [[NML:Badgetable|badgetable]].
| [0 <nowiki>|</nowiki> 1]
| {{ottd|15.0}} Check if the road stop has that specific badge attached.
|}

===List of road stop views===

{| class="wikitable sortable"
! Name
! Type
! Meaning
! Value
|-
| RST_VIEW_BAY_NE
| Bay
| Facing north-east
| 0
|-
| RST_VIEW_BAY_SE
| Bay
| Facing south-east
| 1
|-
| RST_VIEW_BAY_SW
| Bay
| Facing south-west
| 2
|-
| RST_VIEW_BAY_NW
| Bay
| Facing north-west
| 3
|-
| RST_VIEW_DRIVE_THROUGH_X
| Drive-through
| X-axis: north-east to south-west
| 4
|-
| RST_VIEW_DRIVE_THROUGH_Y
| Drive-through
| Y-axis: north-west to south-east
| 5
|}

==Road stop callbacks==

{| class="wikitable sortable"
! callback
! return value
! comment
|-
| default
| Sprite layout
| Normal graphics for a road stop placed on the map
|-
| purchase <ref name="notyetbuilt">These callbacks are called when the road stop is not yet built</ref>
| Sprite layout
| Graphics shown in the build menu
|-
| availability
| 0 <nowiki>|</nowiki> 1
| Whether this road stop type is available in the build menu, 1 is available, 0 is unavailable
|-
| 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. 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>).
* <code style="color:darkgreen">extra_callback_info1</code>: 32 random bits, if the object flag OBJ_FLAG_RANDOM_ANIMATION is set.
|-
| 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. Returning a sound effect in the high byte will cause that sound effect to be played.
* <code style="color:darkgreen">extra_callback_info1</code>: 32 random bits, if the object flag OBJ_FLAG_RANDOM_ANIMATION is set.
* <code style="color:darkgreen">getbits(extra_callback_info2, 0, 8)</code>: Reason for the callback trigger, see the [[#Animation triggers| table]] below.
|-
| 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.
|}

===Animation triggers===

{| class="wikitable sortable"
! Animation trigger
! Description
! Happens on
! extra_callback_info2
|-
| ANIM_TRIGGER_ROAD_STOP_BUILT
| Road stop is built
| Newly built tile
|
|-
| ANIM_TRIGGER_ROAD_STOP_NEW_CARGO
| New cargo arrives at station
| All tiles
| Bits 8..15 contain the triggering cargo type
|-
| ANIM_TRIGGER_ROAD_STOP_CARGO_TAKEN
| CRGO removed from station
| All tiles
| Bits 8..15 contain the triggering cargo type
|-
| ANIM_TRIGGER_ROAD_STOP_VEH_ENTER
| Road vehicle enters stop (starts loading/unloading)
| Tile where the vehicle is
|
|-
| ANIM_TRIGGER_ROAD_STOP_VEH_LEAVE
| Road vehicle leaves stop (done loading/unloading)
| Tile where the vehicle is
|
|-
| ANIM_TRIGGER_ROAD_STOP_VEH_LOAD
| Road vehicle loads/unloads cargo
| Tile where the vehicle is
|
|-
| ANIM_TRIGGER_ROAD_STOP_250_TICKS
| Every 250 ticks
| All tiles
|
|-
| {{ottd|15.0}} ANIM_TRIGGER_ROAD_STOP_TILELOOP
| Tile is processed in the periodic processing loop
|
|
|}

NML:Roadstops

2026-06-08T07:20:01Z

Rito12: /* Variables without a parameter */ It is roadstop not vehicle.

{{NMLNavPropVarCB}}

Road stops can only be defined in OpenTTD {{ottd|14.0}} or later.

==Road stop IDs==
OpenTTD supports 64000 road stop types per game.

Rpad stop IDs are NewGRF-local and can therefore freely be chosen within the ID ranges.

A road stop is allocated by setting the 'class'-property, which should therefore be set first.

Road stop sprite layouts should always set a suitable ground tile sprite, and should not assume that a road type GRF will provide suitable overlay sprites.
Suggested ground sprite IDs include: GROUNDSPRITE_ROAD_X/GROUNDSPRITE_ROAD_Y (straight road on grass), 1314/1313 (straight road with pavement), 2692 - 2695 (bay road stop ground).

==Road stop properties==

{| class="wikitable sortable"
! property
! value range
! comment
|-
| class
| String literal of length 4
|
'''This property ''must'' be set first, before any other properties or graphics.''' 
Road stops belonging to the same class are grouped in the GUI. 
There is one special class:
* "WAYP": {{ottdp|15.0|no}} The road stop type will be shown in the waypoint construction window, instead of the station construction window.
{{ottdp|15}} Station classes which start with the byte FF are considered waypoint classes, and will appear in the waypoint construction window instead of the station construction window.
|-
| classname
| string
| You only need to set this for one road stop in every class.
|-
| name
| string
|
|-
| availability_type
| RST_AVAILABILITY_TYPE_XXX
| XXX = [PASSENGER <nowiki>|</nowiki> FREIGHT <nowiki>|</nowiki> ALL]
The default value is RST_AVAILABILITY_TYPE_ALL
|-
| draw_mode
| bitmask(RST_DRAW_FLAG_XXX, ...)
| See [[#List of draw mode flags|list of draw mode flags]]
The default value is bitmask(RST_DRAW_FLAG_BAY_ROAD, RST_DRAW_FLAG_DRIVE_THROUGH_ROAD_OVERLAY)
|-
| cargo_random_triggers
| Array of cargo labels from the [[NML:Cargotable|cargotable]]
| Cargo types, which will [[NML:Random_switch#Stations|trigger re-randomization]] when delivered, loaded or unloaded at the station.
|-
| 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
|
|
See [[#Animation_triggers|list of animation triggers]]
|-
| general_flags
| bitmask(RST_GENERAL_FLAG_XXX, ...)
| See [[#List of general flags|list of general flags]]
|-
| cost_multipliers
| [build_cost, clear_cost]
| Build and clear cost multipliers, 16 is the same as a non-NewGRF road stop
|-
| badges
| Array of badge labels from the [[NML:Badgetable|badgetable]].
| Since {{ottd|15.0}}
|-
| heights
| Array of unsigned ints
| Since {{ottd|15.0}} {{nml|0.8.1}} 
Each element of array corresponds to one [[#List of road stop views|view]]. 
Specifies the bridge height so bridges can be build above the road stop.
The bridge height defines minimum clearances required for a bridge for the sprite layouts of this road stop (or zero to not allow any bridge).
Values are given in "height level" units (1 level == 8px).
|-
| blocked_pillars
| Array of <code>bitmask(BRIDGE_PILLAR_XXX, ...)</code>
| Since {{ottd|15.0}} {{nml|0.8.1}} 
Each element of array corresponds to one [[#List of road stop views|view]]. 
Allows information to provided about blocked bridge pillars to assist the game in hiding pillars if necessary depending on what is above the road stop tile. Blocking a pillar prevents the pillar from being drawn. It does not prevent the road stop being bridgeable.
See [[#List_of_bridge_pillar_flags|list of bridge pillar flags]].
|}

===List of draw mode flags===

{| class="wikitable sortable"
! Name
! Meaning
|-
| RST_DRAW_FLAG_BAY_ROAD
| Draw road type ground sprite for bay stops.
|-
| RST_DRAW_FLAG_DRIVE_THROUGH_ROAD_OVERLAY
| Draw road overlays for drive-through stops.
|-
| RST_DRAW_FLAG_WAYPOINT_GROUND
| {{ottdp|15.0|no}} Draw spritelayout ground sprite on top of underlying road (if unset, the spritelayout ground sprite is not drawn).
|}

===List of general flags===

{| class="wikitable sortable"
! Name
! Meaning
|-
| RST_GENERAL_FLAG_RANDOM_ANIMATION
| Animation callback requires random bits in variable extra_callback_info1.
|-
| RST_GENERAL_FLAG_NO_CATENARY
| Do not show catenary graphics.
|-
| RST_GENERAL_FLAG_DRIVE_THROUGH_ONLY
| Only allow drive-through stops (not bay stops).
|-
| RST_GENERAL_FLAG_NO_AUTO_ROAD_CONNECTION
| Do not automatically build connecting road pieces.
|-
| RST_GENERAL_FLAG_BUILD_MENU_ROAD_ONLY
| Only show in the road build menu (not tram).
|-
| RST_GENERAL_FLAG_BUILD_MENU_TRAM_ONLY
| Only show in the tram build menu (not road).
|-
| RST_GENERAL_FLAG_DRAW_MODE_REGISTER
| {{ottdp|15.0|no}} Read the road stop draw mode from variable 0x100 (set using STORE_TEMP), this overrides the draw_mode property.
|}

===List of bridge pillar flags===

{| class="wikitable sortable"
! Name
! Meaning
|-
| BRIDGE_PILLAR_CORNER_W
| Tile layout blocks a pillar on the west corner of the tile.
|-
| BRIDGE_PILLAR_CORNER_S
| Tile layout blocks a pillar on the south corner of the tile.
|-
| BRIDGE_PILLAR_CORNER_E
| Tile layout blocks a pillar on the east corner of the tile.
|-
| BRIDGE_PILLAR_CORNER_N
| Tile layout blocks a pillar on the north corner of the tile.
|-
| BRIDGE_PILLAR_EDGE_NE
| Tile layout blocks a wall on the north east side of the tile.
|-
| BRIDGE_PILLAR_EDGE_SE
| Tile layout blocks a wall on the south east side of the tile.
|-
| BRIDGE_PILLAR_EDGE_SW
| Tile layout blocks a wall on the south west side of the tile.
|-
| BRIDGE_PILLAR_EDGE_NW
| Tile layout blocks a wall on the north west side of the tile.
|}

==Road stop variables==

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

{| class="wikitable sortable"
! name
! value range
! comment
|-
| random_bits_station
| 0..65535
| 16 random bits, shared between all station sections (rail station sections, airports, ...)
|-
| 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:Stations|stations]] and [[NML:Airports|airports]]. They all require a single argument: a cargo type from your [[NML:Cargotable|cargo translation table]].

{| class="wikitable sortable"
! 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="wikitable sortable"
! name
! value range
! comment
|-
| view
| RST_VIEW_XXX
| The view/rotation of the road stop. See [[#List of road stop views|list of road stop views]]
|-
| stop_type
| RST_TYPE_XXX
| XXX = [BUS <nowiki>|</nowiki> TRUCK <nowiki>|</nowiki> {{ottdp|15}}WAYPOINT]
|-
| 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
|-
| has_road
| [0 <nowiki>|</nowiki> 1]
| 1 if this road stop has road
|-
| has_tram
| [0 <nowiki>|</nowiki> 1]
| 1 if this road stop has tram
|-
| road_type
| [Road type <nowiki>|</nowiki> 0xFF]
| Entry from [[NML:Railtypetable|roadtype translation table]], or 0xFF if there is no road
|-
| tram_type
| [Tram type <nowiki>|</nowiki> 0xFF]
| Entry from [[NML:Railtypetable|tramtype translation table]], or 0xFF if there is no tram
|-
| animation_frame
| 0 .. (frame_count - 1)
| Current animation frame, with the maximum defined in the <code style="color:darkgreen">animation_info</code> property.
|-
| 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.
|-
| company_num
| 0 ... 14
| Company number of the roadstop 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.
|-
| random_bits_tile
| 0..255
| 8 random bits, specific to this road stop tile.
|-
| waiting_triggers
| 0..255
| Random triggers waiting to be matched. (see [[NML:Random switch|Random switch]])
|-
| drawn_in_gui
| [0 <nowiki>|</nowiki> 1]
| {{ottdp|15}} 1 if this road stop is being drawn in the build window
|}

===Variables that require one or more parameters===

{| class="wikitable sortable"
! name
! arguments
! value range
! comment
|-
| nearby_tile_slope
| x, y offset (-8..7)
|
| See tile_slope
|-
| 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. Only valid for tiles of the same object.
|-
| nearby_tile_is_road_stop
| x, y offset (-8..7)
| 0 .. 1
| Is the given tile a road stop?
|-
| nearby_tile_road_stop_id
| x, y offset (-8..7)
|
| If nearby_tile_same_grf is true, ID of a road stop on a nearby tile
|-
| nearby_tile_same_grf
| x, y offset (-8..7)
| 0 .. 1
| Is a road stop on a nearby tile defined by the same GRF?
|-
| nearby_tile_other_grf
| x, y offset (-8..7)
| 0 .. 1
| Is a road stop on a nearby tile defined by another GRF?
|-
| nearby_tile_original_gfx
| x, y offset (-8..7)
| 0 .. 1
| Is a road stop on a nearby tile using original graphics?
|-
| nearby_tile_same_station
| x, y offset (-8..7)
| 0 .. 1
| Is a road stop on a nearby tile the same station as this?
|-
| nearby_tile_view
| x, y offset (-8..7)
| RST_VIEW_XXX
| The view/rotation of a nearby road stop tile. See [[#List of road stop views|list of road stop views]]
|-
| nearby_tile_different_view
| x, y offset (-8..7)
| 0 .. 1
| Is the view/rotation of a road stop on a nearby tile different to that of this tile?
|-
| nearby_tile_is_drive_through
| x, y offset (-8..7)
| 0 .. 1
| Is nearby road stop tile a drive-through road stop?
|-
| nearby_tile_stop_type
| x, y offset (-8..7)
| RST_TYPE_XXX
| Road stop type of a nearby tile. See stop_type
|-
| nearby_tile_same_stop_type
| x, y offset (-8..7)
| 0 .. 1
| Is the stop type of a nearby road stop tile the same as this tile?
|-
| nearby_tile_grfid
| x, y offset (-8..7)
| [0xFFFFFFFF <nowiki>|</nowiki> 0 <nowiki>|</nowiki> GRFID]
| 0xFFFFFFFF if the nearby tile is not a road stop, 0 if the nearby tile is a non-custom road stop, or else the GRFID of the NewGRF defining the road stop on the nearby tile
|-
| has_badge
| Label from the [[NML:Badgetable|badgetable]].
| [0 <nowiki>|</nowiki> 1]
| {{ottd|15.0}} Check if the road stop has that specific badge attached.
|}

===List of road stop views===

{| class="wikitable sortable"
! Name
! Type
! Meaning
! Value
|-
| RST_VIEW_BAY_NE
| Bay
| Facing north-east
| 0
|-
| RST_VIEW_BAY_SE
| Bay
| Facing south-east
| 1
|-
| RST_VIEW_BAY_SW
| Bay
| Facing south-west
| 2
|-
| RST_VIEW_BAY_NW
| Bay
| Facing north-west
| 3
|-
| RST_VIEW_DRIVE_THROUGH_X
| Drive-through
| X-axis: north-east to south-west
| 4
|-
| RST_VIEW_DRIVE_THROUGH_Y
| Drive-through
| Y-axis: north-west to south-east
| 5
|}

==Road stop callbacks==

{| class="wikitable sortable"
! callback
! return value
! comment
|-
| default
| Sprite layout
| Normal graphics for a road stop placed on the map
|-
| purchase <ref name="notyetbuilt">These callbacks are called when the road stop is not yet built</ref>
| Sprite layout
| Graphics shown in the build menu
|-
| availability
| 0 <nowiki>|</nowiki> 1
| Whether this road stop type is available in the build menu, 1 is available, 0 is unavailable
|-
| 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. 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>).
* <code style="color:darkgreen">extra_callback_info1</code>: 32 random bits, if the object flag OBJ_FLAG_RANDOM_ANIMATION is set.
|-
| 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. Returning a sound effect in the high byte will cause that sound effect to be played.
* <code style="color:darkgreen">extra_callback_info1</code>: 32 random bits, if the object flag OBJ_FLAG_RANDOM_ANIMATION is set.
* <code style="color:darkgreen">getbits(extra_callback_info2, 0, 8)</code>: Reason for the callback trigger, see the [[#Animation triggers| table]] below.
|-
| 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.
|}

===Animation triggers===

{| class="wikitable sortable"
! Animation trigger
! Description
! Happens on
! extra_callback_info2
|-
| ANIM_TRIGGER_ROAD_STOP_BUILT
| Road stop is built
| Newly built tile
|
|-
| ANIM_TRIGGER_ROAD_STOP_NEW_CARGO
| New cargo arrives at station
| All tiles
| Bits 8..15 contain the triggering cargo type
|-
| ANIM_TRIGGER_ROAD_STOP_CARGO_TAKEN
| CRGO removed from station
| All tiles
| Bits 8..15 contain the triggering cargo type
|-
| ANIM_TRIGGER_ROAD_STOP_VEH_ENTER
| Road vehicle enters stop (starts loading/unloading)
| Tile where the vehicle is
|
|-
| ANIM_TRIGGER_ROAD_STOP_VEH_LEAVE
| Road vehicle leaves stop (done loading/unloading)
| Tile where the vehicle is
|
|-
| ANIM_TRIGGER_ROAD_STOP_VEH_LOAD
| Road vehicle loads/unloads cargo
| Tile where the vehicle is
|
|-
| ANIM_TRIGGER_ROAD_STOP_250_TICKS
| Every 250 ticks
| All tiles
|
|-
| {{ottd|15.0}} ANIM_TRIGGER_ROAD_STOP_TILELOOP
| Tile is processed in the periodic processing loop
|
|
|}

NML:Roadstops

2026-06-07T16:33:17Z

Rito12: /* Variables that require one or more parameters */ Is should be If

{{NMLNavPropVarCB}}

Road stops can only be defined in OpenTTD {{ottd|14.0}} or later.

==Road stop IDs==
OpenTTD supports 64000 road stop types per game.

Rpad stop IDs are NewGRF-local and can therefore freely be chosen within the ID ranges.

A road stop is allocated by setting the 'class'-property, which should therefore be set first.

Road stop sprite layouts should always set a suitable ground tile sprite, and should not assume that a road type GRF will provide suitable overlay sprites.
Suggested ground sprite IDs include: GROUNDSPRITE_ROAD_X/GROUNDSPRITE_ROAD_Y (straight road on grass), 1314/1313 (straight road with pavement), 2692 - 2695 (bay road stop ground).

==Road stop properties==

{| class="wikitable sortable"
! property
! value range
! comment
|-
| class
| String literal of length 4
|
'''This property ''must'' be set first, before any other properties or graphics.''' 
Road stops belonging to the same class are grouped in the GUI. 
There is one special class:
* "WAYP": {{ottdp|15.0|no}} The road stop type will be shown in the waypoint construction window, instead of the station construction window.
{{ottdp|15}} Station classes which start with the byte FF are considered waypoint classes, and will appear in the waypoint construction window instead of the station construction window.
|-
| classname
| string
| You only need to set this for one road stop in every class.
|-
| name
| string
|
|-
| availability_type
| RST_AVAILABILITY_TYPE_XXX
| XXX = [PASSENGER <nowiki>|</nowiki> FREIGHT <nowiki>|</nowiki> ALL]
The default value is RST_AVAILABILITY_TYPE_ALL
|-
| draw_mode
| bitmask(RST_DRAW_FLAG_XXX, ...)
| See [[#List of draw mode flags|list of draw mode flags]]
The default value is bitmask(RST_DRAW_FLAG_BAY_ROAD, RST_DRAW_FLAG_DRIVE_THROUGH_ROAD_OVERLAY)
|-
| cargo_random_triggers
| Array of cargo labels from the [[NML:Cargotable|cargotable]]
| Cargo types, which will [[NML:Random_switch#Stations|trigger re-randomization]] when delivered, loaded or unloaded at the station.
|-
| 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
|
|
See [[#Animation_triggers|list of animation triggers]]
|-
| general_flags
| bitmask(RST_GENERAL_FLAG_XXX, ...)
| See [[#List of general flags|list of general flags]]
|-
| cost_multipliers
| [build_cost, clear_cost]
| Build and clear cost multipliers, 16 is the same as a non-NewGRF road stop
|-
| badges
| Array of badge labels from the [[NML:Badgetable|badgetable]].
| Since {{ottd|15.0}}
|-
| heights
| Array of unsigned ints
| Since {{ottd|15.0}} {{nml|0.8.1}} 
Each element of array corresponds to one [[#List of road stop views|view]]. 
Specifies the bridge height so bridges can be build above the road stop.
The bridge height defines minimum clearances required for a bridge for the sprite layouts of this road stop (or zero to not allow any bridge).
Values are given in "height level" units (1 level == 8px).
|-
| blocked_pillars
| Array of <code>bitmask(BRIDGE_PILLAR_XXX, ...)</code>
| Since {{ottd|15.0}} {{nml|0.8.1}} 
Each element of array corresponds to one [[#List of road stop views|view]]. 
Allows information to provided about blocked bridge pillars to assist the game in hiding pillars if necessary depending on what is above the road stop tile. Blocking a pillar prevents the pillar from being drawn. It does not prevent the road stop being bridgeable.
See [[#List_of_bridge_pillar_flags|list of bridge pillar flags]].
|}

===List of draw mode flags===

{| class="wikitable sortable"
! Name
! Meaning
|-
| RST_DRAW_FLAG_BAY_ROAD
| Draw road type ground sprite for bay stops.
|-
| RST_DRAW_FLAG_DRIVE_THROUGH_ROAD_OVERLAY
| Draw road overlays for drive-through stops.
|-
| RST_DRAW_FLAG_WAYPOINT_GROUND
| {{ottdp|15.0|no}} Draw spritelayout ground sprite on top of underlying road (if unset, the spritelayout ground sprite is not drawn).
|}

===List of general flags===

{| class="wikitable sortable"
! Name
! Meaning
|-
| RST_GENERAL_FLAG_RANDOM_ANIMATION
| Animation callback requires random bits in variable extra_callback_info1.
|-
| RST_GENERAL_FLAG_NO_CATENARY
| Do not show catenary graphics.
|-
| RST_GENERAL_FLAG_DRIVE_THROUGH_ONLY
| Only allow drive-through stops (not bay stops).
|-
| RST_GENERAL_FLAG_NO_AUTO_ROAD_CONNECTION
| Do not automatically build connecting road pieces.
|-
| RST_GENERAL_FLAG_BUILD_MENU_ROAD_ONLY
| Only show in the road build menu (not tram).
|-
| RST_GENERAL_FLAG_BUILD_MENU_TRAM_ONLY
| Only show in the tram build menu (not road).
|-
| RST_GENERAL_FLAG_DRAW_MODE_REGISTER
| {{ottdp|15.0|no}} Read the road stop draw mode from variable 0x100 (set using STORE_TEMP), this overrides the draw_mode property.
|}

===List of bridge pillar flags===

{| class="wikitable sortable"
! Name
! Meaning
|-
| BRIDGE_PILLAR_CORNER_W
| Tile layout blocks a pillar on the west corner of the tile.
|-
| BRIDGE_PILLAR_CORNER_S
| Tile layout blocks a pillar on the south corner of the tile.
|-
| BRIDGE_PILLAR_CORNER_E
| Tile layout blocks a pillar on the east corner of the tile.
|-
| BRIDGE_PILLAR_CORNER_N
| Tile layout blocks a pillar on the north corner of the tile.
|-
| BRIDGE_PILLAR_EDGE_NE
| Tile layout blocks a wall on the north east side of the tile.
|-
| BRIDGE_PILLAR_EDGE_SE
| Tile layout blocks a wall on the south east side of the tile.
|-
| BRIDGE_PILLAR_EDGE_SW
| Tile layout blocks a wall on the south west side of the tile.
|-
| BRIDGE_PILLAR_EDGE_NW
| Tile layout blocks a wall on the north west side of the tile.
|}

==Road stop variables==

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

{| class="wikitable sortable"
! name
! value range
! comment
|-
| random_bits_station
| 0..65535
| 16 random bits, shared between all station sections (rail station sections, airports, ...)
|-
| 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:Stations|stations]] and [[NML:Airports|airports]]. They all require a single argument: a cargo type from your [[NML:Cargotable|cargo translation table]].

{| class="wikitable sortable"
! 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="wikitable sortable"
! name
! value range
! comment
|-
| view
| RST_VIEW_XXX
| The view/rotation of the road stop. See [[#List of road stop views|list of road stop views]]
|-
| stop_type
| RST_TYPE_XXX
| XXX = [BUS <nowiki>|</nowiki> TRUCK <nowiki>|</nowiki> {{ottdp|15}}WAYPOINT]
|-
| 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
|-
| has_road
| [0 <nowiki>|</nowiki> 1]
| 1 if this road stop has road
|-
| has_tram
| [0 <nowiki>|</nowiki> 1]
| 1 if this road stop has tram
|-
| road_type
| [Road type <nowiki>|</nowiki> 0xFF]
| Entry from [[NML:Railtypetable|roadtype translation table]], or 0xFF if there is no road
|-
| tram_type
| [Tram type <nowiki>|</nowiki> 0xFF]
| Entry from [[NML:Railtypetable|tramtype translation table]], or 0xFF if there is no tram
|-
| animation_frame
| 0 .. (frame_count - 1)
| Current animation frame, with the maximum defined in the <code style="color:darkgreen">animation_info</code> property.
|-
| 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.
|-
| 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.
|-
| random_bits_tile
| 0..255
| 8 random bits, specific to this road stop tile.
|-
| waiting_triggers
| 0..255
| Random triggers waiting to be matched. (see [[NML:Random switch|Random switch]])
|-
| drawn_in_gui
| [0 <nowiki>|</nowiki> 1]
| {{ottdp|15}} 1 if this road stop is being drawn in the build window
|}

===Variables that require one or more parameters===

{| class="wikitable sortable"
! name
! arguments
! value range
! comment
|-
| nearby_tile_slope
| x, y offset (-8..7)
|
| See tile_slope
|-
| 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. Only valid for tiles of the same object.
|-
| nearby_tile_is_road_stop
| x, y offset (-8..7)
| 0 .. 1
| Is the given tile a road stop?
|-
| nearby_tile_road_stop_id
| x, y offset (-8..7)
|
| If nearby_tile_same_grf is true, ID of a road stop on a nearby tile
|-
| nearby_tile_same_grf
| x, y offset (-8..7)
| 0 .. 1
| Is a road stop on a nearby tile defined by the same GRF?
|-
| nearby_tile_other_grf
| x, y offset (-8..7)
| 0 .. 1
| Is a road stop on a nearby tile defined by another GRF?
|-
| nearby_tile_original_gfx
| x, y offset (-8..7)
| 0 .. 1
| Is a road stop on a nearby tile using original graphics?
|-
| nearby_tile_same_station
| x, y offset (-8..7)
| 0 .. 1
| Is a road stop on a nearby tile the same station as this?
|-
| nearby_tile_view
| x, y offset (-8..7)
| RST_VIEW_XXX
| The view/rotation of a nearby road stop tile. See [[#List of road stop views|list of road stop views]]
|-
| nearby_tile_different_view
| x, y offset (-8..7)
| 0 .. 1
| Is the view/rotation of a road stop on a nearby tile different to that of this tile?
|-
| nearby_tile_is_drive_through
| x, y offset (-8..7)
| 0 .. 1
| Is nearby road stop tile a drive-through road stop?
|-
| nearby_tile_stop_type
| x, y offset (-8..7)
| RST_TYPE_XXX
| Road stop type of a nearby tile. See stop_type
|-
| nearby_tile_same_stop_type
| x, y offset (-8..7)
| 0 .. 1
| Is the stop type of a nearby road stop tile the same as this tile?
|-
| nearby_tile_grfid
| x, y offset (-8..7)
| [0xFFFFFFFF <nowiki>|</nowiki> 0 <nowiki>|</nowiki> GRFID]
| 0xFFFFFFFF if the nearby tile is not a road stop, 0 if the nearby tile is a non-custom road stop, or else the GRFID of the NewGRF defining the road stop on the nearby tile
|-
| has_badge
| Label from the [[NML:Badgetable|badgetable]].
| [0 <nowiki>|</nowiki> 1]
| {{ottd|15.0}} Check if the road stop has that specific badge attached.
|}

===List of road stop views===

{| class="wikitable sortable"
! Name
! Type
! Meaning
! Value
|-
| RST_VIEW_BAY_NE
| Bay
| Facing north-east
| 0
|-
| RST_VIEW_BAY_SE
| Bay
| Facing south-east
| 1
|-
| RST_VIEW_BAY_SW
| Bay
| Facing south-west
| 2
|-
| RST_VIEW_BAY_NW
| Bay
| Facing north-west
| 3
|-
| RST_VIEW_DRIVE_THROUGH_X
| Drive-through
| X-axis: north-east to south-west
| 4
|-
| RST_VIEW_DRIVE_THROUGH_Y
| Drive-through
| Y-axis: north-west to south-east
| 5
|}

==Road stop callbacks==

{| class="wikitable sortable"
! callback
! return value
! comment
|-
| default
| Sprite layout
| Normal graphics for a road stop placed on the map
|-
| purchase <ref name="notyetbuilt">These callbacks are called when the road stop is not yet built</ref>
| Sprite layout
| Graphics shown in the build menu
|-
| availability
| 0 <nowiki>|</nowiki> 1
| Whether this road stop type is available in the build menu, 1 is available, 0 is unavailable
|-
| 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. 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>).
* <code style="color:darkgreen">extra_callback_info1</code>: 32 random bits, if the object flag OBJ_FLAG_RANDOM_ANIMATION is set.
|-
| 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. Returning a sound effect in the high byte will cause that sound effect to be played.
* <code style="color:darkgreen">extra_callback_info1</code>: 32 random bits, if the object flag OBJ_FLAG_RANDOM_ANIMATION is set.
* <code style="color:darkgreen">getbits(extra_callback_info2, 0, 8)</code>: Reason for the callback trigger, see the [[#Animation triggers| table]] below.
|-
| 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.
|}

===Animation triggers===

{| class="wikitable sortable"
! Animation trigger
! Description
! Happens on
! extra_callback_info2
|-
| ANIM_TRIGGER_ROAD_STOP_BUILT
| Road stop is built
| Newly built tile
|
|-
| ANIM_TRIGGER_ROAD_STOP_NEW_CARGO
| New cargo arrives at station
| All tiles
| Bits 8..15 contain the triggering cargo type
|-
| ANIM_TRIGGER_ROAD_STOP_CARGO_TAKEN
| CRGO removed from station
| All tiles
| Bits 8..15 contain the triggering cargo type
|-
| ANIM_TRIGGER_ROAD_STOP_VEH_ENTER
| Road vehicle enters stop (starts loading/unloading)
| Tile where the vehicle is
|
|-
| ANIM_TRIGGER_ROAD_STOP_VEH_LEAVE
| Road vehicle leaves stop (done loading/unloading)
| Tile where the vehicle is
|
|-
| ANIM_TRIGGER_ROAD_STOP_VEH_LOAD
| Road vehicle loads/unloads cargo
| Tile where the vehicle is
|
|-
| ANIM_TRIGGER_ROAD_STOP_250_TICKS
| Every 250 ticks
| All tiles
|
|-
| {{ottd|15.0}} ANIM_TRIGGER_ROAD_STOP_TILELOOP
| Tile is processed in the periodic processing loop
|
|
|}

VariationalAction2/Stations

2026-06-05T16:45:15Z

Rito12: /* Description */ add var 6B

==Introduction==

Rail stations share a number of variables with airports. The common variables are documented on a [[VariationalAction2/BaseStation|separate page]]

== Variables ==
{| |-
!Variable!!Version!![[GRFActionsDetailed|'''Size''']]!!Description
|-
|10||{{ottdp|0.7|2.5}}||D||Additional information for sprite selection - see [[Action0/Stations#General_Flags_.2813.29|General station flags]] and [[AdvancedSpriteLayout]]
|-
|40||{{ottdp|0.6|2.5}}||D||Platform info and relative position
|-
|41||{{ottdp|0.6|2.5}}||D||Platform info and relative position for individually built sections
|-
|42||{{ottdp|0.6|2.5}}||D||Terrain and track type
|-
|43 <ref>{{ottdp|1.2|2.5|ottdrev=r22848|ttdprev=2.5 beta 2}} Available in the purchase list as well.</ref>||{{ottdp|1.2|2.5|ottdrev=r22848}}||D||Player info, see [[VarAction2Vehicles#Player info (43)|vehicle variable 43]]
|-
|44||{{ottdp|0.7|2.5}}||B||Path-based signalling info
|-
|45||{{ottdp|0.6|2.5}}||W||Rail continuation info
|-
|46,47||{{ottdp|0.6|2.5}}||D||Platform info, counted from the middle
|-
|48|| || ||See [[VariationalAction2/BaseStation|Base Stations]].
|-
|49||{{ottdp|0.6|2.5}}||D||Platform info and relative position of same-direction section
|-
|4A||{{ottdp|0.7|2.5}}||B||Current animation frame
|-
|60-65|| || ||See [[VariationalAction2/BaseStation|Base Stations]].
|-
|66||{{ottdp|0.6|2.5}}||D||Animation frame of nearby tile
|-
|67||{{ottdp|0.6|2.6}}||D||Land info of nearby tiles
|-
|68||{{ottdp|0.6|2.6}}||D||Station info of nearby tiles
|-
|69|| || ||See [[VariationalAction2/BaseStation|Base Stations]].
|-
|6A||{{ottdp|1.10|no|ottdrev=5df01bf}}||D||GRFID of nearby tiles
|-
|6B||{{ottdp|14.0|no|ottdrev=8d62a8f}}||D||16-bit station ID of nearby tiles
|-
|80||{{ottdp|no|no}} <ref>Works in TTDPatch for sufficiently small stations.</ref>||B||Number and length of train platforms
|}
<references/>

For other 80+x variables confer the [http://marcin.ttdpatch.net/sv1codec/TTD-locations.html#_StationArray TTD station structure]. Note that you have to subtract 0x10 from the offsets there, or else the facility bit mask and construction date would not be accessible; instead you lose access to variables 00..0F which are meaningless anyway.

'''WARNING''': Please do not use variables 8C..EB directly. The meaning of these variables changes if the newcargos switch is on. Use the variables 60..64 instead (see below). Those always work correctly.

== Description ==
=== Platform info (40, 41, 46, 47, 49) ===

Variables 40, 41, 46, 47 and 49 all return information about the current tile, which platform it is on and how far along the platform. The difference is in the section of the station that they consider.

{| |-
!Variables!!Regular station!!Irregular station
|-
|40, 46||Whole station||Counting entire length and all adjacent platforms
|-
|41, 47||Individually built sections||
|-
|49||Whole station||Counting length and platforms that have the same direction
|}

The term "counting" here refers to starting at the tile in question, and counting tiles in all four directions. The two directions aligned with the station direction will be the length of the station, and the other two directions give the number of platforms. For variables 40 and 46, this counting stops at the edge of the station, i.e. the first non-station tile. For variable 49, it stops either at the edge, or at a station tile that is in the wrong direction.  The resulting information is probably not really useful in the case of irregular stations, with the exception of edge detection. To correctly detect edges, you have the choice of either the station->non-station transition (vars. 40, 46), or additional an opposite-direction transition (var. 49).

Variable 41 is largely unaffected by irregular stations, because it only refers to individually built sections. However, when these individual sections are built over existing tiles, the var. 41 information of surrounding tiles changes as well, due to an internal limitation in how it is stored.

For variables 40, 41 and 49, the position is counted from the northern most edge of the station, and returned in the form TNLcCpP, where:

{| |-
!Variable!!Bits!!Meaning
|-
|T||8||Tile type: the current tile type/layout
{{ottdp|no|}} In TTDPatch this information is only available during callback 14 (and via variable 10 during callback 24).
|-
|N||4||Total number of platforms
|-
|L||4||Total platform length
|-
|c||4||Platform number current being drawn, counted from the end (starting at zero)
|-
|C||4||Platform number currently being drawn (starting from zero)
|-
|p||4||Position along this platform counted from the end, zero at the end
|-
|P||4||Position along this platform, zero at the beginning
|}

Here, the "beginning" of a station is its northern-most (up on the screen) tile, and the "end" is the southern-most (down on the screen) tile. Each variable consists of 4 bits.

For variables 46 and 47, the position is counted from the middle, i.e. the center tile has C=0 and P=0. For even lengths and numbers of platforms, the middle tile is at position L/2 resp. N/2, e.g. for length 6, it is tile 3, which is the fourth tile. The return format is xTNLxxCP, where T, N and L are as above, and C and P are the positions counted from the middle.

Since C and P can have negative numbers, here's how this is encoded:

{| |-
!Hex!!Binary!!Decimal
|-
|0||0000||0
|-
|1||0001||1
|-
|7||0111||7
|-
|8||1000||-8
|-
|9||1001||-7
|-
|E||1110||-2
|-
|F||1111||-1
|}

The counting goes like this, preferring an extra negative number for an even count (because there are 8 negative numbers available but only 7 positive ones):

{| |-
!Count!!Numbers
|-
|1||<pre> 0</pre>
|-
|2||<pre> -1 0</pre>
|-
|3||<pre> -1 0 1</pre>
|-
|4||<pre> -2 -1 0 1</pre>
|-
|5||<pre> -2 -1 0 1 2</pre>
|-
|6||<pre>-3 -2 -1 0 1 2</pre>
|}

(etc.)

=== Terrain and track type (42) ===

Variable 42 is of the format xxxxttTT, where TT is the terrain type and tt is the (translated) railway track type.

They can have the following values:

{| |-
!TT!!Meaning
|-
|0||normal (grass)
|-
|1||desert
|-
|2||rainforest
|-
|4||on or above snowline
|}

If no railtype translation table is present in the GRF, then the default translation table is used:
{| |-
!tt!!Meaning
|-
|00||railroad, regular
|-
|01||railroad, electrified
|-
|02||monorail
|-
|03||maglev
|}

If the railtype is not present in the table, then tt returns FF.

=== Path-based signalling info (44) ===

This returns the following value in bits 0-2: (bit 2 only available from alpha 47 and up)

{| |-
!State!!Value (binary)!!Value (decimal)
|-
|Reserved||111||7
|-
|Not reserved||100||4
|-
|No PBS||010||2
|}

At the moment, PBS on/off refers to the switch setting, in a future alpha version it will actually refer to whether the switch is on ''and'' the current block actually uses PBS.

The bits are defined this way to allow easy fallback to non-PBS cases. If you need graphics to show the "unreserved" state in non-PBS cases, use bit 0, but if you need the "reserved" state in non-PBS cases, use bit 1. To explicitly check whether PBS is active or not, use bit 2.

All other bits are reserved and must be masked out.

=== Rail continuation info (45) ===

This variable returns 16 bits of info whether the rail tracks continue in the eight tiles adjacent to the station tile.

{| |-
!Bit!!Value!!Set if rail continues in direction of...
|-
|0||01||+Length
|-
|1||02||-Length
|-
|2||04||+Platforms
|-
|3||08||-Platforms
|-
|4||10||+Length, +Platforms
|-
|5||20||-Length, +Platforms
|-
|6||40||+Length, -Platforms
|-
|7||80||-Length, -Platforms
|}

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

[[File:station_var45.png]]

Bits 0 to 3 are set if there is track on the given tile, and it has a connection to the station tile. For bits 2, 3, the station of course has itself no connection to those tiles, but this doesn't matter for this variable. Bits 4 to 7 check connections to the neighbouring platform tile, i.e. bits 4 and 5 resp. 6 and 7 indicate a connection from that tile to tile 2 resp. 3. (This has changed again with 2.5 beta 4 r325.)

Bits 8..15 repeat the above, but are set if there are any train tracks on the tile and disregard whether the track is connected to the station or not entirely.

=== Animation frame of nearby tile (66) ===

(From TTDPatch 2.5 beta 5)

The parameter defines the offset relative to the current tile. Both nibbles are considered signed (that is, 8h=-8, 9h=-7, ...., Fh=-1, 0h=0, 1h=1, ..., 7h=7). The high nibble contains the amount to move sideways (between platforms), the low one is the amount to move along the platform. Negative offsets move northwards, positive ones southwards. If the selected tile is a rail station tile that belongs to the current station, its animation state is returned. Otherwise, FFFFFFFFh is returned.

=== Land info of nearby tiles (67) ===

This variable works like [[VarAction2IndustryTiles#Land_info_of_nearby_tiles_60_|industry tile variable 60]], except for three things:
* The offsets in the parameter are interpreted relatively to the alignment of the station, the same way as for variable 66
* The '''ss''' part is "mirrored" (bit 0 and 2 swapped) for the NW-SE orientation; this will allow you to handle analogous slopes of the two orientations without checking the orientation explicitly (since TTDPatch 2.6 r1693)
* Bit 0 of the '''bb''' part is undefined

=== Station info of nearby tiles (68) ===

The parameter of this variable works the same way as the parameter of variable 66. The returned value is FFFFFFFFh if the selected tile isn't a railway station tile. Otherwise, the returned value can be separated to the following parts:

{| |-
!Bits!!Meaning
|-
|0..7||If the tile is defined in the current GRF, this is the setID used in the definition. Otherwise, the content is undefined.
|-
|8..9||0 - the tile uses original TTD graphics

1 - the tile is defined in the current GRF

2 - the tile is defined in another GRF
|-
|10||set if the selected tile belongs to the current station, clear otherwise
|-
|11||clear if the selected tile is parallel with the current one, set if perpendicular to it
|-
|12..13||0 - plain platform

1 - platform with building

2 - platform with roof, left side

3 - platform with roof, right side
|-
|14..31||Undefined, reserved for future use
|}

=== GRFID of nearby station tile (6A) ===

The parameter of this variable works the same way as the parameter of variable 66.
The returned value is one of the following:
* '''FFFFFFFFh''' if the selected tile isn't a station tile
* '''00000000h''' if the selected station is a default station (no NewGRF station)
* otherwise, the GRFID of the GRF which defined the type of the selected station

=== Station id of nearby tiles (6B) ===

The parameter of this variable works the same way as the parameter of variable 66. The returned value is 0xFFFFFFFF if the selected tile isn't a railway station tile and 0xFFFE if it is from another grf. Otherwise, the returned value is a 16 bit station id.

==Example==

NML:IndustryTiles

2026-06-05T10:45:30Z

Rito12: /* Industry tile callbacks */ var 18 bit 8

{{NMLNavPropVarCB}}

This page contains information on industry tile properties, variables and callbacks. [[NML:Industries|Industries]] are closely related.

== Industry tile ID allocation ==
Industry tile IDs are local to the NewGRF, you are free to choose any ID in the 0..255-range. You should start your item definition with the 'substitute'-property, which allocates a new industry tile. The value of this property should be the ID of a [[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 tile properties==

{| class="wikitable sortable"
! 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.
{{nml|0.5}} {{ottdp|1.9|no}}Array with up to 16 [cargo_id, amount]-pairs.
| The cargos that are accepted by this tile. CargoID is a cargo type from your cargo translation table, amount is the acceptance of the given cargo in 1/8 units. Example: to make a tile accept both COAL and IORE you could use this: <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>
See also <code>INDTILE_FLAG_ACCEPT_ALL</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)
|
;INDTILE_FLAG_RANDOM_ANIMATION
: set this if the decision in anim_control callback needs random bits via extra_callback_info1
;INDTILE_FLAG_ACCEPT_ALL {{nml|0.5}} {{ottd|1.9}}
: In addition to the cargotypes set by accepted_cargos, the tile accepts all cargotypes which the industry accepts.
* This considers industry property cargo_types and callback cargo_input.
* This does not consider industry callback stop_accept_cargo.
* This property adds 8/8 acceptance for the matching cargotypes. You can list negative acceptances (-8/8) in property 13 to exclude specific cargos.
* Tile callback cargo_type_accept overrides all acceptances including those added by this flag.
|-
| badges
| Array of badge labels from the [[NML:Badgetable|badgetable]].
| Since {{ottd|15.0}}
|}

===Land shape flags===

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

{{NML:IndustryCommonVariables}}

==Industry tile variables==

{| class="wikitable sortable"
! 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="wikitable sortable"
! name
! arguments
! value range
! comment
|-
| nearby_tile_is_same_industry
| x, y
| [0 <nowiki>|</nowiki> 1]
| Parameters indicate a signed tile offset relative to the current tile. Returns 1 if the tile is part of the same industry, 0 otherwise
|-
| has_badge
| Label from the [[NML:Badgetable|badgetable]].
| [0 <nowiki>|</nowiki> 1]
| {{ottd|15.0}} Check if the industry tile has that specific badge attached.
|}

==Industry tile callbacks==

{| class="wikitable sortable"
! 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>: 32 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.
Note: Every time the animation frame is changed the map tile will be refreshed, even if the selected graphics stay the same. Therefore using the animation frame as a timer should be avoided, and animation triggers should be preferred instead.
|-
| anim_control
| Next animation frame or CB_RESULT_XXX
|
Called whenever an animation trigger happens. Return the animation frame to show, or CB_RESULT_XXX with XXX = [CB_RESULT_START_ANIMATION <nowiki>|</nowiki> STOP_ANIMATION <nowiki>|</nowiki> DO_NOTHING] to respectively start the animation in its current frame, stop the animation or do nothing. Returning a sound effect in the high byte will cause that sound effect to be played.
* <code style="color:darkgreen">extra_callback_info1</code>: 32 random bits, if enabled in the <code style="color:darkgreen">special_flags</code> property.
* <code style="color:darkgreen">getbits(extra_callback_info2, 0, 8)</code>: Reason for the callback trigger, 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.
*<code>getbits(extra_callback_info2, 8, 1)</code>: Whether triggered when placing new industries.
Note: Every time the animation frame is changed the map tile will be refreshed, even if the selected graphics stay the same. Therefore using the animation frame as a timer should be avoided, and animation triggers should be preferred instead.
|-
| anim_speed
| 0 .. 16
| Decide the time an animation frame should last. Return value is interpreted as (num_ticks = 2^anim_speed), which each tick lasting 30 ms. Avoid using this callback if possible, since it has to be called each tick for every animated tile. This can be used to create animation frames that last between 30 ms and 33 minutes.
|-
| cargo_type_accept
| type1 + (type2 << 5) + (type3 << 10)
| Decide the cargo types that this tile accepts. If this callback is not implemented or fails, the values from <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">getbits(extra_callback_info2, 0, 8)</code>: The industry layout number.
* <code style="color:darkgreen">getbits(extra_callback_info2, 8, 8)</code>: The [[#Industry creation types|creation type]]
Note: use of this callback will deactivate the use of the landshape flags. 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.
|}

{{NML:LocationCheckResults}}

===Animation triggers===

{| class="wikitable sortable"
! Trigger
! Meaning
|-
| ANIM_TRIGGER_INDTILE_CONSTRUCTION_STATE
| the construction state changes
Since {{ottd|15.0}} also triggered when placing new industries.
|-
| 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

2026-06-05T10:42:51Z

Rito12: /* House callbacks */ var18 bit 0

{{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).

{{ottdp|15}} Since OpenTTD 15 the allowed ID range is increased to 0..4095.

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.

Note, setting the 4th parameter requires to also set the 3rd parameter. If you want automatic id assignment (mind the notes on the [[NML:Item|Item page]]), you need to set the 3rd parameter to -1. Example:
<pre style="color:blue">
item(FEAT_HOUSES, item_brewery, -1, HOUSE_SIZE_2X2) {
}
</pre>

===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="wikitable sortable"
! property
! value range
! comment
|-
| 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.
|-
| name
| string
| for example string(STR_NAME_EIFFEL_TOWER)
|-
| override
| 0 ... 109
| id of the default house which this house replaces (and thus disabling the default). This is ignored, if the default house has already been overridden (disabling it another time is pointless). 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 unconditionally on (the beginning of) construction. If not set, animation can still be started (conditionally) via the callbacks <code style="color:darkgreen">anim_control</code>, <code style="color:darkgreen">construction_anim</code> or <code style="color:darkgreen">watched_cargo_accepted</code>.
;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. This also affects how many passengers the house generates, unless the <code>cargo_production</code> callback is used.
|-
| mail_multiplier
| 0 ... 255
| Affects how much mail the building generates. Not used if the <code>cargo_production</code> callback is used.
|-
| accepted_cargos
| Array with up to 3 [cargo_id, amount]-pairs.
{{nml|0.5}}{{ottdp|1.9|no}} Array with up to 16 [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.
|-
| badges
| Array of badge labels from the [[NML:Badgetable|badgetable]].
| Since {{ottd|15.0}}
|}

==House variables==

{| class="wikitable sortable"
! 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..4095
| X-coordinate (top right -> bottom left) of the tile on the map
|-
| y_coordinate
| 0..4095
| 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="wikitable sortable"
! 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_map
| 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>TYPE | 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.
|-
| has_badge
| Label from the [[NML:Badgetable|badgetable]].
| [0 <nowiki>|</nowiki> 1]
| {{ottd|15.0}} Check if the house has that specific badge attached.
|}
<references/>

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

{| class="wikitable sortable"
! 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. Returning a sound effect in the high byte will cause that sound effect to be played.
* <code>extra_callback_info1</code>: 32 random bits, if enabled in the <code>building_flags</code> property.
Note: Every time the animation frame is changed the map tile will be refreshed, even if the selected graphics stay the same. Therefore using the animation frame as a timer should be avoided, and animation triggers should be preferred instead.
|-
| anim_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. Returning a sound effect in the high byte will cause that sound effect to be played.
* <code>extra_callback_info1</code>: 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.
Note: Every time the animation frame is changed the map tile will be refreshed, even if the selected graphics stay the same. Therefore using the animation frame as a timer should be avoided, and animation triggers should be preferred instead.
|-
| 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.
Since {{ottd|15.0}} also triggered when placing new house.
*<code>getbits(extra_callback_info2, 0, 1)</code> : Whether triggered when placing new house.
|-
| 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, or <code>CB_RESULT_HOUSE_NO_MORE_PRODUCTION</code>
| Called every 256 ticks. The return value specifies what cargo and what amount is produced. The callback is called multiple times until <code>CB_RESULT_HOUSE_NO_MORE_PRODUCTION</code> is returned.
* <code>getbits(extra_callback_info1, 0, 8)</code>: The number of iterations so far.
* <code>extra_callback_info2</code>: 32 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

2026-06-05T10:38:36Z

Rito12: /* House callbacks */ ottd #14089

{{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).

{{ottdp|15}} Since OpenTTD 15 the allowed ID range is increased to 0..4095.

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.

Note, setting the 4th parameter requires to also set the 3rd parameter. If you want automatic id assignment (mind the notes on the [[NML:Item|Item page]]), you need to set the 3rd parameter to -1. Example:
<pre style="color:blue">
item(FEAT_HOUSES, item_brewery, -1, HOUSE_SIZE_2X2) {
}
</pre>

===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="wikitable sortable"
! property
! value range
! comment
|-
| 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.
|-
| name
| string
| for example string(STR_NAME_EIFFEL_TOWER)
|-
| override
| 0 ... 109
| id of the default house which this house replaces (and thus disabling the default). This is ignored, if the default house has already been overridden (disabling it another time is pointless). 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 unconditionally on (the beginning of) construction. If not set, animation can still be started (conditionally) via the callbacks <code style="color:darkgreen">anim_control</code>, <code style="color:darkgreen">construction_anim</code> or <code style="color:darkgreen">watched_cargo_accepted</code>.
;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. This also affects how many passengers the house generates, unless the <code>cargo_production</code> callback is used.
|-
| mail_multiplier
| 0 ... 255
| Affects how much mail the building generates. Not used if the <code>cargo_production</code> callback is used.
|-
| accepted_cargos
| Array with up to 3 [cargo_id, amount]-pairs.
{{nml|0.5}}{{ottdp|1.9|no}} Array with up to 16 [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.
|-
| badges
| Array of badge labels from the [[NML:Badgetable|badgetable]].
| Since {{ottd|15.0}}
|}

==House variables==

{| class="wikitable sortable"
! 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..4095
| X-coordinate (top right -> bottom left) of the tile on the map
|-
| y_coordinate
| 0..4095
| 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="wikitable sortable"
! 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_map
| 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>TYPE | 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.
|-
| has_badge
| Label from the [[NML:Badgetable|badgetable]].
| [0 <nowiki>|</nowiki> 1]
| {{ottd|15.0}} Check if the house has that specific badge attached.
|}
<references/>

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

{| class="wikitable sortable"
! 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. Returning a sound effect in the high byte will cause that sound effect to be played.
* <code>extra_callback_info1</code>: 32 random bits, if enabled in the <code>building_flags</code> property.
Note: Every time the animation frame is changed the map tile will be refreshed, even if the selected graphics stay the same. Therefore using the animation frame as a timer should be avoided, and animation triggers should be preferred instead.
|-
| anim_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. Returning a sound effect in the high byte will cause that sound effect to be played.
* <code>extra_callback_info1</code>: 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.
Note: Every time the animation frame is changed the map tile will be refreshed, even if the selected graphics stay the same. Therefore using the animation frame as a timer should be avoided, and animation triggers should be preferred instead.
|-
| 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.
Since {{ottd|15.0}} also triggered when placing new house.
|-
| 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, or <code>CB_RESULT_HOUSE_NO_MORE_PRODUCTION</code>
| Called every 256 ticks. The return value specifies what cargo and what amount is produced. The callback is called multiple times until <code>CB_RESULT_HOUSE_NO_MORE_PRODUCTION</code> is returned.
* <code>getbits(extra_callback_info1, 0, 8)</code>: The number of iterations so far.
* <code>extra_callback_info2</code>: 32 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:IndustryTiles

2026-06-05T10:33:34Z

Rito12: /* Animation triggers */ ottd #14089

{{NMLNavPropVarCB}}

This page contains information on industry tile properties, variables and callbacks. [[NML:Industries|Industries]] are closely related.

== Industry tile ID allocation ==
Industry tile IDs are local to the NewGRF, you are free to choose any ID in the 0..255-range. You should start your item definition with the 'substitute'-property, which allocates a new industry tile. The value of this property should be the ID of a [[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 tile properties==

{| class="wikitable sortable"
! 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.
{{nml|0.5}} {{ottdp|1.9|no}}Array with up to 16 [cargo_id, amount]-pairs.
| The cargos that are accepted by this tile. CargoID is a cargo type from your cargo translation table, amount is the acceptance of the given cargo in 1/8 units. Example: to make a tile accept both COAL and IORE you could use this: <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>
See also <code>INDTILE_FLAG_ACCEPT_ALL</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)
|
;INDTILE_FLAG_RANDOM_ANIMATION
: set this if the decision in anim_control callback needs random bits via extra_callback_info1
;INDTILE_FLAG_ACCEPT_ALL {{nml|0.5}} {{ottd|1.9}}
: In addition to the cargotypes set by accepted_cargos, the tile accepts all cargotypes which the industry accepts.
* This considers industry property cargo_types and callback cargo_input.
* This does not consider industry callback stop_accept_cargo.
* This property adds 8/8 acceptance for the matching cargotypes. You can list negative acceptances (-8/8) in property 13 to exclude specific cargos.
* Tile callback cargo_type_accept overrides all acceptances including those added by this flag.
|-
| badges
| Array of badge labels from the [[NML:Badgetable|badgetable]].
| Since {{ottd|15.0}}
|}

===Land shape flags===

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

{{NML:IndustryCommonVariables}}

==Industry tile variables==

{| class="wikitable sortable"
! 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="wikitable sortable"
! name
! arguments
! value range
! comment
|-
| nearby_tile_is_same_industry
| x, y
| [0 <nowiki>|</nowiki> 1]
| Parameters indicate a signed tile offset relative to the current tile. Returns 1 if the tile is part of the same industry, 0 otherwise
|-
| has_badge
| Label from the [[NML:Badgetable|badgetable]].
| [0 <nowiki>|</nowiki> 1]
| {{ottd|15.0}} Check if the industry tile has that specific badge attached.
|}

==Industry tile callbacks==

{| class="wikitable sortable"
! 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>: 32 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.
Note: Every time the animation frame is changed the map tile will be refreshed, even if the selected graphics stay the same. Therefore using the animation frame as a timer should be avoided, and animation triggers should be preferred instead.
|-
| anim_control
| Next animation frame or CB_RESULT_XXX
|
Called whenever an animation trigger happens. Return the animation frame to show, or CB_RESULT_XXX with XXX = [CB_RESULT_START_ANIMATION <nowiki>|</nowiki> STOP_ANIMATION <nowiki>|</nowiki> DO_NOTHING] to respectively start the animation in its current frame, stop the animation or do nothing. Returning a sound effect in the high byte will cause that sound effect to be played.
* <code style="color:darkgreen">extra_callback_info1</code>: 32 random bits, if enabled in the <code style="color:darkgreen">special_flags</code> property.
* <code style="color:darkgreen">getbits(extra_callback_info2, 0, 8)</code>: Reason for the callback trigger, 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.
Note: Every time the animation frame is changed the map tile will be refreshed, even if the selected graphics stay the same. Therefore using the animation frame as a timer should be avoided, and animation triggers should be preferred instead.
|-
| anim_speed
| 0 .. 16
| Decide the time an animation frame should last. Return value is interpreted as (num_ticks = 2^anim_speed), which each tick lasting 30 ms. Avoid using this callback if possible, since it has to be called each tick for every animated tile. This can be used to create animation frames that last between 30 ms and 33 minutes.
|-
| cargo_type_accept
| type1 + (type2 << 5) + (type3 << 10)
| Decide the cargo types that this tile accepts. If this callback is not implemented or fails, the values from <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">getbits(extra_callback_info2, 0, 8)</code>: The industry layout number.
* <code style="color:darkgreen">getbits(extra_callback_info2, 8, 8)</code>: The [[#Industry creation types|creation type]]
Note: use of this callback will deactivate the use of the landshape flags. 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.
|}

{{NML:LocationCheckResults}}

===Animation triggers===

{| class="wikitable sortable"
! Trigger
! Meaning
|-
| ANIM_TRIGGER_INDTILE_CONSTRUCTION_STATE
| the construction state changes
Since {{ottd|15.0}} also triggered when placing new industries.
|-
| 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:Roadstops

2026-06-05T10:11:37Z

Rito12: /* Road stop properties */ nml #388

{{NMLNavPropVarCB}}

Road stops can only be defined in OpenTTD {{ottd|14.0}} or later.

==Road stop IDs==
OpenTTD supports 64000 road stop types per game.

Rpad stop IDs are NewGRF-local and can therefore freely be chosen within the ID ranges.

A road stop is allocated by setting the 'class'-property, which should therefore be set first.

Road stop sprite layouts should always set a suitable ground tile sprite, and should not assume that a road type GRF will provide suitable overlay sprites.
Suggested ground sprite IDs include: GROUNDSPRITE_ROAD_X/GROUNDSPRITE_ROAD_Y (straight road on grass), 1314/1313 (straight road with pavement), 2692 - 2695 (bay road stop ground).

==Road stop properties==

{| class="wikitable sortable"
! property
! value range
! comment
|-
| class
| String literal of length 4
|
'''This property ''must'' be set first, before any other properties or graphics.''' 
Road stops belonging to the same class are grouped in the GUI. 
There is one special class:
* "WAYP": {{ottdp|15.0|no}} The road stop type will be shown in the waypoint construction window, instead of the station construction window.
{{ottdp|15}} Station classes which start with the byte FF are considered waypoint classes, and will appear in the waypoint construction window instead of the station construction window.
|-
| classname
| string
| You only need to set this for one road stop in every class.
|-
| name
| string
|
|-
| availability_type
| RST_AVAILABILITY_TYPE_XXX
| XXX = [PASSENGER <nowiki>|</nowiki> FREIGHT <nowiki>|</nowiki> ALL]
The default value is RST_AVAILABILITY_TYPE_ALL
|-
| draw_mode
| bitmask(RST_DRAW_FLAG_XXX, ...)
| See [[#List of draw mode flags|list of draw mode flags]]
The default value is bitmask(RST_DRAW_FLAG_BAY_ROAD, RST_DRAW_FLAG_DRIVE_THROUGH_ROAD_OVERLAY)
|-
| cargo_random_triggers
| Array of cargo labels from the [[NML:Cargotable|cargotable]]
| Cargo types, which will [[NML:Random_switch#Stations|trigger re-randomization]] when delivered, loaded or unloaded at the station.
|-
| 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
|
|
See [[#Animation_triggers|list of animation triggers]]
|-
| general_flags
| bitmask(RST_GENERAL_FLAG_XXX, ...)
| See [[#List of general flags|list of general flags]]
|-
| cost_multipliers
| [build_cost, clear_cost]
| Build and clear cost multipliers, 16 is the same as a non-NewGRF road stop
|-
| badges
| Array of badge labels from the [[NML:Badgetable|badgetable]].
| Since {{ottd|15.0}}
|-
| heights
| Array of unsigned ints
| Since {{ottd|15.0}} {{nml|0.8.1}} 
Each element of array corresponds to one [[#List of road stop views|view]]. 
Specifies the bridge height so bridges can be build above the road stop.
The bridge height defines minimum clearances required for a bridge for the sprite layouts of this road stop (or zero to not allow any bridge).
Values are given in "height level" units (1 level == 8px).
|-
| blocked_pillars
| Array of <code>bitmask(BRIDGE_PILLAR_XXX, ...)</code>
| Since {{ottd|15.0}} {{nml|0.8.1}} 
Each element of array corresponds to one [[#List of road stop views|view]]. 
Allows information to provided about blocked bridge pillars to assist the game in hiding pillars if necessary depending on what is above the road stop tile. Blocking a pillar prevents the pillar from being drawn. It does not prevent the road stop being bridgeable.
See [[#List_of_bridge_pillar_flags|list of bridge pillar flags]].
|}

===List of draw mode flags===

{| class="wikitable sortable"
! Name
! Meaning
|-
| RST_DRAW_FLAG_BAY_ROAD
| Draw road type ground sprite for bay stops.
|-
| RST_DRAW_FLAG_DRIVE_THROUGH_ROAD_OVERLAY
| Draw road overlays for drive-through stops.
|-
| RST_DRAW_FLAG_WAYPOINT_GROUND
| {{ottdp|15.0|no}} Draw spritelayout ground sprite on top of underlying road (if unset, the spritelayout ground sprite is not drawn).
|}

===List of general flags===

{| class="wikitable sortable"
! Name
! Meaning
|-
| RST_GENERAL_FLAG_RANDOM_ANIMATION
| Animation callback requires random bits in variable extra_callback_info1.
|-
| RST_GENERAL_FLAG_NO_CATENARY
| Do not show catenary graphics.
|-
| RST_GENERAL_FLAG_DRIVE_THROUGH_ONLY
| Only allow drive-through stops (not bay stops).
|-
| RST_GENERAL_FLAG_NO_AUTO_ROAD_CONNECTION
| Do not automatically build connecting road pieces.
|-
| RST_GENERAL_FLAG_BUILD_MENU_ROAD_ONLY
| Only show in the road build menu (not tram).
|-
| RST_GENERAL_FLAG_BUILD_MENU_TRAM_ONLY
| Only show in the tram build menu (not road).
|-
| RST_GENERAL_FLAG_DRAW_MODE_REGISTER
| {{ottdp|15.0|no}} Read the road stop draw mode from variable 0x100 (set using STORE_TEMP), this overrides the draw_mode property.
|}

===List of bridge pillar flags===

{| class="wikitable sortable"
! Name
! Meaning
|-
| BRIDGE_PILLAR_CORNER_W
| Tile layout blocks a pillar on the west corner of the tile.
|-
| BRIDGE_PILLAR_CORNER_S
| Tile layout blocks a pillar on the south corner of the tile.
|-
| BRIDGE_PILLAR_CORNER_E
| Tile layout blocks a pillar on the east corner of the tile.
|-
| BRIDGE_PILLAR_CORNER_N
| Tile layout blocks a pillar on the north corner of the tile.
|-
| BRIDGE_PILLAR_EDGE_NE
| Tile layout blocks a wall on the north east side of the tile.
|-
| BRIDGE_PILLAR_EDGE_SE
| Tile layout blocks a wall on the south east side of the tile.
|-
| BRIDGE_PILLAR_EDGE_SW
| Tile layout blocks a wall on the south west side of the tile.
|-
| BRIDGE_PILLAR_EDGE_NW
| Tile layout blocks a wall on the north west side of the tile.
|}

==Road stop variables==

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

{| class="wikitable sortable"
! name
! value range
! comment
|-
| random_bits_station
| 0..65535
| 16 random bits, shared between all station sections (rail station sections, airports, ...)
|-
| 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:Stations|stations]] and [[NML:Airports|airports]]. They all require a single argument: a cargo type from your [[NML:Cargotable|cargo translation table]].

{| class="wikitable sortable"
! 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="wikitable sortable"
! name
! value range
! comment
|-
| view
| RST_VIEW_XXX
| The view/rotation of the road stop. See [[#List of road stop views|list of road stop views]]
|-
| stop_type
| RST_TYPE_XXX
| XXX = [BUS <nowiki>|</nowiki> TRUCK <nowiki>|</nowiki> {{ottdp|15}}WAYPOINT]
|-
| 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
|-
| has_road
| [0 <nowiki>|</nowiki> 1]
| 1 if this road stop has road
|-
| has_tram
| [0 <nowiki>|</nowiki> 1]
| 1 if this road stop has tram
|-
| road_type
| [Road type <nowiki>|</nowiki> 0xFF]
| Entry from [[NML:Railtypetable|roadtype translation table]], or 0xFF if there is no road
|-
| tram_type
| [Tram type <nowiki>|</nowiki> 0xFF]
| Entry from [[NML:Railtypetable|tramtype translation table]], or 0xFF if there is no tram
|-
| animation_frame
| 0 .. (frame_count - 1)
| Current animation frame, with the maximum defined in the <code style="color:darkgreen">animation_info</code> property.
|-
| 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.
|-
| 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.
|-
| random_bits_tile
| 0..255
| 8 random bits, specific to this road stop tile.
|-
| waiting_triggers
| 0..255
| Random triggers waiting to be matched. (see [[NML:Random switch|Random switch]])
|-
| drawn_in_gui
| [0 <nowiki>|</nowiki> 1]
| {{ottdp|15}} 1 if this road stop is being drawn in the build window
|}

===Variables that require one or more parameters===

{| class="wikitable sortable"
! name
! arguments
! value range
! comment
|-
| nearby_tile_slope
| x, y offset (-8..7)
|
| See tile_slope
|-
| 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. Only valid for tiles of the same object.
|-
| nearby_tile_is_road_stop
| x, y offset (-8..7)
| 0 .. 1
| Is the given tile a road stop?
|-
| nearby_tile_road_stop_id
| x, y offset (-8..7)
|
| Is nearby_tile_same_grf is true, ID of a road stop on a nearby tile
|-
| nearby_tile_same_grf
| x, y offset (-8..7)
| 0 .. 1
| Is a road stop on a nearby tile defined by the same GRF?
|-
| nearby_tile_other_grf
| x, y offset (-8..7)
| 0 .. 1
| Is a road stop on a nearby tile defined by another GRF?
|-
| nearby_tile_original_gfx
| x, y offset (-8..7)
| 0 .. 1
| Is a road stop on a nearby tile using original graphics?
|-
| nearby_tile_same_station
| x, y offset (-8..7)
| 0 .. 1
| Is a road stop on a nearby tile the same station as this?
|-
| nearby_tile_view
| x, y offset (-8..7)
| RST_VIEW_XXX
| The view/rotation of a nearby road stop tile. See [[#List of road stop views|list of road stop views]]
|-
| nearby_tile_different_view
| x, y offset (-8..7)
| 0 .. 1
| Is the view/rotation of a road stop on a nearby tile different to that of this tile?
|-
| nearby_tile_is_drive_through
| x, y offset (-8..7)
| 0 .. 1
| Is nearby road stop tile a drive-through road stop?
|-
| nearby_tile_stop_type
| x, y offset (-8..7)
| RST_TYPE_XXX
| Road stop type of a nearby tile. See stop_type
|-
| nearby_tile_same_stop_type
| x, y offset (-8..7)
| 0 .. 1
| Is the stop type of a nearby road stop tile the same as this tile?
|-
| nearby_tile_grfid
| x, y offset (-8..7)
| [0xFFFFFFFF <nowiki>|</nowiki> 0 <nowiki>|</nowiki> GRFID]
| 0xFFFFFFFF if the nearby tile is not a road stop, 0 if the nearby tile is a non-custom road stop, or else the GRFID of the NewGRF defining the road stop on the nearby tile
|-
| has_badge
| Label from the [[NML:Badgetable|badgetable]].
| [0 <nowiki>|</nowiki> 1]
| {{ottd|15.0}} Check if the road stop has that specific badge attached.
|}

===List of road stop views===

{| class="wikitable sortable"
! Name
! Type
! Meaning
! Value
|-
| RST_VIEW_BAY_NE
| Bay
| Facing north-east
| 0
|-
| RST_VIEW_BAY_SE
| Bay
| Facing south-east
| 1
|-
| RST_VIEW_BAY_SW
| Bay
| Facing south-west
| 2
|-
| RST_VIEW_BAY_NW
| Bay
| Facing north-west
| 3
|-
| RST_VIEW_DRIVE_THROUGH_X
| Drive-through
| X-axis: north-east to south-west
| 4
|-
| RST_VIEW_DRIVE_THROUGH_Y
| Drive-through
| Y-axis: north-west to south-east
| 5
|}

==Road stop callbacks==

{| class="wikitable sortable"
! callback
! return value
! comment
|-
| default
| Sprite layout
| Normal graphics for a road stop placed on the map
|-
| purchase <ref name="notyetbuilt">These callbacks are called when the road stop is not yet built</ref>
| Sprite layout
| Graphics shown in the build menu
|-
| availability
| 0 <nowiki>|</nowiki> 1
| Whether this road stop type is available in the build menu, 1 is available, 0 is unavailable
|-
| 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. 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>).
* <code style="color:darkgreen">extra_callback_info1</code>: 32 random bits, if the object flag OBJ_FLAG_RANDOM_ANIMATION is set.
|-
| 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. Returning a sound effect in the high byte will cause that sound effect to be played.
* <code style="color:darkgreen">extra_callback_info1</code>: 32 random bits, if the object flag OBJ_FLAG_RANDOM_ANIMATION is set.
* <code style="color:darkgreen">getbits(extra_callback_info2, 0, 8)</code>: Reason for the callback trigger, see the [[#Animation triggers| table]] below.
|-
| 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.
|}

===Animation triggers===

{| class="wikitable sortable"
! Animation trigger
! Description
! Happens on
! extra_callback_info2
|-
| ANIM_TRIGGER_ROAD_STOP_BUILT
| Road stop is built
| Newly built tile
|
|-
| ANIM_TRIGGER_ROAD_STOP_NEW_CARGO
| New cargo arrives at station
| All tiles
| Bits 8..15 contain the triggering cargo type
|-
| ANIM_TRIGGER_ROAD_STOP_CARGO_TAKEN
| CRGO removed from station
| All tiles
| Bits 8..15 contain the triggering cargo type
|-
| ANIM_TRIGGER_ROAD_STOP_VEH_ENTER
| Road vehicle enters stop (starts loading/unloading)
| Tile where the vehicle is
|
|-
| ANIM_TRIGGER_ROAD_STOP_VEH_LEAVE
| Road vehicle leaves stop (done loading/unloading)
| Tile where the vehicle is
|
|-
| ANIM_TRIGGER_ROAD_STOP_VEH_LOAD
| Road vehicle loads/unloads cargo
| Tile where the vehicle is
|
|-
| ANIM_TRIGGER_ROAD_STOP_250_TICKS
| Every 250 ticks
| All tiles
|
|-
| {{ottd|15.0}} ANIM_TRIGGER_ROAD_STOP_TILELOOP
| Tile is processed in the periodic processing loop
|
|
|}

NML:Roadstops

2026-06-05T09:58:30Z

Rito12: /* List of road stop views */ Add value to the table.

{{NMLNavPropVarCB}}

Road stops can only be defined in OpenTTD {{ottd|14.0}} or later.

==Road stop IDs==
OpenTTD supports 64000 road stop types per game.

Rpad stop IDs are NewGRF-local and can therefore freely be chosen within the ID ranges.

A road stop is allocated by setting the 'class'-property, which should therefore be set first.

Road stop sprite layouts should always set a suitable ground tile sprite, and should not assume that a road type GRF will provide suitable overlay sprites.
Suggested ground sprite IDs include: GROUNDSPRITE_ROAD_X/GROUNDSPRITE_ROAD_Y (straight road on grass), 1314/1313 (straight road with pavement), 2692 - 2695 (bay road stop ground).

==Road stop properties==

{| class="wikitable sortable"
! property
! value range
! comment
|-
| class
| String literal of length 4
|
'''This property ''must'' be set first, before any other properties or graphics.''' 
Road stops belonging to the same class are grouped in the GUI. 
There is one special class:
* "WAYP": {{ottdp|15.0|no}} The road stop type will be shown in the waypoint construction window, instead of the station construction window.
{{ottdp|15}} Station classes which start with the byte FF are considered waypoint classes, and will appear in the waypoint construction window instead of the station construction window.
|-
| classname
| string
| You only need to set this for one road stop in every class.
|-
| name
| string
|
|-
| availability_type
| RST_AVAILABILITY_TYPE_XXX
| XXX = [PASSENGER <nowiki>|</nowiki> FREIGHT <nowiki>|</nowiki> ALL]
The default value is RST_AVAILABILITY_TYPE_ALL
|-
| draw_mode
| bitmask(RST_DRAW_FLAG_XXX, ...)
| See [[#List of draw mode flags|list of draw mode flags]]
The default value is bitmask(RST_DRAW_FLAG_BAY_ROAD, RST_DRAW_FLAG_DRIVE_THROUGH_ROAD_OVERLAY)
|-
| cargo_random_triggers
| Array of cargo labels from the [[NML:Cargotable|cargotable]]
| Cargo types, which will [[NML:Random_switch#Stations|trigger re-randomization]] when delivered, loaded or unloaded at the station.
|-
| 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
|
|
See [[#Animation_triggers|list of animation triggers]]
|-
| general_flags
| bitmask(RST_GENERAL_FLAG_XXX, ...)
| See [[#List of general flags|list of general flags]]
|-
| cost_multipliers
| [build_cost, clear_cost]
| Build and clear cost multipliers, 16 is the same as a non-NewGRF road stop
|-
| badges
| Array of badge labels from the [[NML:Badgetable|badgetable]].
| Since {{ottd|15.0}}
|}

===List of draw mode flags===

{| class="wikitable sortable"
! Name
! Meaning
|-
| RST_DRAW_FLAG_BAY_ROAD
| Draw road type ground sprite for bay stops.
|-
| RST_DRAW_FLAG_DRIVE_THROUGH_ROAD_OVERLAY
| Draw road overlays for drive-through stops.
|-
| RST_DRAW_FLAG_WAYPOINT_GROUND
| {{ottdp|15.0|no}} Draw spritelayout ground sprite on top of underlying road (if unset, the spritelayout ground sprite is not drawn).
|}

===List of general flags===

{| class="wikitable sortable"
! Name
! Meaning
|-
| RST_GENERAL_FLAG_RANDOM_ANIMATION
| Animation callback requires random bits in variable extra_callback_info1.
|-
| RST_GENERAL_FLAG_NO_CATENARY
| Do not show catenary graphics.
|-
| RST_GENERAL_FLAG_DRIVE_THROUGH_ONLY
| Only allow drive-through stops (not bay stops).
|-
| RST_GENERAL_FLAG_NO_AUTO_ROAD_CONNECTION
| Do not automatically build connecting road pieces.
|-
| RST_GENERAL_FLAG_BUILD_MENU_ROAD_ONLY
| Only show in the road build menu (not tram).
|-
| RST_GENERAL_FLAG_BUILD_MENU_TRAM_ONLY
| Only show in the tram build menu (not road).
|-
| RST_GENERAL_FLAG_DRAW_MODE_REGISTER
| {{ottdp|15.0|no}} Read the road stop draw mode from variable 0x100 (set using STORE_TEMP), this overrides the draw_mode property.
|}

==Road stop variables==

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

{| class="wikitable sortable"
! name
! value range
! comment
|-
| random_bits_station
| 0..65535
| 16 random bits, shared between all station sections (rail station sections, airports, ...)
|-
| 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:Stations|stations]] and [[NML:Airports|airports]]. They all require a single argument: a cargo type from your [[NML:Cargotable|cargo translation table]].

{| class="wikitable sortable"
! 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="wikitable sortable"
! name
! value range
! comment
|-
| view
| RST_VIEW_XXX
| The view/rotation of the road stop. See [[#List of road stop views|list of road stop views]]
|-
| stop_type
| RST_TYPE_XXX
| XXX = [BUS <nowiki>|</nowiki> TRUCK <nowiki>|</nowiki> {{ottdp|15}}WAYPOINT]
|-
| 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
|-
| has_road
| [0 <nowiki>|</nowiki> 1]
| 1 if this road stop has road
|-
| has_tram
| [0 <nowiki>|</nowiki> 1]
| 1 if this road stop has tram
|-
| road_type
| [Road type <nowiki>|</nowiki> 0xFF]
| Entry from [[NML:Railtypetable|roadtype translation table]], or 0xFF if there is no road
|-
| tram_type
| [Tram type <nowiki>|</nowiki> 0xFF]
| Entry from [[NML:Railtypetable|tramtype translation table]], or 0xFF if there is no tram
|-
| animation_frame
| 0 .. (frame_count - 1)
| Current animation frame, with the maximum defined in the <code style="color:darkgreen">animation_info</code> property.
|-
| 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.
|-
| 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.
|-
| random_bits_tile
| 0..255
| 8 random bits, specific to this road stop tile.
|-
| waiting_triggers
| 0..255
| Random triggers waiting to be matched. (see [[NML:Random switch|Random switch]])
|-
| drawn_in_gui
| [0 <nowiki>|</nowiki> 1]
| {{ottdp|15}} 1 if this road stop is being drawn in the build window
|}

===Variables that require one or more parameters===

{| class="wikitable sortable"
! name
! arguments
! value range
! comment
|-
| nearby_tile_slope
| x, y offset (-8..7)
|
| See tile_slope
|-
| 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. Only valid for tiles of the same object.
|-
| nearby_tile_is_road_stop
| x, y offset (-8..7)
| 0 .. 1
| Is the given tile a road stop?
|-
| nearby_tile_road_stop_id
| x, y offset (-8..7)
|
| Is nearby_tile_same_grf is true, ID of a road stop on a nearby tile
|-
| nearby_tile_same_grf
| x, y offset (-8..7)
| 0 .. 1
| Is a road stop on a nearby tile defined by the same GRF?
|-
| nearby_tile_other_grf
| x, y offset (-8..7)
| 0 .. 1
| Is a road stop on a nearby tile defined by another GRF?
|-
| nearby_tile_original_gfx
| x, y offset (-8..7)
| 0 .. 1
| Is a road stop on a nearby tile using original graphics?
|-
| nearby_tile_same_station
| x, y offset (-8..7)
| 0 .. 1
| Is a road stop on a nearby tile the same station as this?
|-
| nearby_tile_view
| x, y offset (-8..7)
| RST_VIEW_XXX
| The view/rotation of a nearby road stop tile. See [[#List of road stop views|list of road stop views]]
|-
| nearby_tile_different_view
| x, y offset (-8..7)
| 0 .. 1
| Is the view/rotation of a road stop on a nearby tile different to that of this tile?
|-
| nearby_tile_is_drive_through
| x, y offset (-8..7)
| 0 .. 1
| Is nearby road stop tile a drive-through road stop?
|-
| nearby_tile_stop_type
| x, y offset (-8..7)
| RST_TYPE_XXX
| Road stop type of a nearby tile. See stop_type
|-
| nearby_tile_same_stop_type
| x, y offset (-8..7)
| 0 .. 1
| Is the stop type of a nearby road stop tile the same as this tile?
|-
| nearby_tile_grfid
| x, y offset (-8..7)
| [0xFFFFFFFF <nowiki>|</nowiki> 0 <nowiki>|</nowiki> GRFID]
| 0xFFFFFFFF if the nearby tile is not a road stop, 0 if the nearby tile is a non-custom road stop, or else the GRFID of the NewGRF defining the road stop on the nearby tile
|-
| has_badge
| Label from the [[NML:Badgetable|badgetable]].
| [0 <nowiki>|</nowiki> 1]
| {{ottd|15.0}} Check if the road stop has that specific badge attached.
|}

===List of road stop views===

{| class="wikitable sortable"
! Name
! Type
! Meaning
! Value
|-
| RST_VIEW_BAY_NE
| Bay
| Facing north-east
| 0
|-
| RST_VIEW_BAY_SE
| Bay
| Facing south-east
| 1
|-
| RST_VIEW_BAY_SW
| Bay
| Facing south-west
| 2
|-
| RST_VIEW_BAY_NW
| Bay
| Facing north-west
| 3
|-
| RST_VIEW_DRIVE_THROUGH_X
| Drive-through
| X-axis: north-east to south-west
| 4
|-
| RST_VIEW_DRIVE_THROUGH_Y
| Drive-through
| Y-axis: north-west to south-east
| 5
|}

==Road stop callbacks==

{| class="wikitable sortable"
! callback
! return value
! comment
|-
| default
| Sprite layout
| Normal graphics for a road stop placed on the map
|-
| purchase <ref name="notyetbuilt">These callbacks are called when the road stop is not yet built</ref>
| Sprite layout
| Graphics shown in the build menu
|-
| availability
| 0 <nowiki>|</nowiki> 1
| Whether this road stop type is available in the build menu, 1 is available, 0 is unavailable
|-
| 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. 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>).
* <code style="color:darkgreen">extra_callback_info1</code>: 32 random bits, if the object flag OBJ_FLAG_RANDOM_ANIMATION is set.
|-
| 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. Returning a sound effect in the high byte will cause that sound effect to be played.
* <code style="color:darkgreen">extra_callback_info1</code>: 32 random bits, if the object flag OBJ_FLAG_RANDOM_ANIMATION is set.
* <code style="color:darkgreen">getbits(extra_callback_info2, 0, 8)</code>: Reason for the callback trigger, see the [[#Animation triggers| table]] below.
|-
| 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.
|}

===Animation triggers===

{| class="wikitable sortable"
! Animation trigger
! Description
! Happens on
! extra_callback_info2
|-
| ANIM_TRIGGER_ROAD_STOP_BUILT
| Road stop is built
| Newly built tile
|
|-
| ANIM_TRIGGER_ROAD_STOP_NEW_CARGO
| New cargo arrives at station
| All tiles
| Bits 8..15 contain the triggering cargo type
|-
| ANIM_TRIGGER_ROAD_STOP_CARGO_TAKEN
| CRGO removed from station
| All tiles
| Bits 8..15 contain the triggering cargo type
|-
| ANIM_TRIGGER_ROAD_STOP_VEH_ENTER
| Road vehicle enters stop (starts loading/unloading)
| Tile where the vehicle is
|
|-
| ANIM_TRIGGER_ROAD_STOP_VEH_LEAVE
| Road vehicle leaves stop (done loading/unloading)
| Tile where the vehicle is
|
|-
| ANIM_TRIGGER_ROAD_STOP_VEH_LOAD
| Road vehicle loads/unloads cargo
| Tile where the vehicle is
|
|-
| ANIM_TRIGGER_ROAD_STOP_250_TICKS
| Every 250 ticks
| All tiles
|
|-
| {{ottd|15.0}} ANIM_TRIGGER_ROAD_STOP_TILELOOP
| Tile is processed in the periodic processing loop
|
|
|}

NML:Stations

2026-06-05T09:27:45Z

Rito12: /* Station properties */ add #388

{{NMLNavPropVarCB}}
Stations are supported since {{nml|0.7}}.

==Station sections==

Stations can be built from multiple sections. Station tiles will remember, which tiles were built together in one action.
* Building a 2x5 station in one action creates a single station section of size 2x5.
* Building a 2x5 station by placing two 1x5 areas next to each other in two actions creates two station sections of size 1x5; even when using the same station type from the same NewGRF.

[[File:station_sections.png|800px]]

Overbuilding stations and removing station tiles will remove tiles from station sections.
* On construction all station sections are contiguous rectangular NxM tile ares. (regular station section)
* When tiles are overbuilt or tiles are removed, station sections may end up non-rectangular and non-contiguous. (irregular station section)
Station tiles can query their position inside a contiguous line of tiles from the same section.
* This is great as long as the section remains regular.
* If tiles are non-contiguous, they are indistinguishable from tiles of other sections.

For irregular sections the "position" inside the section will become rather arbitrary.
The picture shows the perspective of each tile of a irregular section as "(platform, position)/(num-platforms, length)":

[[File:station_sections_irregular.png|800px]]

==Tile types==

When station sections are built, they can store a "tile type" for each tile using the <code style="color:darkgreen">select_tile_type</code> callback.

Tile types have multiple usages:
* The type can be read via the <code style="color:darkgreen">tile_type</code> variable, and can act as persistent storage.
* It decides whether the tile is traversible by trains, or whether it is a building without tracks.
* It decides whether catenary pylons and/or wires shall be drawn/hidden on the tile. Note: even non-track station buildings have a rail type, and can draw catenary.

The tile type is immutable after construction. So, unlike the platform/position information, the tile type will never change after construction, even if tiles of the station section are removed or overbuilt.

The number of tile types is quite limited: 4 per orientation, 8 in total.
'''Note:''' Since {{ottd|15.0}} {{nml|0.7.6}} it is possible to register up to 256 tile types.
* Tile types 0, 2, 4 and 6 are used for station sections with tracks in X direction (⤢).
* Tile types 1, 3, 5 and 7 are used for station sections with tracks in Y direciton (⤡).
* Callback <code style="color:darkgreen">select_tile_type</code> decides between the pairs (0,1), (2,3), (4,5), (6,7) during construction. The orientation is always picked by the player.

==Station properties==

{| class="wikitable sortable"
! property
! value range
! comment
|-
| class
| String literal of length 4
|
'''This property ''must'' be set first, before any other properties or graphics.''' 
Stations belonging to the same class are grouped in the GUI. 
There is one special class:
* "WAYP": The station type will be shown in the waypoint construction window, instead of the station construction window.
{{ottdp|15.0}} Station classes which start with the byte FF are considered waypoint classes, and will appear in the waypoint construction window instead of the station construction window.
|-
| classname
| string
| You only need to set this for one station in every class.
|-
| name
| string
| For example: string(STR_50S_STATION)
|-
| disabled_platforms disabled_length
| bitmask(1, 2, 3, 4, 5, 6, 7, 8)
|
Restricts the possible number-of-platforms and platform-lengths the player can build as one section.
* Sizes 1 to 7 can be disabled individually,
* "size 8" is used for anything bigger than 7.
To put restrictions on sizes bigger than 7 (for example, only allow even sizes), you can use callback <code style="color:darkgreen">tile_check</code>.
 Note: Players can remove single tiles from any station, so stations sections can end up with forbidden sizes anyway.
|-
| cargo_threshold
| 0..4095
| Threshold between <code style="color:darkgreen">little</code> and <code style="color:darkgreen">lots</code> spritesets, see [[NML:Spritegroup#Stations|spritegroup]] for details.
|-
| draw_pylon_tiles hide_wire_tiles non_traversable_tiles 
| bitmask(0, 1, 2, 3, 4, 5, 6, 7)
| '''Deprecated since '''{{nml|0.7.6}}''' , replaced by '''<code style="color:darkgreen">tile_flags</code>'''.''' 
Specifies which [[#Tile_types|tile types]] are traversible/non-traversible, and whether pylons and/or catenary shall be drawn for electrified rail types.
Note: it is common that all tile types behave the same, you may want to use the short cuts
* <code style="color:darkgreen">0</code> for no tile types, and
* <code style="color:darkgreen">STAT_ALL_TILES</code> for all tile types.
|-
| cargo_random_triggers
| Array of cargo labels from the [[NML:Cargotable|cargotable]]
| Cargo types, which will [[NML:Random_switch#Stations|trigger re-randomization]] when delivered, loaded or unloaded at the station.
|-
| general_flags
| bitmask(STAT_FLAG_XXX, STAT_FLAG_YYY, ...)
|
;STAT_FLAG_DISTRIBUTED_CARGO_BY_PERIMETER {{nml|0.9.0}}
:Specifies whether waiting cargo amounts are scaled by station '''perimeter''' for spriteset selection, see [[NML:Spritegroup#Stations|spritegroup]] for details.
:Since {{ottd|16.0}} if <code style="color:darkgreen">STAT_FLAG_DISTRIBUTED_CARGO_BY_AREA</code> is also set it does not do anything.
;STAT_FLAG_DISTRIBUTED_CARGO_BY_AREA {{ottd|16.0}} {{nml|0.9.0}}
:Specifies whether waiting cargo amounts are scaled by station '''area''' for spriteset selection, see [[NML:Spritegroup#Stations|spritegroup]] for details.
;STAT_FLAG_RANDOM_ANIMATION
:If set, callback <code style="color:darkgreen">anim_next_frame</code> will get random data in <code style="color:darkgreen">extra_callback_info1</code>
;STAT_FLAG_CUSTOM_FOUNDATIONS
:Enables callback <code style="color:darkgreen">foundations</code>, see below.
;STAT_FLAG_EXTENDED_FOUNDATIONS
:Selects between two possible spriteset formats for callback <code style="color:darkgreen">foundations</code>, see below.
;STAT_FLAG_DISTRIBUTED_CARGO
:Deprecated since {{nml|0.9.0}}.
|-
| 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(STAT_ANIM_XXX, ANIM_TRIGGER_STAT_YYY, ...)
| Enables callback <code style="color:darkgreen">anim_control</code> for specified triggers:
;STAT_ANIM_IS_BUILT
:Tile is built. (all new-built/overbuilt tiles)
;STAT_ANIM_CARGO_ARRIVES
:Cargo is deliverd from industry to station. (all station tiles)
;STAT_ANIM_CARGO_REMOVED
:All cargo was loaded onto a vehicle, no more cargo (of this type) is waiting. (all station tiles)
;STAT_ANIM_TRAIN_ENTERS
:Train stops at station. (all tiles of platform)
;STAT_ANIM_TRAIN_LEAVES
:Train leaves station. (all tiles of platform)
;STAT_ANIM_TRAIN_LOAD_UNLOAD
:Train is loading or unloading. (all tiles of platform)
;STAT_ANIM_250_TICKS
:Every 250 ticks. (synchronized for all tiles of the station)
;{{ottd|15.0}} ANIM_TRIGGER_STAT_TILELOOP
:Tile is processed in the periodic processing loop
;{{ottd|15.0}} ANIM_TRIGGER_STAT_TRAIN_RESERVES
:Train reserves platform (using PBS)
|-
| badges
| Array of badge labels from the [[NML:Badgetable|badgetable]].
| Since {{ottd|15.0}}
|-
| tile_flags
| Array of <code>bitmask(STAT_TILE_XXX, ...)</code>
| Since {{ottd|15.0}} {{nml|0.7.6}} 
Each element of array corresponds to one tile type. Array should always have even number of elements. 
'''XXX''' should be replaced by one of the following:
; PYLON
: Draw pylon on tile with that type.
; NOWIRE
: Hide wire on tile with that type.
; BLOCKED
: Do not allow trains to enter tile with that type.
|-
| heights
| Array of unsigned ints
| Since {{ottd|15.0}} {{nml|0.8.1}} 
Each element of array corresponds to one tile type. Array should always have even number of elements. 
Specifies the bridge height so bridges can be build above the station.
The bridge height defines minimum clearances required for a bridge for the sprite layouts of this station (or zero to not allow any bridge).
Values are given in "height level" units (1 level == 8px).
|-
| blocked_pillars
| Array of <code>bitmask(BRIDGE_PILLAR_XXX, ...)</code>
| Since {{ottd|15.0}} {{nml|0.8.1}} 
Each element of array corresponds to one tile type. Array should always have even number of elements. 
Allows information to provided about blocked bridge pillars to assist the game in hiding pillars if necessary depending on what is above the station tile. Blocking a pillar prevents the pillar from being drawn. It does not prevent the station being bridgeable.
 '''XXX''' should be replaced by one of the following:
;CORNER_W : Tile layout blocks a pillar on the west corner of the tile.
;CORNER_S : Tile layout blocks a pillar on the south corner of the tile.
;CORNER_E : Tile layout blocks a pillar on the east corner of the tile.
;CORNER_N : Tile layout blocks a pillar on the north corner of the tile.
;EDGE_NE : Tile layout blocks a wall on the north east side of the tile.
;EDGE_SE : Tile layout blocks a wall on the south east side of the tile.
;EDGE_SW : Tile layout blocks a wall on the south west side of the tile.
;EDGE_NW : Tile layout blocks a wall on the north west side of the tile.
|}

==Station variables==

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

{| class="wikitable sortable"
! name
! value range
! comment
|-
| random_bits_station
| 0..65535
| 16 random bits, shared between all station sections (rail station sections, airports, ...)
|-
| 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="wikitable sortable"
! 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="wikitable sortable"
! name
! value range
! comment
|-
| tile_type
| 0..7
; 0..255 {{ottd|15.0}}
| The type of tile, as decided by <code style="color:darkgreen">select_tile_type</code>. Bit 0 also tells the orientation.
|-
| 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.
|-
| random_bits_tile
| 0..15
| 4 random bits, specific to this station 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="wikitable sortable"
! 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_grfid
| tile- and platform-offset <ref name="offset"/>
| 32-bit GRFID
| GRFID of the NewGRF defining the given station tile.
|-
| 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_tile_type
| tile- and platform-offset <ref name="offset"/>
| 0..7
; 0..255 {{ottd|15.0}}
| [[#Tile_types|Tile type]] of the given tile. The orientation bit is adjusted to be relative to the current tile's orientation:
* 0, 2, 4, 6: Tracks are parallel.
* 1, 3, 5, 7: Tracks are perpendicular.
|-
| 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 [[#Station_sections|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.
|-
| has_badge
| Label from the [[NML:Badgetable|badgetable]].
| [0 <nowiki>|</nowiki> 1]
| {{ottd|15.0}} Check if the rail station has that specific badge attached.
|}
<references/>

==Station callbacks==

The following table contains a list of available station 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 cargo is waiting at the station. If multiple cargo types are waiting at the station, OpenTTD will pick one of the options the station provides.
If none of the listed cargo types is waiting at the station, the <code style="color:darkgreen">default</code> callback will be used.

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="wikitable sortable"
! callback
! return value
! comment
|-
| default
| spritegroup
| See [[#Graphics|below]].
|-
| purchase
| spritegroup or spriteset
| See [[#Graphics|below]]. If a spritegroup is linked instead of a spriteset, the "zero cargo amount" spriteset is used.
|-
| custom_spritesets
| Array of spritesets
| See [[#Graphics|below]].
|-
| sprite_layouts
| Array of spritelayouts
| See [[#Graphics|below]]. The number of sprite_layouts must be even, alternating X (⤢) and Y (⤡) orientations.
|-
| select_sprite_layout
| index into sprite_layouts[]
| See [[#Graphics|below]]. The result's even-/oddness is ignored. The orientation is always adjusted by OpenTTD.
|-
| purchase_select_sprite_layout
| index into sprite_layouts[]
| See [[#Graphics|below]]. The result's even-/oddness is ignored. The orientation is always adjusted by OpenTTD.
|-
| prepare_layout
| expression list
| See [[#Graphics|below]].
|-
| purchase_prepare_layout
| expression list
| See [[#Graphics|below]].
|-
| foundations
| sprite set
| See [[#foundations|below]].
|-
| availability
| [0 <nowiki>|</nowiki> 1]
| Return 1 to make the station show up in the build window
|-
| tile_check
| Same as for the [[NML:IndustryTiles#Location check results|location_check]] industry callback
| Decide whether station may be built on this tile. This is an additional check to all built-in checks (like slope checks), you can only further restrict construction, not lessen conditions.

Called before constructing the station section, so nothing exists on the map yet. Since the station isn't built yet, so you can't access station variables.
Only these variables are available: company-information, and the class, height, slope, terrain type and water status of nearby tiles.
* <code style="color:darkgreen">getbits(extra_callback_info1, 4, 4)</code>: The [[NML:List_of_tile_slopes|tile slope]] of the tile.
* <code style="color:darkgreen">getbits(extra_callback_info1, 0, 4)</code>: The [[NML:List_of_tile_slopes|tile slope]] of the tile, adjusted by station orientation:
** unmodified in X direction (⤢)
** mirrored in Y direction (⤡)
* <code style="color:darkgreen">getbits(extra_callback_info2, 0, 8)</code>: Tile position along the new-built platform. (0 = north tile)
* <code style="color:darkgreen">getbits(extra_callback_info2, 8, 8)</code>: Platform number within the new-built section. (0 = north platform)
* <code style="color:darkgreen">getbits(extra_callback_info2, 16, 8)</code>: Length of the new section being built.
* <code style="color:darkgreen">getbits(extra_callback_info2, 24, 8)</code>: Number of platforms in the new section being built.

|-
| select_tile_type
| [0 <nowiki>|</nowiki> 2 <nowiki>|</nowiki> 4 <nowiki>|</nowiki> 6]

Since {{ottdp|15}}, even values up to FE can be returned as long as the tile is defined.
| Decides which tile type to store for each tile during construction. The lowest bit is always defined by the station orientation, no matter the callback result. See also [[#Tile_types|tile type above]].

Called before constructing the station section, so nothing exists on the map yet. Since the station isn't built yet, so you can't access station variables.
Only these variables are available: company-information, and the class, height, slope, terrain type and water status of nearby tiles.
* <code style="color:darkgreen">getbits(extra_callback_info1, 0, 4)</code>: Tile position along the new-built platform. (0 = north tile)
* <code style="color:darkgreen">getbits(extra_callback_info1, 4, 4)</code>: Tile position along the new-built platform. (0 = south tile)
* <code style="color:darkgreen">getbits(extra_callback_info1, 8, 4)</code>: Platform number within the new-built section. (0 = north platform)
* <code style="color:darkgreen">getbits(extra_callback_info1, 12, 4)</code>: Platform number within the new-built section. (0 = south platform)
* <code style="color:darkgreen">getbits(extra_callback_info1, 16, 4)</code>: Length of the new section being built.
* <code style="color:darkgreen">getbits(extra_callback_info1, 20, 4)</code>: Number of platforms in the new section being built.
* <code style="color:darkgreen">getbits(extra_callback_info1, 24, 8)</code>: Original tile type in static layout.

|-
| 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>: 32 random bits, if enabled in the <code style="color:darkgreen">general_flags</code> property.
Returning a sound effect in the high byte will cause that sound effect to be played.

Note: Every time the animation frame is changed the map tile will be refreshed, even if the selected graphics stay the same. Therefore using the animation frame as a timer should be avoided, and animation triggers should be preferred instead.
|-
| anim_control
| Next animation frame or CB_RESULT_XXX
|
Called whenever an animation trigger happens. Return the animation frame to show, or CB_RESULT_XXX with XXX = [CB_RESULT_START_ANIMATION <nowiki>|</nowiki> STOP_ANIMATION <nowiki>|</nowiki> DO_NOTHING] to respectively start the animation in its current frame, stop the animation or do nothing. Returning a sound effect in the high byte will cause that sound effect to be played.
* <code style="color:darkgreen">extra_callback_info1</code>: 32 random bits. The low 16 bits are always different for each station tile, but the high 16 bits are the same for all triggered tiles.
* <code style="color:darkgreen">getbits(extra_callback_info2, 0, 8)</code>: Reason for the callback trigger (STAT_ANIM_xxx). Note that you need to enable the wanted triggers in the <code style="color:darkgreen">animation_triggers</code> property.
* <code style="color:darkgreen">getbits(extra_callback_info2, 8, 8)</code>: Cargo-type involved in the trigger. Only applies to STAT_ANIM_CARGO_ARRIVES, STAT_ANIM_CARGO_REMOVED, STAT_ANIM_TRAIN_LOAD_UNLOAD.
Note: Every time the animation frame is changed the map tile will be refreshed, even if the selected graphics stay the same. Therefore using the animation frame as a timer should be avoided, and animation triggers should be preferred instead.
|-
| anim_speed
| 0 .. 16
| Decide the time an animation frame should last. Return value is interpreted as (num_ticks = 2^anim_speed), which each tick lasting 30 ms. Avoid using this callback if possible, since it has to be called each tick for every animated tile. This can be used to create animation frames that last between 30 ms and 33 minutes.
|}

=== Graphics ===

[[File:Nml_station_graphics.dot.png|1000px]]

=== foundations ===

If <code style="color:darkgreen">STAT_FLAG_CUSTOM_FOUNDATIONS</code> is enabled in <code style="color:darkgreen">general_flags</code> you can draw custom foundation for station tiles on sloped terrain.

There are two options for providing foundation sprites:

==== STAT_FLAG_EXTENDED_FOUNDATIONS not set ====
The callback should return a spriteset looking like this:

[[File:simple_foundations.png]]

The foundations will be drawn by combining multiple sprites, as needed for the slope.

==== STAT_FLAG_EXTENDED_FOUNDATIONS ====
The callback should return a spritset looking like this:

[[File:extended_foundations.png]]

In addition you will have to check
* <code style="color:darkgreen">getbits(extra_callback_info2, 16, 2)</code>:
** 0: sprites as in template above.
** 1: sprites like before, but with no wall on NW edge.
** 2: sprites like before, but with no wall on NE edge.
** 3: sprites like before, but with no walls on either north edge.

NML:Vehicles

2026-06-05T08:11:55Z

Rito12: /* Variables that require an argument */ ` -> <code>

{{NMLNavPropVarCB}}
==Properties common to all vehicle types==

{| class="wikitable sortable"
! 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. If set to 0, cargo does not age. Repeated tests have shown that the gameplay effects of this property often do not match the expectations of grf authors. Explaining why requires a detailed understanding of the OpenTTD cargo aging algorithm, and how that works with e.g. different map sizes, vehicle speeds, multi-leg feeder systems, etc. TL;DR avoid using this property unless you absolutely understand the effect it will have.
|-
| <code style="color:green">variant_group</code>
| Vehicle ID or alternatively the vehicle numeric ID (0 ... 65535)
| no
|
{{ottd|13}} This property supports grouping vehicles in the purchase menu (also the autoreplace menu). The property value is the ID of another vehicle in the same GRF which will act as the parent for vehicles in the group.

Groups can also be nested (this is experimental as of December 2022 and may change with testing).

See also vehicle extra_flags which can influence the behaviour of vehicles in variant groups.

See also https://github.com/OpenTTD/OpenTTD/pull/10220
|-
| <code style="color:green">extra_flags</code>
| bitmask(VEHICLE_FLAG_XXX, ...)
| no
| {{ottd|13}}
;VEHICLE_FLAG_DISABLE_NEW_VEHICLE_MESSAGE
: Disable "New Vehicle" news message for this engine
;VEHICLE_FLAG_DISABLE_EXCLUSIVE_PREVIEW
: Disable "Exclusive Preview" for this engine
;VEHICLE_FLAG_SYNC_VARIANT_EXCLUSIVE_PREVIEW
: Variants - Include this variant when primary engine has "Exclusive Preview"
;VEHICLE_FLAG_SYNC_VARIANT_RELIABILITY
: Variants - (Attempt to) Synchronize reliability the primary engine.
|-
| <code style="color:green">badges</code>
| Array of badge labels from the [[NML:Badgetable|badgetable]].
| yes
| Since {{ottd|15.0}}
|}

===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. The length of each phase and the starting, peak, and final reliabilities are randomized for each engine when starting a new game. Also note that phase 2 (the vehicle's peak performance) is actually about 8 years shorter than the <code style="color:darkgreen">model_life</code> parameter.

{| 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 + (0 to 15 months)
| stays constant at peak, 75-100%
|-
| 3
| 10 to 20.6 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.

==Train properties==

{| class="wikitable sortable"
! 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). See also curve_speed_mod property.
;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. {{ottdp|13|no|no}} this flag is no longer required, flip is always allowed, except for multi-header or articulated vehicles which cannot be flipped. For vehicles shorter than 8/8, see [[Action0/Vehicles/Trains#cite_note-6|this note about sprite offsets]]
;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
;TRAIN_FLAG_SPRITE_STACK
:{{ottdp|1.7|no|ottdrev=r27668}} Enable [[NML:Vehicles#Composing_vehicles_from_multiple_sprites|composition from multiple sprites]].
|-
| <code style="color:green">extra_flags</code>
| bitmask(VEHICLE_FLAG_XXX, ...)
| yes
| {{ottd|16}}
;VEHICLE_FLAG_TRAIN_HAS_CAB
: Train wagon has a cab and can lead a train when driving backwards, without any speed reduction.
Additionally, trains have the extra flags common to all vehicle types, described above.
|-
| <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>
|{{ottd|15.0.0}} array of items from railtypetable {{ottd|<15.0.0}} 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. It also sets the corresponding sound effect of the engine, and if visual_effect_and_powered is not set, the visual effect as well.
;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) * 9.8 * weight (in tons), with 9.8 being an approximation of the acceleration of gravity (9.81 m/s).
|-
| <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
|
There are two methods to set the visual effect of a vehicle:
* <code style="color:green">visual_effect_and_powered</code>: Easy method for simple effects.
* <code style="color:green">effect_spawn_model_and_powered</code> + callback <code style="color:green">create_effect</code>: {{ottdp|1.5|no|ottdrev=r26747}} Harder to use, but also more powerful.
For each vehicle you have to decide for the method. You cannot use them both for the same vehicle 'item'.

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">effect_spawn_model_and_powered</code>
| <code style="color:green">EFFECT_SPAWN_MODEL_XXX</code> or <code style="color:green">EFFECT_SPAWN_MODEL_XXX <nowiki>|</nowiki> ENABLE_WAGON_POWER</code>
| yes
|
There are two methods to set the visual effect of a vehicle:
* <code style="color:green">visual_effect_and_powered</code>: Easy method for simple effects.
* <code style="color:green">effect_spawn_model_and_powered</code> + callback <code style="color:green">create_effect</code>: {{ottdp|1.5|no|ottdrev=r26747}} Harder to use, but also more powerful.
For each vehicle you have to decide for the method. You cannot use them both for the same vehicle 'item'.

{{ottdp|1.5|no|ottdrev=r26747}} Set the spawning model of visual effects for the vehicle, that is when the vehicle emits visual effects.
The visual appearance itself is defined by the callback 'create_effect'.

;EFFECT_SPAWN_MODEL_NONE
: Do not spawn any effects.
;EFFECT_SPAWN_MODEL_STEAM
: Gradually less effects when approaching max speed.
;EFFECT_SPAWN_MODEL_DIESEL
: Effect proportional to acceleration, no effect when idling at top speed.
;EFFECT_SPAWN_MODEL_ELECTRIC
: Random effect, gradually less likely when approaching max speed.
|-
| <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>]]
|-
| <code style="color:green">curve_speed_mod</code>
| -128 ... 127.996 (float)
| yes
| {{nml|0.7}} {{ottd|12.0}} Maximum curve speed modifier.

The modifier is applied after the normal curve speed calculation is done using the formula max_curve_speed * (1 + curve_speed_mod). This means that the default property value of 0 is equivalent to no change. Negative values are supported, but the resulting vehicle curve speed is clamped at 2 mph-ish to make sure vehicles don't become permanently stuck.

If different vehicles in a train have different curve speed modifiers, the lowest value wins.

See also TRAIN_FLAG_TILT, which is an older and less flexible way of managing vehicle curve speed.
|}

==Road vehicle properties==

{| class="wikitable sortable"
! property
! value range
! available for articulated vehicle
! comment
|-
| sprite_id
| SPRITE_ID_NEW_ROADVEH
| yes
| Set this property to enable new graphics
|-
| speed
| 0 ... 511km/h (float, speed units)
| no
|
|-
| road_type ''or'' tram_type
| item from [[NML:Railtypetable-Roadtypetable-Tramtypetable|roadtypetable]] or [[NML:Railtypetable-Roadtypetable-Tramtypetable|tramtypetable]]
| must be the same as front
| Only ''one'' of these properties may be set.
If <code style="color:green">tram_type</code> is set, <code style="color:green">ROADVEH_FLAG_TRAM</code> must also be set for the vehicle in <code style="color:green">misc_flags</code>.

If not set, road vehicles will default to ROAD and tram vehicles will default to RAIL (this does not overlap with railtype RAIL).
|-
| 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
;ROADVEH_FLAG_SPRITE_STACK
:{{ottdp|1.7|no|ottdrev=r27668}} Enable [[NML:Vehicles#Composing_vehicles_from_multiple_sprites|composition from multiple sprites]].
|-
| 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]].
 {{ottdp|1.6|no|ottdrev=r27507}} Since OpenTTD r27507 also <code style="color:green">sound("sound.wav")</code> and <code style="color:green">import_sound(grfid, number)</code> are valid here.
|-
| visual_effect
| visual_effect( VISUAL_EFFECT_XXX, offset)
| yes
|
There are two methods to set the visual effect of a vehicle:
* <code style="color:green">visual_effect</code>: Easy method for simple effects.
* <code style="color:green">effect_spawn_model</code> + callback <code style="color:green">create_effect</code>: {{ottdp|1.5|no|ottdrev=r26747}} Harder to use, but also more powerful.
For each vehicle you have to decide for the method. You cannot use them both for the same vehicle 'item'.

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">effect_spawn_model</code>
| <code style="color:green">EFFECT_SPAWN_MODEL_XXX</code>
| yes
|
There are two methods to set the visual effect of a vehicle:
* <code style="color:green">visual_effect</code>: Easy method for simple effects.
* <code style="color:green">effect_spawn_model</code> + callback <code style="color:green">create_effect</code>: {{ottdp|1.5|no|ottdrev=r26747}} Harder to use, but also more powerful.
For each vehicle you have to decide for the method. You cannot use them both for the same vehicle 'item'.

{{ottdp|1.5|no|ottdrev=r26747}} Set the spawning model of visual effects for the vehicle, that is when the vehicle emits visual effects.
The visual appearance itself is defined by the callback 'create_effect'.

;EFFECT_SPAWN_MODEL_NONE
: Do not spawn any effects.
;EFFECT_SPAWN_MODEL_STEAM
: Gradually less effects when approaching max speed.
;EFFECT_SPAWN_MODEL_DIESEL
: Effect proportional to acceleration, no effect when idling at top speed.
;EFFECT_SPAWN_MODEL_ELECTRIC
: Random effect, gradually less likely when approaching max speed.
|-
| 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="wikitable sortable"
! 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)
| {{ottd|14}}{{nml|7.5}} 0 .. 32767 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
;SHIP_FLAG_SPRITE_STACK
:{{ottdp|1.7|no|ottdrev=r27668}} Enable [[NML:Vehicles#Composing_vehicles_from_multiple_sprites|composition from multiple sprites]].
|-
| 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]].
 {{ottdp|1.6|no|ottdrev=r27507}} Since OpenTTD r27507 also <code style="color:green">sound("sound.wav")</code> and <code style="color:green">import_sound(grfid, number)</code> are valid here.
|-
| 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)
|
There are two methods to set the visual effect of a vehicle:
* <code style="color:green">visual_effect</code>: Easy method for simple effects.
* <code style="color:green">effect_spawn_model</code> + callback <code style="color:green">create_effect</code>: {{ottdp|1.5|no|ottdrev=r26747}} Harder to use, but also more powerful.
For each vehicle you have to decide for the method. You cannot use them both for the same vehicle 'item'.

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.
|-
| <code style="color:green">effect_spawn_model</code>
| <code style="color:green">EFFECT_SPAWN_MODEL_XXX</code>
|
There are two methods to set the visual effect of a vehicle:
* <code style="color:green">visual_effect</code>: Easy method for simple effects.
* <code style="color:green">effect_spawn_model</code> + callback <code style="color:green">create_effect</code>: {{ottdp|1.5|no|ottdrev=r26747}} Harder to use, but also more powerful.
For each vehicle you have to decide for the method. You cannot use them both for the same vehicle 'item'.

{{ottdp|1.5|no|ottdrev=r26747}} Set the spawning model of visual effects for the vehicle, that is when the vehicle emits visual effects.
The visual appearance itself is defined by the callback 'create_effect'.

;EFFECT_SPAWN_MODEL_NONE
: Do not spawn any effects.
;EFFECT_SPAWN_MODEL_STEAM
: Gradually less effects when approaching max speed.
;EFFECT_SPAWN_MODEL_DIESEL
: Effect proportional to acceleration, no effect when idling at top speed.
;EFFECT_SPAWN_MODEL_ELECTRIC
: Random effect, gradually less likely when approaching max speed.
|-
| acceleration
| 1 ... 255
| {{ottd|14}} Acceleration in units of ~0.5 km/h per tick. 1 is the default and is the acceleration of default ships.
|}

==Aircraft properties==

{| class="wikitable sortable"
! 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
;AIRCRAFT_FLAG_SPRITE_STACK
:{{ottdp|1.7|no|ottdrev=r27668}} Enable [[NML:Vehicles#Composing_vehicles_from_multiple_sprites|composition from multiple sprites]]. This also affects custom rotor sprites.
|-
| 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
| {{ottd|1.3.1}} 0 ... 255 {{ottd|<1.3.1}} 0 ... 19
| {{ottd|1.3.1}} Default aircraft use values in the range 18 to 50 (= 6.75 to 18.75 mph/tick = 499.5 to 1387.5 mph/day), which is generally considered quite fast. 
{{ottd|<1.3.1}} In older OpenTTD, aircraft provided by NewGRF accelerate 166% faster than intended.
|-
| 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]].
 {{ottdp|1.6|no|ottdrev=r27507}} Since OpenTTD r27507 also <code style="color:green">sound("sound.wav")</code> and <code style="color:green">import_sound(grfid, number)</code> are valid here.
|}

==Vehicle variables==

Below an overview of all vehicle-specific variables. Note 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, similarly checking current_roadtype for a tram won't return a useful result.

===Variables without parameter===

{| class="wikitable sortable"
! 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.
|-
| position_in_articulated_veh
| 0 ... 255
| No
| {{nml|0.3}} {{ottdp|1.4|no|ottdrev=r26157}} The position of the current articulated vehicle from the start of the vehicle. The first will get value 0, the second one gets value 1, etc.
|-
| position_in_articulated_veh_from_end
| 0 ... 255
| No
| {{nml|0.3}} {{ottdp|1.4|no|ottdrev=r26157}} The position of the current articulated vehicle from the end of the vehicle. The last will get value 0, the second last one gets value 1, etc.
|-
| cargo_classes_in_consist
| Bitmask of CC_XXX
| No
|
[[NML:Cargos#Cargo classes|cargo classes]]
|-
| most_common_cargo_type
|
[[NML:Cargos#Cargo properties|Cargo label]]
| No
| The most common cargo type in the consist. Prior to nml r2320 this was known as most_common_refit, and didn't work, and was also incorrectly documented :)
|-
| most_common_cargo_subtype
| 0 ... 255
| No
| The most common cargo subtype for most_common_cargo_type
|-
| 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
|-
| flight_state
| 0 ... 28
| No
| {{nml|0.8.1}} Only for aircrafts.
|-
| 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 ... 0xFFFFFF
| Yes, always 0
| Is increased every time the vehicle moves a single step on the map. Useful for driving animations.
For that, make the animation use a number of frames, which is a power of two, i.e. 2, 4, 8, 16, 32, ... frames, and then use the lower n bits of motion_counter.
|-
| 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_flipped
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the sprite is reversed via flip-vehicle-in-depot (trains only), or if it's the rear-most part of a dual-head engine.
|-
| vehicle_is_reversed
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle has reversed an odd number of times
|-
| train_is_driving_backwards
| [0 <nowiki>|</nowiki> 1]
| No
| {{ottd|16}} Value is 1 if the train is driving backwards (trains only)
|-
| built_during_preview
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle was built during the exclusive preview stage
|-
| current_railtype
| Entry from railtype translation table or 0xFF
| No
| This variable is useless due to equivalent railtypes, use tile_xxx_railtype instead. If you do use this variable, it will not work as expected 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.
|-
| current_roadtype
| Entry from current_roadtype translation table or 0xFF
| No
| {{nml|0.5}} {{ottdp|1.10|no}} This variable is useless due to equivalent roadtypes, use tile_xxx_roadtype instead. Don't use this variable unless you've defined a roadtype translation table. If the road vehicle is running on a roadtype that is not listed in your roadtype translation table this variable will contain 0xFF. Checking this for a tram is not supported and will not return a useful result.
|-
| current_tramtype
| Entry from tramtype translation table or 0xFF
| No
| {{nml|0.5}} {{ottdp|1.10|no}} This variable is useless due to equivalent tramtypes, use tile_xxx_tramtype instead. Don't use this variable unless you've defined a tramtype translation table. If the road vehicle is running on a tramtype that is not listed in your tramtype translation table this variable will contain 0xFF. Checking this for a road vehicle that is not a tram is not supported and will not return a useful result.
|-
| tile_has_catenary
| [0 <nowiki>|</nowiki> 1]
| No
| {{ottdp|1.11|no}} True if the track_type on the tile has catenary. This is a little simplified as it is intended for sprite changes (e.g. raise/lower pantograph) and only checks for "some catenary". To distinguish different types of electric track, AC and DC voltages etc, ... use tile_xxx_railtype/tile_xxx_roadtype/tile_xxx_tramtype instead.
|-
| 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 or a name defined in item block
| 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
|-
| vehicle_is_unloading
| [0 <nowiki>|</nowiki> 1]
| No
| {{ottdp|1.5|2.5|ottdrev=r26430}} Value is 1 if the vehicle is unloading at a station and has not yet started loading new cargo.
|}

===Variables that require an argument===

{| class="wikitable sortable"
! 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">Argument 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_y_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_z_offset
| 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.
|-
| tile_supports_railtype tile_supports_roadtype tile_supports_tramtype
| Entry from rail/road/tram translation table
| [0 <nowiki>|</nowiki> 1]
| No
| {{ottdp|1.11|no}} Vehicles of the track_type label used as parameter are compatible with the rail/road/tram track_type on the current tile. Example: <code style="color:darkgreen">tile_supports_railtype(ELRL)</code>
|-
| tile_powers_railtype tile_powers_roadtype tile_powers_tramtype
| Entry from rail/road/tram translation table
| [0 <nowiki>|</nowiki> 1]
| No
| {{ottdp|1.11|no}} Vehicles of the track_type label used as parameter are powered on the rail/road/tram track_type on the current tile. Example: <code style="color:darkgreen">tile_powers_railtype(ELRL)</code>
|-
| tile_is_railtype tile_is_roadtype tile_is_tramtype
| Entry from rail/road/tram translation table
| [0 <nowiki>|</nowiki> 1]
| No
| {{ottdp|1.11|no}} The track_type label used as parameter is identical or equivalent (listed as alternate label in rail-/road-/tram-type property 1D) to the rail/road/tram track_type on the current tile. Example: <code style="color:darkgreen">tile_is_railtype(ELRL)</code>
|-
| has_badge
| Label from the [[NML:Badgetable|badgetable]].
| [0 <nowiki>|</nowiki> 1]
| yes
| {{ottd|15.0}} {{nml|0.9.0}} Check if the vehicle has that specific badge attached.
|-
| count_has_badge
| Label from the [[NML:Badgetable|badgetable]].
| 0..255
| no
| {{ottd|15.0}} {{nml|0.9.0}} The number of vehicles in the current consist that have that specific badge attached.
|-
| tile_has_railtype_badge tile_has_roadtype_badge tile_has_tramtype_badge
| Label from the [[NML:Badgetable|badgetable]].
| [0 <nowiki>|</nowiki> 1]
| no
| {{ottd|15.0}} {{nml|0.9.0}} Check if the rail/road/tram type of the current tile occupied by the vehicle has that specific badge attached. '''Trains/RVs/Trams only.''' <code>tile_has_roadtype_badge</code> also works for trams to allow code reuse.
|}
<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="wikitable sortable"
! 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
| NOTE: As of OpenTTD 13, this feature is considered deprecated for most uses. Use variants instead. 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 to select specific sprites for the vehicle's current cargo subtype.
|-
| 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">getbits(extra_callback_info1, 0, 8)</code> 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">getbits(extra_callback_info1, 0, 8)</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.

The vehicle ID for the articulated part must be in the range 0 .. 16383.

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. If a wagon is inserted in the middle, all wagons are removed and attached one-by-one in the new order. This callback has to be defined at the engine. The scopes behave different than usual though:
* <code style="color:darkgreen">SELF</code> refers to the wagon being attached. (despite the callback being defined at the engine)
* <code style="color:darkgreen">PARENT</code> refers to the consist of the engine up to the wagon before <code style="color:darkgreen">SELF</code>, i.e. not (yet) including the wagon being attached.
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.
* <code style="color:darkgreen">getbits(extra_callback_info1, 0, 8)</code>: The new cargo type.
* <code style="color:darkgreen">getbits(extra_callback_info1, 8, 8)</code>: The new cargo subtype (see <code style="color:darkgreen">cargo_subtype_text</code>-callback).
* <code style="color:darkgreen">getbits(extra_callback_info1, 16, 16)</code>: 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.
|-
| create_effect
| {{ottdp|1.5|no|ottdrev=r26747}} Trains, Road Vehicles, Ships
| No
| 0 .. 3 for number of effects. Optionally add <code style="color:darkgreen">CB_RESULT_CREATE_EFFECT_CENTER</code> and/or <code style="color:darkgreen">CB_RESULT_CREATE_EFFECT_NO_ROTATION</code>
| Called when a effect spawning model is defined via <code style="color:darkgreen">effect_spawn_model</code> resp. <code style="color:darkgreen">effect_spawn_model_and_powered</code>.

The result specifies how many effects shall be created.
The position and appearance of the individual effects is returned via registers 0x100 to 0x103:
<pre style="color:blue">
switch (FEAT_XXX, SELF, switch_name, [
STORE_TEMP(create_effect(EFFECT_SPRITE_XXX, 8, -3, 10), 0x100), // first effect,
STORE_TEMP(create_effect(EFFECT_SPRITE_YYY, 8, 3, 10), 0x101) // second effect, ...
]) {
return 2; // number of effects
}
</pre>
The register values are created using the <code style="color:darkgreen">create_effect(''effect_sprite'', ''l_x_offset'', ''t_y_offset'', ''z_offset'')</code> function:
* ''effect_sprite'': Sprite for the effect. One of <code style="color:darkgreen">EFFECT_SPRITE_</code>[<code style="color:darkgreen">NONE</code>|<code style="color:darkgreen">STEAM</code>|<code style="color:darkgreen">DIESEL</code>|<code style="color:darkgreen">ELECTRIC</code>|<code style="color:darkgreen">AIRCRAFT_BREAKDOWN_SMOKE</code>].
* ''l_x_offset'': Longitudinal or X position of the effect, depending on callback result <code style="color:darkgreen">CB_RESULT_CREATE_EFFECT_NO_ROTATION</code>.
* ''t_y_offset'': Transversal or Y position of the effect, depending on callback result <code style="color:darkgreen">CB_RESULT_CREATE_EFFECT_NO_ROTATION</code>.
* ''z_offset'': Z position of the effect.

Additional to the number of effects, the callback result may specify these flags:
;<code style="color:darkgreen">CB_RESULT_CREATE_EFFECT_CENTER</code>
:(Train and road vehicle only) If set, position effect relative to vehicle center instead of relative to vehicle sprite. (behaves the same for vehicles with length 8/8)
;<code style="color:darkgreen">CB_RESULT_CREATE_EFFECT_NO_ROTATION</code>
*If not set, the parameters to <code style="color:darkgreen">effect_sprite</code> describe longitudinal/transversal positions, which are rotate wrt. vehicle orientation.
*If set, the parameters to <code style="color:darkgreen">effect_sprite</code> describe X and Y positions, which are not automatically rotated.
|-
| reverse_build_probability
| {{nml|0.7.5}} {{ottd|14.0}} Trains
| No
| 0
| Probability of reversing rail vehicle, i.e. facing forward or backward, when purchased.
|-
| refit
| {{ottd|15.0}} All vehicle types
| Callback runs once, in purchase scope only
|
* 0 Don't change refittability (i.e. use whatever the evaluation of the various refittability vehicle props has determined).
* 1 Allow cargo type as a refit.
* 2 Disallow cargo type as a refit.
|

The custom refit callback allows overriding the refittablity of each cargo as defined by the standard vehicle properties. It will be called for each defined cargo type once after the game has loaded all NewGRF files. The callback is run in purchase list scope, i.e. for cargotype FF. No variables of an actual vehicle are available. Information about the cargo type the callback is called for is available in variables 10 and 18:
'''Note:''' As this callback is not re-evaluated after game initialization, using any dynamic variables like e.g. game date will lead to undefined and faulty behaviour.

This callback is available starting with {{ottdp|15|no|ottdrev=gd2496b6ec4}} OpenTTD 15.

See https://newgrf-specs.tt-wiki.net/wiki/Callbacks#Custom_refit_.28163.29
|}

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

{| class="wikitable sortable"
! 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
|
|-
| effect_spawn_model_and_powered
| Trains
| No
|
|-
| effect_spawn_model
| 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
|
|-
| curve_speed_mod
| {{nml|0.7}} {{ottd|12.0}} Trains
| No
|
|-
| name
| {{nml|0.7.2}} {{ottd|14.0}} All
| Yes
| Can be used to display vehicle name differently depending on context (purchase menu, depot, nested variant depth etc). <code style="color:darkgreen">extra_callback_info1</code> contains detailed information about context - please see https://newgrf-specs.tt-wiki.net/wiki/Callbacks#Engine_name_.28161.29
|}

===Sprites in GUI===
{{ottdp|1.2|no|ottdrev=r23080}} Since OpenTTD r23080 you can use variable <code style="color:darkgreen">getbits(extra_callback_info1, 0, 8)</code> to display different sprites in the GUI and on the map. Currently these cases are available:
{| |-
! getbits(extra_callback_info1, 0, 8) !! 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 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.

===Composing vehicles from multiple sprites===
{{ottdp|1.7|no|ottdrev=r27668}} Since OpenTTD r27668 you can draw vehicles by drawing multiple sprites on top of each other.
* The sprites can use different recolouring.
* When using 32bpp sprites, the sprites can use the alpha channel to blend with the other sprites. In particular you can use this to alpha-blend company colours over other sprites.

To enable this, you need to set <code style="color:darkgreen">XXX_FLAG_SPRITE_STACK</code> in the <code style="color:darkgreen">misc_flags</code> property.

When enabled, sprites are resolved multiple times while incrementing an iteration number, that can be read via
<code style="color:darkgreen">getbits(extra_callback_info1, 8, 8)</code>

For OpenTTD 1.7 to 12.0, this is limited to at most 4 sprites per articulated part.

Increased to 8 sprites per articulated part for OpenTTD 13.0 {{ottdp|13.0|no}}

In addition you need to set register 100 as additional result:
* <code style="color:darkgreen">STORE_TEMP(CB_FLAG_MORE_SPRITES | recolouring, 0x100)</code> if there are more sprites to draw.
* <code style="color:darkgreen">STORE_TEMP(recolouring, 0x100)</code> if there are no more sprites to draw.
"recolouring" can be:
* <code>PALETTE_USE_DEFAULT</code> to use the default vehicle recolouring.
* <code>PALETTE_IDENTITY</code> to use no recolouring
* Any other default or custom recolouring sprite.

===Sound events===

{| class="wikitable sortable"
! 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
|}

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

Note that while vehicle ID affects the order in which vehicles appear in the purchase menu, this can be overridden using the [[NML:Sorting vehicles in the purchase list|sort block]].

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

NML:Vehicles

2026-06-05T08:11:21Z

Rito12: /* Variables that require an argument */ Fix the style.

{{NMLNavPropVarCB}}
==Properties common to all vehicle types==

{| class="wikitable sortable"
! 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. If set to 0, cargo does not age. Repeated tests have shown that the gameplay effects of this property often do not match the expectations of grf authors. Explaining why requires a detailed understanding of the OpenTTD cargo aging algorithm, and how that works with e.g. different map sizes, vehicle speeds, multi-leg feeder systems, etc. TL;DR avoid using this property unless you absolutely understand the effect it will have.
|-
| <code style="color:green">variant_group</code>
| Vehicle ID or alternatively the vehicle numeric ID (0 ... 65535)
| no
|
{{ottd|13}} This property supports grouping vehicles in the purchase menu (also the autoreplace menu). The property value is the ID of another vehicle in the same GRF which will act as the parent for vehicles in the group.

Groups can also be nested (this is experimental as of December 2022 and may change with testing).

See also vehicle extra_flags which can influence the behaviour of vehicles in variant groups.

See also https://github.com/OpenTTD/OpenTTD/pull/10220
|-
| <code style="color:green">extra_flags</code>
| bitmask(VEHICLE_FLAG_XXX, ...)
| no
| {{ottd|13}}
;VEHICLE_FLAG_DISABLE_NEW_VEHICLE_MESSAGE
: Disable "New Vehicle" news message for this engine
;VEHICLE_FLAG_DISABLE_EXCLUSIVE_PREVIEW
: Disable "Exclusive Preview" for this engine
;VEHICLE_FLAG_SYNC_VARIANT_EXCLUSIVE_PREVIEW
: Variants - Include this variant when primary engine has "Exclusive Preview"
;VEHICLE_FLAG_SYNC_VARIANT_RELIABILITY
: Variants - (Attempt to) Synchronize reliability the primary engine.
|-
| <code style="color:green">badges</code>
| Array of badge labels from the [[NML:Badgetable|badgetable]].
| yes
| Since {{ottd|15.0}}
|}

===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. The length of each phase and the starting, peak, and final reliabilities are randomized for each engine when starting a new game. Also note that phase 2 (the vehicle's peak performance) is actually about 8 years shorter than the <code style="color:darkgreen">model_life</code> parameter.

{| 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 + (0 to 15 months)
| stays constant at peak, 75-100%
|-
| 3
| 10 to 20.6 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.

==Train properties==

{| class="wikitable sortable"
! 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). See also curve_speed_mod property.
;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. {{ottdp|13|no|no}} this flag is no longer required, flip is always allowed, except for multi-header or articulated vehicles which cannot be flipped. For vehicles shorter than 8/8, see [[Action0/Vehicles/Trains#cite_note-6|this note about sprite offsets]]
;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
;TRAIN_FLAG_SPRITE_STACK
:{{ottdp|1.7|no|ottdrev=r27668}} Enable [[NML:Vehicles#Composing_vehicles_from_multiple_sprites|composition from multiple sprites]].
|-
| <code style="color:green">extra_flags</code>
| bitmask(VEHICLE_FLAG_XXX, ...)
| yes
| {{ottd|16}}
;VEHICLE_FLAG_TRAIN_HAS_CAB
: Train wagon has a cab and can lead a train when driving backwards, without any speed reduction.
Additionally, trains have the extra flags common to all vehicle types, described above.
|-
| <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>
|{{ottd|15.0.0}} array of items from railtypetable {{ottd|<15.0.0}} 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. It also sets the corresponding sound effect of the engine, and if visual_effect_and_powered is not set, the visual effect as well.
;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) * 9.8 * weight (in tons), with 9.8 being an approximation of the acceleration of gravity (9.81 m/s).
|-
| <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
|
There are two methods to set the visual effect of a vehicle:
* <code style="color:green">visual_effect_and_powered</code>: Easy method for simple effects.
* <code style="color:green">effect_spawn_model_and_powered</code> + callback <code style="color:green">create_effect</code>: {{ottdp|1.5|no|ottdrev=r26747}} Harder to use, but also more powerful.
For each vehicle you have to decide for the method. You cannot use them both for the same vehicle 'item'.

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">effect_spawn_model_and_powered</code>
| <code style="color:green">EFFECT_SPAWN_MODEL_XXX</code> or <code style="color:green">EFFECT_SPAWN_MODEL_XXX <nowiki>|</nowiki> ENABLE_WAGON_POWER</code>
| yes
|
There are two methods to set the visual effect of a vehicle:
* <code style="color:green">visual_effect_and_powered</code>: Easy method for simple effects.
* <code style="color:green">effect_spawn_model_and_powered</code> + callback <code style="color:green">create_effect</code>: {{ottdp|1.5|no|ottdrev=r26747}} Harder to use, but also more powerful.
For each vehicle you have to decide for the method. You cannot use them both for the same vehicle 'item'.

{{ottdp|1.5|no|ottdrev=r26747}} Set the spawning model of visual effects for the vehicle, that is when the vehicle emits visual effects.
The visual appearance itself is defined by the callback 'create_effect'.

;EFFECT_SPAWN_MODEL_NONE
: Do not spawn any effects.
;EFFECT_SPAWN_MODEL_STEAM
: Gradually less effects when approaching max speed.
;EFFECT_SPAWN_MODEL_DIESEL
: Effect proportional to acceleration, no effect when idling at top speed.
;EFFECT_SPAWN_MODEL_ELECTRIC
: Random effect, gradually less likely when approaching max speed.
|-
| <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>]]
|-
| <code style="color:green">curve_speed_mod</code>
| -128 ... 127.996 (float)
| yes
| {{nml|0.7}} {{ottd|12.0}} Maximum curve speed modifier.

The modifier is applied after the normal curve speed calculation is done using the formula max_curve_speed * (1 + curve_speed_mod). This means that the default property value of 0 is equivalent to no change. Negative values are supported, but the resulting vehicle curve speed is clamped at 2 mph-ish to make sure vehicles don't become permanently stuck.

If different vehicles in a train have different curve speed modifiers, the lowest value wins.

See also TRAIN_FLAG_TILT, which is an older and less flexible way of managing vehicle curve speed.
|}

==Road vehicle properties==

{| class="wikitable sortable"
! property
! value range
! available for articulated vehicle
! comment
|-
| sprite_id
| SPRITE_ID_NEW_ROADVEH
| yes
| Set this property to enable new graphics
|-
| speed
| 0 ... 511km/h (float, speed units)
| no
|
|-
| road_type ''or'' tram_type
| item from [[NML:Railtypetable-Roadtypetable-Tramtypetable|roadtypetable]] or [[NML:Railtypetable-Roadtypetable-Tramtypetable|tramtypetable]]
| must be the same as front
| Only ''one'' of these properties may be set.
If <code style="color:green">tram_type</code> is set, <code style="color:green">ROADVEH_FLAG_TRAM</code> must also be set for the vehicle in <code style="color:green">misc_flags</code>.

If not set, road vehicles will default to ROAD and tram vehicles will default to RAIL (this does not overlap with railtype RAIL).
|-
| 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
;ROADVEH_FLAG_SPRITE_STACK
:{{ottdp|1.7|no|ottdrev=r27668}} Enable [[NML:Vehicles#Composing_vehicles_from_multiple_sprites|composition from multiple sprites]].
|-
| 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]].
 {{ottdp|1.6|no|ottdrev=r27507}} Since OpenTTD r27507 also <code style="color:green">sound("sound.wav")</code> and <code style="color:green">import_sound(grfid, number)</code> are valid here.
|-
| visual_effect
| visual_effect( VISUAL_EFFECT_XXX, offset)
| yes
|
There are two methods to set the visual effect of a vehicle:
* <code style="color:green">visual_effect</code>: Easy method for simple effects.
* <code style="color:green">effect_spawn_model</code> + callback <code style="color:green">create_effect</code>: {{ottdp|1.5|no|ottdrev=r26747}} Harder to use, but also more powerful.
For each vehicle you have to decide for the method. You cannot use them both for the same vehicle 'item'.

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">effect_spawn_model</code>
| <code style="color:green">EFFECT_SPAWN_MODEL_XXX</code>
| yes
|
There are two methods to set the visual effect of a vehicle:
* <code style="color:green">visual_effect</code>: Easy method for simple effects.
* <code style="color:green">effect_spawn_model</code> + callback <code style="color:green">create_effect</code>: {{ottdp|1.5|no|ottdrev=r26747}} Harder to use, but also more powerful.
For each vehicle you have to decide for the method. You cannot use them both for the same vehicle 'item'.

{{ottdp|1.5|no|ottdrev=r26747}} Set the spawning model of visual effects for the vehicle, that is when the vehicle emits visual effects.
The visual appearance itself is defined by the callback 'create_effect'.

;EFFECT_SPAWN_MODEL_NONE
: Do not spawn any effects.
;EFFECT_SPAWN_MODEL_STEAM
: Gradually less effects when approaching max speed.
;EFFECT_SPAWN_MODEL_DIESEL
: Effect proportional to acceleration, no effect when idling at top speed.
;EFFECT_SPAWN_MODEL_ELECTRIC
: Random effect, gradually less likely when approaching max speed.
|-
| 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="wikitable sortable"
! 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)
| {{ottd|14}}{{nml|7.5}} 0 .. 32767 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
;SHIP_FLAG_SPRITE_STACK
:{{ottdp|1.7|no|ottdrev=r27668}} Enable [[NML:Vehicles#Composing_vehicles_from_multiple_sprites|composition from multiple sprites]].
|-
| 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]].
 {{ottdp|1.6|no|ottdrev=r27507}} Since OpenTTD r27507 also <code style="color:green">sound("sound.wav")</code> and <code style="color:green">import_sound(grfid, number)</code> are valid here.
|-
| 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)
|
There are two methods to set the visual effect of a vehicle:
* <code style="color:green">visual_effect</code>: Easy method for simple effects.
* <code style="color:green">effect_spawn_model</code> + callback <code style="color:green">create_effect</code>: {{ottdp|1.5|no|ottdrev=r26747}} Harder to use, but also more powerful.
For each vehicle you have to decide for the method. You cannot use them both for the same vehicle 'item'.

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.
|-
| <code style="color:green">effect_spawn_model</code>
| <code style="color:green">EFFECT_SPAWN_MODEL_XXX</code>
|
There are two methods to set the visual effect of a vehicle:
* <code style="color:green">visual_effect</code>: Easy method for simple effects.
* <code style="color:green">effect_spawn_model</code> + callback <code style="color:green">create_effect</code>: {{ottdp|1.5|no|ottdrev=r26747}} Harder to use, but also more powerful.
For each vehicle you have to decide for the method. You cannot use them both for the same vehicle 'item'.

{{ottdp|1.5|no|ottdrev=r26747}} Set the spawning model of visual effects for the vehicle, that is when the vehicle emits visual effects.
The visual appearance itself is defined by the callback 'create_effect'.

;EFFECT_SPAWN_MODEL_NONE
: Do not spawn any effects.
;EFFECT_SPAWN_MODEL_STEAM
: Gradually less effects when approaching max speed.
;EFFECT_SPAWN_MODEL_DIESEL
: Effect proportional to acceleration, no effect when idling at top speed.
;EFFECT_SPAWN_MODEL_ELECTRIC
: Random effect, gradually less likely when approaching max speed.
|-
| acceleration
| 1 ... 255
| {{ottd|14}} Acceleration in units of ~0.5 km/h per tick. 1 is the default and is the acceleration of default ships.
|}

==Aircraft properties==

{| class="wikitable sortable"
! 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
;AIRCRAFT_FLAG_SPRITE_STACK
:{{ottdp|1.7|no|ottdrev=r27668}} Enable [[NML:Vehicles#Composing_vehicles_from_multiple_sprites|composition from multiple sprites]]. This also affects custom rotor sprites.
|-
| 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
| {{ottd|1.3.1}} 0 ... 255 {{ottd|<1.3.1}} 0 ... 19
| {{ottd|1.3.1}} Default aircraft use values in the range 18 to 50 (= 6.75 to 18.75 mph/tick = 499.5 to 1387.5 mph/day), which is generally considered quite fast. 
{{ottd|<1.3.1}} In older OpenTTD, aircraft provided by NewGRF accelerate 166% faster than intended.
|-
| 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]].
 {{ottdp|1.6|no|ottdrev=r27507}} Since OpenTTD r27507 also <code style="color:green">sound("sound.wav")</code> and <code style="color:green">import_sound(grfid, number)</code> are valid here.
|}

==Vehicle variables==

Below an overview of all vehicle-specific variables. Note 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, similarly checking current_roadtype for a tram won't return a useful result.

===Variables without parameter===

{| class="wikitable sortable"
! 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.
|-
| position_in_articulated_veh
| 0 ... 255
| No
| {{nml|0.3}} {{ottdp|1.4|no|ottdrev=r26157}} The position of the current articulated vehicle from the start of the vehicle. The first will get value 0, the second one gets value 1, etc.
|-
| position_in_articulated_veh_from_end
| 0 ... 255
| No
| {{nml|0.3}} {{ottdp|1.4|no|ottdrev=r26157}} The position of the current articulated vehicle from the end of the vehicle. The last will get value 0, the second last one gets value 1, etc.
|-
| cargo_classes_in_consist
| Bitmask of CC_XXX
| No
|
[[NML:Cargos#Cargo classes|cargo classes]]
|-
| most_common_cargo_type
|
[[NML:Cargos#Cargo properties|Cargo label]]
| No
| The most common cargo type in the consist. Prior to nml r2320 this was known as most_common_refit, and didn't work, and was also incorrectly documented :)
|-
| most_common_cargo_subtype
| 0 ... 255
| No
| The most common cargo subtype for most_common_cargo_type
|-
| 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
|-
| flight_state
| 0 ... 28
| No
| {{nml|0.8.1}} Only for aircrafts.
|-
| 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 ... 0xFFFFFF
| Yes, always 0
| Is increased every time the vehicle moves a single step on the map. Useful for driving animations.
For that, make the animation use a number of frames, which is a power of two, i.e. 2, 4, 8, 16, 32, ... frames, and then use the lower n bits of motion_counter.
|-
| 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_flipped
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the sprite is reversed via flip-vehicle-in-depot (trains only), or if it's the rear-most part of a dual-head engine.
|-
| vehicle_is_reversed
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle has reversed an odd number of times
|-
| train_is_driving_backwards
| [0 <nowiki>|</nowiki> 1]
| No
| {{ottd|16}} Value is 1 if the train is driving backwards (trains only)
|-
| built_during_preview
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle was built during the exclusive preview stage
|-
| current_railtype
| Entry from railtype translation table or 0xFF
| No
| This variable is useless due to equivalent railtypes, use tile_xxx_railtype instead. If you do use this variable, it will not work as expected 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.
|-
| current_roadtype
| Entry from current_roadtype translation table or 0xFF
| No
| {{nml|0.5}} {{ottdp|1.10|no}} This variable is useless due to equivalent roadtypes, use tile_xxx_roadtype instead. Don't use this variable unless you've defined a roadtype translation table. If the road vehicle is running on a roadtype that is not listed in your roadtype translation table this variable will contain 0xFF. Checking this for a tram is not supported and will not return a useful result.
|-
| current_tramtype
| Entry from tramtype translation table or 0xFF
| No
| {{nml|0.5}} {{ottdp|1.10|no}} This variable is useless due to equivalent tramtypes, use tile_xxx_tramtype instead. Don't use this variable unless you've defined a tramtype translation table. If the road vehicle is running on a tramtype that is not listed in your tramtype translation table this variable will contain 0xFF. Checking this for a road vehicle that is not a tram is not supported and will not return a useful result.
|-
| tile_has_catenary
| [0 <nowiki>|</nowiki> 1]
| No
| {{ottdp|1.11|no}} True if the track_type on the tile has catenary. This is a little simplified as it is intended for sprite changes (e.g. raise/lower pantograph) and only checks for "some catenary". To distinguish different types of electric track, AC and DC voltages etc, ... use tile_xxx_railtype/tile_xxx_roadtype/tile_xxx_tramtype instead.
|-
| 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 or a name defined in item block
| 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
|-
| vehicle_is_unloading
| [0 <nowiki>|</nowiki> 1]
| No
| {{ottdp|1.5|2.5|ottdrev=r26430}} Value is 1 if the vehicle is unloading at a station and has not yet started loading new cargo.
|}

===Variables that require an argument===

{| class="wikitable sortable"
! 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">Argument 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_y_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_z_offset
| 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.
|-
| tile_supports_railtype tile_supports_roadtype tile_supports_tramtype
| Entry from rail/road/tram translation table
| [0 <nowiki>|</nowiki> 1]
| No
| {{ottdp|1.11|no}} Vehicles of the track_type label used as parameter are compatible with the rail/road/tram track_type on the current tile. Example: <code style="color:darkgreen">tile_supports_railtype(ELRL)</code>
|-
| tile_powers_railtype tile_powers_roadtype tile_powers_tramtype
| Entry from rail/road/tram translation table
| [0 <nowiki>|</nowiki> 1]
| No
| {{ottdp|1.11|no}} Vehicles of the track_type label used as parameter are powered on the rail/road/tram track_type on the current tile. Example: <code style="color:darkgreen">tile_powers_railtype(ELRL)</code>
|-
| tile_is_railtype tile_is_roadtype tile_is_tramtype
| Entry from rail/road/tram translation table
| [0 <nowiki>|</nowiki> 1]
| No
| {{ottdp|1.11|no}} The track_type label used as parameter is identical or equivalent (listed as alternate label in rail-/road-/tram-type property 1D) to the rail/road/tram track_type on the current tile. Example: <code style="color:darkgreen">tile_is_railtype(ELRL)</code>
|-
| has_badge
| Label from the [[NML:Badgetable|badgetable]].
| [0 <nowiki>|</nowiki> 1]
| yes
| {{ottd|15.0}} {{nml|0.9.0}} Check if the vehicle has that specific badge attached.
|-
| count_has_badge
| Label from the [[NML:Badgetable|badgetable]].
| 0..255
| no
| {{ottd|15.0}} {{nml|0.9.0}} The number of vehicles in the current consist that have that specific badge attached.
|-
| tile_has_railtype_badge tile_has_roadtype_badge tile_has_tramtype_badge
| Label from the [[NML:Badgetable|badgetable]].
| [0 <nowiki>|</nowiki> 1]
| no
| {{ottd|15.0}} {{nml|0.9.0}} Check if the rail/road/tram type of the current tile occupied by the vehicle has that specific badge attached. '''Trains/RVs/Trams only.''' `tile_has_roadtype_badge` also works for trams to allow code reuse.
|}
<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="wikitable sortable"
! 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
| NOTE: As of OpenTTD 13, this feature is considered deprecated for most uses. Use variants instead. 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 to select specific sprites for the vehicle's current cargo subtype.
|-
| 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">getbits(extra_callback_info1, 0, 8)</code> 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">getbits(extra_callback_info1, 0, 8)</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.

The vehicle ID for the articulated part must be in the range 0 .. 16383.

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. If a wagon is inserted in the middle, all wagons are removed and attached one-by-one in the new order. This callback has to be defined at the engine. The scopes behave different than usual though:
* <code style="color:darkgreen">SELF</code> refers to the wagon being attached. (despite the callback being defined at the engine)
* <code style="color:darkgreen">PARENT</code> refers to the consist of the engine up to the wagon before <code style="color:darkgreen">SELF</code>, i.e. not (yet) including the wagon being attached.
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.
* <code style="color:darkgreen">getbits(extra_callback_info1, 0, 8)</code>: The new cargo type.
* <code style="color:darkgreen">getbits(extra_callback_info1, 8, 8)</code>: The new cargo subtype (see <code style="color:darkgreen">cargo_subtype_text</code>-callback).
* <code style="color:darkgreen">getbits(extra_callback_info1, 16, 16)</code>: 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.
|-
| create_effect
| {{ottdp|1.5|no|ottdrev=r26747}} Trains, Road Vehicles, Ships
| No
| 0 .. 3 for number of effects. Optionally add <code style="color:darkgreen">CB_RESULT_CREATE_EFFECT_CENTER</code> and/or <code style="color:darkgreen">CB_RESULT_CREATE_EFFECT_NO_ROTATION</code>
| Called when a effect spawning model is defined via <code style="color:darkgreen">effect_spawn_model</code> resp. <code style="color:darkgreen">effect_spawn_model_and_powered</code>.

The result specifies how many effects shall be created.
The position and appearance of the individual effects is returned via registers 0x100 to 0x103:
<pre style="color:blue">
switch (FEAT_XXX, SELF, switch_name, [
STORE_TEMP(create_effect(EFFECT_SPRITE_XXX, 8, -3, 10), 0x100), // first effect,
STORE_TEMP(create_effect(EFFECT_SPRITE_YYY, 8, 3, 10), 0x101) // second effect, ...
]) {
return 2; // number of effects
}
</pre>
The register values are created using the <code style="color:darkgreen">create_effect(''effect_sprite'', ''l_x_offset'', ''t_y_offset'', ''z_offset'')</code> function:
* ''effect_sprite'': Sprite for the effect. One of <code style="color:darkgreen">EFFECT_SPRITE_</code>[<code style="color:darkgreen">NONE</code>|<code style="color:darkgreen">STEAM</code>|<code style="color:darkgreen">DIESEL</code>|<code style="color:darkgreen">ELECTRIC</code>|<code style="color:darkgreen">AIRCRAFT_BREAKDOWN_SMOKE</code>].
* ''l_x_offset'': Longitudinal or X position of the effect, depending on callback result <code style="color:darkgreen">CB_RESULT_CREATE_EFFECT_NO_ROTATION</code>.
* ''t_y_offset'': Transversal or Y position of the effect, depending on callback result <code style="color:darkgreen">CB_RESULT_CREATE_EFFECT_NO_ROTATION</code>.
* ''z_offset'': Z position of the effect.

Additional to the number of effects, the callback result may specify these flags:
;<code style="color:darkgreen">CB_RESULT_CREATE_EFFECT_CENTER</code>
:(Train and road vehicle only) If set, position effect relative to vehicle center instead of relative to vehicle sprite. (behaves the same for vehicles with length 8/8)
;<code style="color:darkgreen">CB_RESULT_CREATE_EFFECT_NO_ROTATION</code>
*If not set, the parameters to <code style="color:darkgreen">effect_sprite</code> describe longitudinal/transversal positions, which are rotate wrt. vehicle orientation.
*If set, the parameters to <code style="color:darkgreen">effect_sprite</code> describe X and Y positions, which are not automatically rotated.
|-
| reverse_build_probability
| {{nml|0.7.5}} {{ottd|14.0}} Trains
| No
| 0
| Probability of reversing rail vehicle, i.e. facing forward or backward, when purchased.
|-
| refit
| {{ottd|15.0}} All vehicle types
| Callback runs once, in purchase scope only
|
* 0 Don't change refittability (i.e. use whatever the evaluation of the various refittability vehicle props has determined).
* 1 Allow cargo type as a refit.
* 2 Disallow cargo type as a refit.
|

The custom refit callback allows overriding the refittablity of each cargo as defined by the standard vehicle properties. It will be called for each defined cargo type once after the game has loaded all NewGRF files. The callback is run in purchase list scope, i.e. for cargotype FF. No variables of an actual vehicle are available. Information about the cargo type the callback is called for is available in variables 10 and 18:
'''Note:''' As this callback is not re-evaluated after game initialization, using any dynamic variables like e.g. game date will lead to undefined and faulty behaviour.

This callback is available starting with {{ottdp|15|no|ottdrev=gd2496b6ec4}} OpenTTD 15.

See https://newgrf-specs.tt-wiki.net/wiki/Callbacks#Custom_refit_.28163.29
|}

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

{| class="wikitable sortable"
! 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
|
|-
| effect_spawn_model_and_powered
| Trains
| No
|
|-
| effect_spawn_model
| 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
|
|-
| curve_speed_mod
| {{nml|0.7}} {{ottd|12.0}} Trains
| No
|
|-
| name
| {{nml|0.7.2}} {{ottd|14.0}} All
| Yes
| Can be used to display vehicle name differently depending on context (purchase menu, depot, nested variant depth etc). <code style="color:darkgreen">extra_callback_info1</code> contains detailed information about context - please see https://newgrf-specs.tt-wiki.net/wiki/Callbacks#Engine_name_.28161.29
|}

===Sprites in GUI===
{{ottdp|1.2|no|ottdrev=r23080}} Since OpenTTD r23080 you can use variable <code style="color:darkgreen">getbits(extra_callback_info1, 0, 8)</code> to display different sprites in the GUI and on the map. Currently these cases are available:
{| |-
! getbits(extra_callback_info1, 0, 8) !! 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 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.

===Composing vehicles from multiple sprites===
{{ottdp|1.7|no|ottdrev=r27668}} Since OpenTTD r27668 you can draw vehicles by drawing multiple sprites on top of each other.
* The sprites can use different recolouring.
* When using 32bpp sprites, the sprites can use the alpha channel to blend with the other sprites. In particular you can use this to alpha-blend company colours over other sprites.

To enable this, you need to set <code style="color:darkgreen">XXX_FLAG_SPRITE_STACK</code> in the <code style="color:darkgreen">misc_flags</code> property.

When enabled, sprites are resolved multiple times while incrementing an iteration number, that can be read via
<code style="color:darkgreen">getbits(extra_callback_info1, 8, 8)</code>

For OpenTTD 1.7 to 12.0, this is limited to at most 4 sprites per articulated part.

Increased to 8 sprites per articulated part for OpenTTD 13.0 {{ottdp|13.0|no}}

In addition you need to set register 100 as additional result:
* <code style="color:darkgreen">STORE_TEMP(CB_FLAG_MORE_SPRITES | recolouring, 0x100)</code> if there are more sprites to draw.
* <code style="color:darkgreen">STORE_TEMP(recolouring, 0x100)</code> if there are no more sprites to draw.
"recolouring" can be:
* <code>PALETTE_USE_DEFAULT</code> to use the default vehicle recolouring.
* <code>PALETTE_IDENTITY</code> to use no recolouring
* Any other default or custom recolouring sprite.

===Sound events===

{| class="wikitable sortable"
! 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
|}

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

Note that while vehicle ID affects the order in which vehicles appear in the purchase menu, this can be overridden using the [[NML:Sorting vehicles in the purchase list|sort block]].

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

NML:Vehicles

2026-06-05T08:00:02Z

Rito12: /* Variables that require an argument */ add an notice that tile_has_roadtype_badge and tile_has_tramtype_badge are the same under the hood.

{{NMLNavPropVarCB}}
==Properties common to all vehicle types==

{| class="wikitable sortable"
! 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. If set to 0, cargo does not age. Repeated tests have shown that the gameplay effects of this property often do not match the expectations of grf authors. Explaining why requires a detailed understanding of the OpenTTD cargo aging algorithm, and how that works with e.g. different map sizes, vehicle speeds, multi-leg feeder systems, etc. TL;DR avoid using this property unless you absolutely understand the effect it will have.
|-
| <code style="color:green">variant_group</code>
| Vehicle ID or alternatively the vehicle numeric ID (0 ... 65535)
| no
|
{{ottd|13}} This property supports grouping vehicles in the purchase menu (also the autoreplace menu). The property value is the ID of another vehicle in the same GRF which will act as the parent for vehicles in the group.

Groups can also be nested (this is experimental as of December 2022 and may change with testing).

See also vehicle extra_flags which can influence the behaviour of vehicles in variant groups.

See also https://github.com/OpenTTD/OpenTTD/pull/10220
|-
| <code style="color:green">extra_flags</code>
| bitmask(VEHICLE_FLAG_XXX, ...)
| no
| {{ottd|13}}
;VEHICLE_FLAG_DISABLE_NEW_VEHICLE_MESSAGE
: Disable "New Vehicle" news message for this engine
;VEHICLE_FLAG_DISABLE_EXCLUSIVE_PREVIEW
: Disable "Exclusive Preview" for this engine
;VEHICLE_FLAG_SYNC_VARIANT_EXCLUSIVE_PREVIEW
: Variants - Include this variant when primary engine has "Exclusive Preview"
;VEHICLE_FLAG_SYNC_VARIANT_RELIABILITY
: Variants - (Attempt to) Synchronize reliability the primary engine.
|-
| <code style="color:green">badges</code>
| Array of badge labels from the [[NML:Badgetable|badgetable]].
| yes
| Since {{ottd|15.0}}
|}

===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. The length of each phase and the starting, peak, and final reliabilities are randomized for each engine when starting a new game. Also note that phase 2 (the vehicle's peak performance) is actually about 8 years shorter than the <code style="color:darkgreen">model_life</code> parameter.

{| 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 + (0 to 15 months)
| stays constant at peak, 75-100%
|-
| 3
| 10 to 20.6 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.

==Train properties==

{| class="wikitable sortable"
! 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). See also curve_speed_mod property.
;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. {{ottdp|13|no|no}} this flag is no longer required, flip is always allowed, except for multi-header or articulated vehicles which cannot be flipped. For vehicles shorter than 8/8, see [[Action0/Vehicles/Trains#cite_note-6|this note about sprite offsets]]
;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
;TRAIN_FLAG_SPRITE_STACK
:{{ottdp|1.7|no|ottdrev=r27668}} Enable [[NML:Vehicles#Composing_vehicles_from_multiple_sprites|composition from multiple sprites]].
|-
| <code style="color:green">extra_flags</code>
| bitmask(VEHICLE_FLAG_XXX, ...)
| yes
| {{ottd|16}}
;VEHICLE_FLAG_TRAIN_HAS_CAB
: Train wagon has a cab and can lead a train when driving backwards, without any speed reduction.
Additionally, trains have the extra flags common to all vehicle types, described above.
|-
| <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>
|{{ottd|15.0.0}} array of items from railtypetable {{ottd|<15.0.0}} 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. It also sets the corresponding sound effect of the engine, and if visual_effect_and_powered is not set, the visual effect as well.
;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) * 9.8 * weight (in tons), with 9.8 being an approximation of the acceleration of gravity (9.81 m/s).
|-
| <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
|
There are two methods to set the visual effect of a vehicle:
* <code style="color:green">visual_effect_and_powered</code>: Easy method for simple effects.
* <code style="color:green">effect_spawn_model_and_powered</code> + callback <code style="color:green">create_effect</code>: {{ottdp|1.5|no|ottdrev=r26747}} Harder to use, but also more powerful.
For each vehicle you have to decide for the method. You cannot use them both for the same vehicle 'item'.

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">effect_spawn_model_and_powered</code>
| <code style="color:green">EFFECT_SPAWN_MODEL_XXX</code> or <code style="color:green">EFFECT_SPAWN_MODEL_XXX <nowiki>|</nowiki> ENABLE_WAGON_POWER</code>
| yes
|
There are two methods to set the visual effect of a vehicle:
* <code style="color:green">visual_effect_and_powered</code>: Easy method for simple effects.
* <code style="color:green">effect_spawn_model_and_powered</code> + callback <code style="color:green">create_effect</code>: {{ottdp|1.5|no|ottdrev=r26747}} Harder to use, but also more powerful.
For each vehicle you have to decide for the method. You cannot use them both for the same vehicle 'item'.

{{ottdp|1.5|no|ottdrev=r26747}} Set the spawning model of visual effects for the vehicle, that is when the vehicle emits visual effects.
The visual appearance itself is defined by the callback 'create_effect'.

;EFFECT_SPAWN_MODEL_NONE
: Do not spawn any effects.
;EFFECT_SPAWN_MODEL_STEAM
: Gradually less effects when approaching max speed.
;EFFECT_SPAWN_MODEL_DIESEL
: Effect proportional to acceleration, no effect when idling at top speed.
;EFFECT_SPAWN_MODEL_ELECTRIC
: Random effect, gradually less likely when approaching max speed.
|-
| <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>]]
|-
| <code style="color:green">curve_speed_mod</code>
| -128 ... 127.996 (float)
| yes
| {{nml|0.7}} {{ottd|12.0}} Maximum curve speed modifier.

The modifier is applied after the normal curve speed calculation is done using the formula max_curve_speed * (1 + curve_speed_mod). This means that the default property value of 0 is equivalent to no change. Negative values are supported, but the resulting vehicle curve speed is clamped at 2 mph-ish to make sure vehicles don't become permanently stuck.

If different vehicles in a train have different curve speed modifiers, the lowest value wins.

See also TRAIN_FLAG_TILT, which is an older and less flexible way of managing vehicle curve speed.
|}

==Road vehicle properties==

{| class="wikitable sortable"
! property
! value range
! available for articulated vehicle
! comment
|-
| sprite_id
| SPRITE_ID_NEW_ROADVEH
| yes
| Set this property to enable new graphics
|-
| speed
| 0 ... 511km/h (float, speed units)
| no
|
|-
| road_type ''or'' tram_type
| item from [[NML:Railtypetable-Roadtypetable-Tramtypetable|roadtypetable]] or [[NML:Railtypetable-Roadtypetable-Tramtypetable|tramtypetable]]
| must be the same as front
| Only ''one'' of these properties may be set.
If <code style="color:green">tram_type</code> is set, <code style="color:green">ROADVEH_FLAG_TRAM</code> must also be set for the vehicle in <code style="color:green">misc_flags</code>.

If not set, road vehicles will default to ROAD and tram vehicles will default to RAIL (this does not overlap with railtype RAIL).
|-
| 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
;ROADVEH_FLAG_SPRITE_STACK
:{{ottdp|1.7|no|ottdrev=r27668}} Enable [[NML:Vehicles#Composing_vehicles_from_multiple_sprites|composition from multiple sprites]].
|-
| 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]].
 {{ottdp|1.6|no|ottdrev=r27507}} Since OpenTTD r27507 also <code style="color:green">sound("sound.wav")</code> and <code style="color:green">import_sound(grfid, number)</code> are valid here.
|-
| visual_effect
| visual_effect( VISUAL_EFFECT_XXX, offset)
| yes
|
There are two methods to set the visual effect of a vehicle:
* <code style="color:green">visual_effect</code>: Easy method for simple effects.
* <code style="color:green">effect_spawn_model</code> + callback <code style="color:green">create_effect</code>: {{ottdp|1.5|no|ottdrev=r26747}} Harder to use, but also more powerful.
For each vehicle you have to decide for the method. You cannot use them both for the same vehicle 'item'.

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">effect_spawn_model</code>
| <code style="color:green">EFFECT_SPAWN_MODEL_XXX</code>
| yes
|
There are two methods to set the visual effect of a vehicle:
* <code style="color:green">visual_effect</code>: Easy method for simple effects.
* <code style="color:green">effect_spawn_model</code> + callback <code style="color:green">create_effect</code>: {{ottdp|1.5|no|ottdrev=r26747}} Harder to use, but also more powerful.
For each vehicle you have to decide for the method. You cannot use them both for the same vehicle 'item'.

{{ottdp|1.5|no|ottdrev=r26747}} Set the spawning model of visual effects for the vehicle, that is when the vehicle emits visual effects.
The visual appearance itself is defined by the callback 'create_effect'.

;EFFECT_SPAWN_MODEL_NONE
: Do not spawn any effects.
;EFFECT_SPAWN_MODEL_STEAM
: Gradually less effects when approaching max speed.
;EFFECT_SPAWN_MODEL_DIESEL
: Effect proportional to acceleration, no effect when idling at top speed.
;EFFECT_SPAWN_MODEL_ELECTRIC
: Random effect, gradually less likely when approaching max speed.
|-
| 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="wikitable sortable"
! 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)
| {{ottd|14}}{{nml|7.5}} 0 .. 32767 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
;SHIP_FLAG_SPRITE_STACK
:{{ottdp|1.7|no|ottdrev=r27668}} Enable [[NML:Vehicles#Composing_vehicles_from_multiple_sprites|composition from multiple sprites]].
|-
| 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]].
 {{ottdp|1.6|no|ottdrev=r27507}} Since OpenTTD r27507 also <code style="color:green">sound("sound.wav")</code> and <code style="color:green">import_sound(grfid, number)</code> are valid here.
|-
| 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)
|
There are two methods to set the visual effect of a vehicle:
* <code style="color:green">visual_effect</code>: Easy method for simple effects.
* <code style="color:green">effect_spawn_model</code> + callback <code style="color:green">create_effect</code>: {{ottdp|1.5|no|ottdrev=r26747}} Harder to use, but also more powerful.
For each vehicle you have to decide for the method. You cannot use them both for the same vehicle 'item'.

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.
|-
| <code style="color:green">effect_spawn_model</code>
| <code style="color:green">EFFECT_SPAWN_MODEL_XXX</code>
|
There are two methods to set the visual effect of a vehicle:
* <code style="color:green">visual_effect</code>: Easy method for simple effects.
* <code style="color:green">effect_spawn_model</code> + callback <code style="color:green">create_effect</code>: {{ottdp|1.5|no|ottdrev=r26747}} Harder to use, but also more powerful.
For each vehicle you have to decide for the method. You cannot use them both for the same vehicle 'item'.

{{ottdp|1.5|no|ottdrev=r26747}} Set the spawning model of visual effects for the vehicle, that is when the vehicle emits visual effects.
The visual appearance itself is defined by the callback 'create_effect'.

;EFFECT_SPAWN_MODEL_NONE
: Do not spawn any effects.
;EFFECT_SPAWN_MODEL_STEAM
: Gradually less effects when approaching max speed.
;EFFECT_SPAWN_MODEL_DIESEL
: Effect proportional to acceleration, no effect when idling at top speed.
;EFFECT_SPAWN_MODEL_ELECTRIC
: Random effect, gradually less likely when approaching max speed.
|-
| acceleration
| 1 ... 255
| {{ottd|14}} Acceleration in units of ~0.5 km/h per tick. 1 is the default and is the acceleration of default ships.
|}

==Aircraft properties==

{| class="wikitable sortable"
! 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
;AIRCRAFT_FLAG_SPRITE_STACK
:{{ottdp|1.7|no|ottdrev=r27668}} Enable [[NML:Vehicles#Composing_vehicles_from_multiple_sprites|composition from multiple sprites]]. This also affects custom rotor sprites.
|-
| 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
| {{ottd|1.3.1}} 0 ... 255 {{ottd|<1.3.1}} 0 ... 19
| {{ottd|1.3.1}} Default aircraft use values in the range 18 to 50 (= 6.75 to 18.75 mph/tick = 499.5 to 1387.5 mph/day), which is generally considered quite fast. 
{{ottd|<1.3.1}} In older OpenTTD, aircraft provided by NewGRF accelerate 166% faster than intended.
|-
| 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]].
 {{ottdp|1.6|no|ottdrev=r27507}} Since OpenTTD r27507 also <code style="color:green">sound("sound.wav")</code> and <code style="color:green">import_sound(grfid, number)</code> are valid here.
|}

==Vehicle variables==

Below an overview of all vehicle-specific variables. Note 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, similarly checking current_roadtype for a tram won't return a useful result.

===Variables without parameter===

{| class="wikitable sortable"
! 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.
|-
| position_in_articulated_veh
| 0 ... 255
| No
| {{nml|0.3}} {{ottdp|1.4|no|ottdrev=r26157}} The position of the current articulated vehicle from the start of the vehicle. The first will get value 0, the second one gets value 1, etc.
|-
| position_in_articulated_veh_from_end
| 0 ... 255
| No
| {{nml|0.3}} {{ottdp|1.4|no|ottdrev=r26157}} The position of the current articulated vehicle from the end of the vehicle. The last will get value 0, the second last one gets value 1, etc.
|-
| cargo_classes_in_consist
| Bitmask of CC_XXX
| No
|
[[NML:Cargos#Cargo classes|cargo classes]]
|-
| most_common_cargo_type
|
[[NML:Cargos#Cargo properties|Cargo label]]
| No
| The most common cargo type in the consist. Prior to nml r2320 this was known as most_common_refit, and didn't work, and was also incorrectly documented :)
|-
| most_common_cargo_subtype
| 0 ... 255
| No
| The most common cargo subtype for most_common_cargo_type
|-
| 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
|-
| flight_state
| 0 ... 28
| No
| {{nml|0.8.1}} Only for aircrafts.
|-
| 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 ... 0xFFFFFF
| Yes, always 0
| Is increased every time the vehicle moves a single step on the map. Useful for driving animations.
For that, make the animation use a number of frames, which is a power of two, i.e. 2, 4, 8, 16, 32, ... frames, and then use the lower n bits of motion_counter.
|-
| 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_flipped
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the sprite is reversed via flip-vehicle-in-depot (trains only), or if it's the rear-most part of a dual-head engine.
|-
| vehicle_is_reversed
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle has reversed an odd number of times
|-
| train_is_driving_backwards
| [0 <nowiki>|</nowiki> 1]
| No
| {{ottd|16}} Value is 1 if the train is driving backwards (trains only)
|-
| built_during_preview
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle was built during the exclusive preview stage
|-
| current_railtype
| Entry from railtype translation table or 0xFF
| No
| This variable is useless due to equivalent railtypes, use tile_xxx_railtype instead. If you do use this variable, it will not work as expected 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.
|-
| current_roadtype
| Entry from current_roadtype translation table or 0xFF
| No
| {{nml|0.5}} {{ottdp|1.10|no}} This variable is useless due to equivalent roadtypes, use tile_xxx_roadtype instead. Don't use this variable unless you've defined a roadtype translation table. If the road vehicle is running on a roadtype that is not listed in your roadtype translation table this variable will contain 0xFF. Checking this for a tram is not supported and will not return a useful result.
|-
| current_tramtype
| Entry from tramtype translation table or 0xFF
| No
| {{nml|0.5}} {{ottdp|1.10|no}} This variable is useless due to equivalent tramtypes, use tile_xxx_tramtype instead. Don't use this variable unless you've defined a tramtype translation table. If the road vehicle is running on a tramtype that is not listed in your tramtype translation table this variable will contain 0xFF. Checking this for a road vehicle that is not a tram is not supported and will not return a useful result.
|-
| tile_has_catenary
| [0 <nowiki>|</nowiki> 1]
| No
| {{ottdp|1.11|no}} True if the track_type on the tile has catenary. This is a little simplified as it is intended for sprite changes (e.g. raise/lower pantograph) and only checks for "some catenary". To distinguish different types of electric track, AC and DC voltages etc, ... use tile_xxx_railtype/tile_xxx_roadtype/tile_xxx_tramtype instead.
|-
| 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 or a name defined in item block
| 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
|-
| vehicle_is_unloading
| [0 <nowiki>|</nowiki> 1]
| No
| {{ottdp|1.5|2.5|ottdrev=r26430}} Value is 1 if the vehicle is unloading at a station and has not yet started loading new cargo.
|}

===Variables that require an argument===

{| class="wikitable sortable"
! 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">Argument 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_y_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_z_offset
| 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.
|-
| tile_supports_railtype tile_supports_roadtype tile_supports_tramtype
| Entry from rail/road/tram translation table
| [0 <nowiki>|</nowiki> 1]
| No
| {{ottdp|1.11|no}} Vehicles of the track_type label used as parameter are compatible with the rail/road/tram track_type on the current tile. Example: <code style="color:darkgreen">tile_supports_railtype(ELRL)</code>
|-
| tile_powers_railtype tile_powers_roadtype tile_powers_tramtype
| Entry from rail/road/tram translation table
| [0 <nowiki>|</nowiki> 1]
| No
| {{ottdp|1.11|no}} Vehicles of the track_type label used as parameter are powered on the rail/road/tram track_type on the current tile. Example: <code style="color:darkgreen">tile_powers_railtype(ELRL)</code>
|-
| tile_is_railtype tile_is_roadtype tile_is_tramtype
| Entry from rail/road/tram translation table
| [0 <nowiki>|</nowiki> 1]
| No
| {{ottdp|1.11|no}} The track_type label used as parameter is identical or equivalent (listed as alternate label in rail-/road-/tram-type property 1D) to the rail/road/tram track_type on the current tile. Example: <code style="color:darkgreen">tile_is_railtype(ELRL)</code>
|-
| has_badge
| Label from the [[NML:Badgetable|badgetable]].
| [0 <nowiki>|</nowiki> 1]
| yes
| {{ottd|15.0}} Check if the vehicle has that specific badge attached.
|-
| count_has_badge
| Label from the [[NML:Badgetable|badgetable]].
| 0..255
| no
| {{ottd|15.0}} The number of vehicles in the current consist that have that specific badge attached.
|-
| tile_has_railtype_badge
| Label from the [[NML:Badgetable|badgetable]].
| [0 <nowiki>|</nowiki> 1]
| no
| {{ottd|15.0}} Check if the rail type of the current tile occupied by the train has that specific badge attached. '''Trains only'''
|-
| tile_has_roadtype_badge
| Label from the [[NML:Badgetable|badgetable]].
| [0 <nowiki>|</nowiki> 1]
| no
| {{ottd|15.0}} Check if the road type of the current tile occupied by the road vehicle has that specific badge attached. '''RVs only''', although if used on tram works the same way as <code>tile_has_tramtype_badge</code>.
|-
| tile_has_tramtype_badge
| Label from the [[NML:Badgetable|badgetable]].
| [0 <nowiki>|</nowiki> 1]
| no
| {{ottd|15.0}} Check if the tram track type of the current tile occupied by the tram has that specific badge attached. '''Trams only'''
|}
<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="wikitable sortable"
! 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
| NOTE: As of OpenTTD 13, this feature is considered deprecated for most uses. Use variants instead. 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 to select specific sprites for the vehicle's current cargo subtype.
|-
| 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">getbits(extra_callback_info1, 0, 8)</code> 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">getbits(extra_callback_info1, 0, 8)</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.

The vehicle ID for the articulated part must be in the range 0 .. 16383.

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. If a wagon is inserted in the middle, all wagons are removed and attached one-by-one in the new order. This callback has to be defined at the engine. The scopes behave different than usual though:
* <code style="color:darkgreen">SELF</code> refers to the wagon being attached. (despite the callback being defined at the engine)
* <code style="color:darkgreen">PARENT</code> refers to the consist of the engine up to the wagon before <code style="color:darkgreen">SELF</code>, i.e. not (yet) including the wagon being attached.
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.
* <code style="color:darkgreen">getbits(extra_callback_info1, 0, 8)</code>: The new cargo type.
* <code style="color:darkgreen">getbits(extra_callback_info1, 8, 8)</code>: The new cargo subtype (see <code style="color:darkgreen">cargo_subtype_text</code>-callback).
* <code style="color:darkgreen">getbits(extra_callback_info1, 16, 16)</code>: 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.
|-
| create_effect
| {{ottdp|1.5|no|ottdrev=r26747}} Trains, Road Vehicles, Ships
| No
| 0 .. 3 for number of effects. Optionally add <code style="color:darkgreen">CB_RESULT_CREATE_EFFECT_CENTER</code> and/or <code style="color:darkgreen">CB_RESULT_CREATE_EFFECT_NO_ROTATION</code>
| Called when a effect spawning model is defined via <code style="color:darkgreen">effect_spawn_model</code> resp. <code style="color:darkgreen">effect_spawn_model_and_powered</code>.

The result specifies how many effects shall be created.
The position and appearance of the individual effects is returned via registers 0x100 to 0x103:
<pre style="color:blue">
switch (FEAT_XXX, SELF, switch_name, [
STORE_TEMP(create_effect(EFFECT_SPRITE_XXX, 8, -3, 10), 0x100), // first effect,
STORE_TEMP(create_effect(EFFECT_SPRITE_YYY, 8, 3, 10), 0x101) // second effect, ...
]) {
return 2; // number of effects
}
</pre>
The register values are created using the <code style="color:darkgreen">create_effect(''effect_sprite'', ''l_x_offset'', ''t_y_offset'', ''z_offset'')</code> function:
* ''effect_sprite'': Sprite for the effect. One of <code style="color:darkgreen">EFFECT_SPRITE_</code>[<code style="color:darkgreen">NONE</code>|<code style="color:darkgreen">STEAM</code>|<code style="color:darkgreen">DIESEL</code>|<code style="color:darkgreen">ELECTRIC</code>|<code style="color:darkgreen">AIRCRAFT_BREAKDOWN_SMOKE</code>].
* ''l_x_offset'': Longitudinal or X position of the effect, depending on callback result <code style="color:darkgreen">CB_RESULT_CREATE_EFFECT_NO_ROTATION</code>.
* ''t_y_offset'': Transversal or Y position of the effect, depending on callback result <code style="color:darkgreen">CB_RESULT_CREATE_EFFECT_NO_ROTATION</code>.
* ''z_offset'': Z position of the effect.

Additional to the number of effects, the callback result may specify these flags:
;<code style="color:darkgreen">CB_RESULT_CREATE_EFFECT_CENTER</code>
:(Train and road vehicle only) If set, position effect relative to vehicle center instead of relative to vehicle sprite. (behaves the same for vehicles with length 8/8)
;<code style="color:darkgreen">CB_RESULT_CREATE_EFFECT_NO_ROTATION</code>
*If not set, the parameters to <code style="color:darkgreen">effect_sprite</code> describe longitudinal/transversal positions, which are rotate wrt. vehicle orientation.
*If set, the parameters to <code style="color:darkgreen">effect_sprite</code> describe X and Y positions, which are not automatically rotated.
|-
| reverse_build_probability
| {{nml|0.7.5}} {{ottd|14.0}} Trains
| No
| 0
| Probability of reversing rail vehicle, i.e. facing forward or backward, when purchased.
|-
| refit
| {{ottd|15.0}} All vehicle types
| Callback runs once, in purchase scope only
|
* 0 Don't change refittability (i.e. use whatever the evaluation of the various refittability vehicle props has determined).
* 1 Allow cargo type as a refit.
* 2 Disallow cargo type as a refit.
|

The custom refit callback allows overriding the refittablity of each cargo as defined by the standard vehicle properties. It will be called for each defined cargo type once after the game has loaded all NewGRF files. The callback is run in purchase list scope, i.e. for cargotype FF. No variables of an actual vehicle are available. Information about the cargo type the callback is called for is available in variables 10 and 18:
'''Note:''' As this callback is not re-evaluated after game initialization, using any dynamic variables like e.g. game date will lead to undefined and faulty behaviour.

This callback is available starting with {{ottdp|15|no|ottdrev=gd2496b6ec4}} OpenTTD 15.

See https://newgrf-specs.tt-wiki.net/wiki/Callbacks#Custom_refit_.28163.29
|}

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

{| class="wikitable sortable"
! 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
|
|-
| effect_spawn_model_and_powered
| Trains
| No
|
|-
| effect_spawn_model
| 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
|
|-
| curve_speed_mod
| {{nml|0.7}} {{ottd|12.0}} Trains
| No
|
|-
| name
| {{nml|0.7.2}} {{ottd|14.0}} All
| Yes
| Can be used to display vehicle name differently depending on context (purchase menu, depot, nested variant depth etc). <code style="color:darkgreen">extra_callback_info1</code> contains detailed information about context - please see https://newgrf-specs.tt-wiki.net/wiki/Callbacks#Engine_name_.28161.29
|}

===Sprites in GUI===
{{ottdp|1.2|no|ottdrev=r23080}} Since OpenTTD r23080 you can use variable <code style="color:darkgreen">getbits(extra_callback_info1, 0, 8)</code> to display different sprites in the GUI and on the map. Currently these cases are available:
{| |-
! getbits(extra_callback_info1, 0, 8) !! 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 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.

===Composing vehicles from multiple sprites===
{{ottdp|1.7|no|ottdrev=r27668}} Since OpenTTD r27668 you can draw vehicles by drawing multiple sprites on top of each other.
* The sprites can use different recolouring.
* When using 32bpp sprites, the sprites can use the alpha channel to blend with the other sprites. In particular you can use this to alpha-blend company colours over other sprites.

To enable this, you need to set <code style="color:darkgreen">XXX_FLAG_SPRITE_STACK</code> in the <code style="color:darkgreen">misc_flags</code> property.

When enabled, sprites are resolved multiple times while incrementing an iteration number, that can be read via
<code style="color:darkgreen">getbits(extra_callback_info1, 8, 8)</code>

For OpenTTD 1.7 to 12.0, this is limited to at most 4 sprites per articulated part.

Increased to 8 sprites per articulated part for OpenTTD 13.0 {{ottdp|13.0|no}}

In addition you need to set register 100 as additional result:
* <code style="color:darkgreen">STORE_TEMP(CB_FLAG_MORE_SPRITES | recolouring, 0x100)</code> if there are more sprites to draw.
* <code style="color:darkgreen">STORE_TEMP(recolouring, 0x100)</code> if there are no more sprites to draw.
"recolouring" can be:
* <code>PALETTE_USE_DEFAULT</code> to use the default vehicle recolouring.
* <code>PALETTE_IDENTITY</code> to use no recolouring
* Any other default or custom recolouring sprite.

===Sound events===

{| class="wikitable sortable"
! 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
|}

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

Note that while vehicle ID affects the order in which vehicles appear in the purchase menu, this can be overridden using the [[NML:Sorting vehicles in the purchase list|sort block]].

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

NML:Vehicles

2026-06-05T07:56:22Z

Rito12: /* Variables that require an argument */ Add variable 0x65.

{{NMLNavPropVarCB}}
==Properties common to all vehicle types==

{| class="wikitable sortable"
! 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. If set to 0, cargo does not age. Repeated tests have shown that the gameplay effects of this property often do not match the expectations of grf authors. Explaining why requires a detailed understanding of the OpenTTD cargo aging algorithm, and how that works with e.g. different map sizes, vehicle speeds, multi-leg feeder systems, etc. TL;DR avoid using this property unless you absolutely understand the effect it will have.
|-
| <code style="color:green">variant_group</code>
| Vehicle ID or alternatively the vehicle numeric ID (0 ... 65535)
| no
|
{{ottd|13}} This property supports grouping vehicles in the purchase menu (also the autoreplace menu). The property value is the ID of another vehicle in the same GRF which will act as the parent for vehicles in the group.

Groups can also be nested (this is experimental as of December 2022 and may change with testing).

See also vehicle extra_flags which can influence the behaviour of vehicles in variant groups.

See also https://github.com/OpenTTD/OpenTTD/pull/10220
|-
| <code style="color:green">extra_flags</code>
| bitmask(VEHICLE_FLAG_XXX, ...)
| no
| {{ottd|13}}
;VEHICLE_FLAG_DISABLE_NEW_VEHICLE_MESSAGE
: Disable "New Vehicle" news message for this engine
;VEHICLE_FLAG_DISABLE_EXCLUSIVE_PREVIEW
: Disable "Exclusive Preview" for this engine
;VEHICLE_FLAG_SYNC_VARIANT_EXCLUSIVE_PREVIEW
: Variants - Include this variant when primary engine has "Exclusive Preview"
;VEHICLE_FLAG_SYNC_VARIANT_RELIABILITY
: Variants - (Attempt to) Synchronize reliability the primary engine.
|-
| <code style="color:green">badges</code>
| Array of badge labels from the [[NML:Badgetable|badgetable]].
| yes
| Since {{ottd|15.0}}
|}

===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. The length of each phase and the starting, peak, and final reliabilities are randomized for each engine when starting a new game. Also note that phase 2 (the vehicle's peak performance) is actually about 8 years shorter than the <code style="color:darkgreen">model_life</code> parameter.

{| 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 + (0 to 15 months)
| stays constant at peak, 75-100%
|-
| 3
| 10 to 20.6 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.

==Train properties==

{| class="wikitable sortable"
! 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). See also curve_speed_mod property.
;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. {{ottdp|13|no|no}} this flag is no longer required, flip is always allowed, except for multi-header or articulated vehicles which cannot be flipped. For vehicles shorter than 8/8, see [[Action0/Vehicles/Trains#cite_note-6|this note about sprite offsets]]
;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
;TRAIN_FLAG_SPRITE_STACK
:{{ottdp|1.7|no|ottdrev=r27668}} Enable [[NML:Vehicles#Composing_vehicles_from_multiple_sprites|composition from multiple sprites]].
|-
| <code style="color:green">extra_flags</code>
| bitmask(VEHICLE_FLAG_XXX, ...)
| yes
| {{ottd|16}}
;VEHICLE_FLAG_TRAIN_HAS_CAB
: Train wagon has a cab and can lead a train when driving backwards, without any speed reduction.
Additionally, trains have the extra flags common to all vehicle types, described above.
|-
| <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>
|{{ottd|15.0.0}} array of items from railtypetable {{ottd|<15.0.0}} 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. It also sets the corresponding sound effect of the engine, and if visual_effect_and_powered is not set, the visual effect as well.
;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) * 9.8 * weight (in tons), with 9.8 being an approximation of the acceleration of gravity (9.81 m/s).
|-
| <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
|
There are two methods to set the visual effect of a vehicle:
* <code style="color:green">visual_effect_and_powered</code>: Easy method for simple effects.
* <code style="color:green">effect_spawn_model_and_powered</code> + callback <code style="color:green">create_effect</code>: {{ottdp|1.5|no|ottdrev=r26747}} Harder to use, but also more powerful.
For each vehicle you have to decide for the method. You cannot use them both for the same vehicle 'item'.

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">effect_spawn_model_and_powered</code>
| <code style="color:green">EFFECT_SPAWN_MODEL_XXX</code> or <code style="color:green">EFFECT_SPAWN_MODEL_XXX <nowiki>|</nowiki> ENABLE_WAGON_POWER</code>
| yes
|
There are two methods to set the visual effect of a vehicle:
* <code style="color:green">visual_effect_and_powered</code>: Easy method for simple effects.
* <code style="color:green">effect_spawn_model_and_powered</code> + callback <code style="color:green">create_effect</code>: {{ottdp|1.5|no|ottdrev=r26747}} Harder to use, but also more powerful.
For each vehicle you have to decide for the method. You cannot use them both for the same vehicle 'item'.

{{ottdp|1.5|no|ottdrev=r26747}} Set the spawning model of visual effects for the vehicle, that is when the vehicle emits visual effects.
The visual appearance itself is defined by the callback 'create_effect'.

;EFFECT_SPAWN_MODEL_NONE
: Do not spawn any effects.
;EFFECT_SPAWN_MODEL_STEAM
: Gradually less effects when approaching max speed.
;EFFECT_SPAWN_MODEL_DIESEL
: Effect proportional to acceleration, no effect when idling at top speed.
;EFFECT_SPAWN_MODEL_ELECTRIC
: Random effect, gradually less likely when approaching max speed.
|-
| <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>]]
|-
| <code style="color:green">curve_speed_mod</code>
| -128 ... 127.996 (float)
| yes
| {{nml|0.7}} {{ottd|12.0}} Maximum curve speed modifier.

The modifier is applied after the normal curve speed calculation is done using the formula max_curve_speed * (1 + curve_speed_mod). This means that the default property value of 0 is equivalent to no change. Negative values are supported, but the resulting vehicle curve speed is clamped at 2 mph-ish to make sure vehicles don't become permanently stuck.

If different vehicles in a train have different curve speed modifiers, the lowest value wins.

See also TRAIN_FLAG_TILT, which is an older and less flexible way of managing vehicle curve speed.
|}

==Road vehicle properties==

{| class="wikitable sortable"
! property
! value range
! available for articulated vehicle
! comment
|-
| sprite_id
| SPRITE_ID_NEW_ROADVEH
| yes
| Set this property to enable new graphics
|-
| speed
| 0 ... 511km/h (float, speed units)
| no
|
|-
| road_type ''or'' tram_type
| item from [[NML:Railtypetable-Roadtypetable-Tramtypetable|roadtypetable]] or [[NML:Railtypetable-Roadtypetable-Tramtypetable|tramtypetable]]
| must be the same as front
| Only ''one'' of these properties may be set.
If <code style="color:green">tram_type</code> is set, <code style="color:green">ROADVEH_FLAG_TRAM</code> must also be set for the vehicle in <code style="color:green">misc_flags</code>.

If not set, road vehicles will default to ROAD and tram vehicles will default to RAIL (this does not overlap with railtype RAIL).
|-
| 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
;ROADVEH_FLAG_SPRITE_STACK
:{{ottdp|1.7|no|ottdrev=r27668}} Enable [[NML:Vehicles#Composing_vehicles_from_multiple_sprites|composition from multiple sprites]].
|-
| 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]].
 {{ottdp|1.6|no|ottdrev=r27507}} Since OpenTTD r27507 also <code style="color:green">sound("sound.wav")</code> and <code style="color:green">import_sound(grfid, number)</code> are valid here.
|-
| visual_effect
| visual_effect( VISUAL_EFFECT_XXX, offset)
| yes
|
There are two methods to set the visual effect of a vehicle:
* <code style="color:green">visual_effect</code>: Easy method for simple effects.
* <code style="color:green">effect_spawn_model</code> + callback <code style="color:green">create_effect</code>: {{ottdp|1.5|no|ottdrev=r26747}} Harder to use, but also more powerful.
For each vehicle you have to decide for the method. You cannot use them both for the same vehicle 'item'.

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">effect_spawn_model</code>
| <code style="color:green">EFFECT_SPAWN_MODEL_XXX</code>
| yes
|
There are two methods to set the visual effect of a vehicle:
* <code style="color:green">visual_effect</code>: Easy method for simple effects.
* <code style="color:green">effect_spawn_model</code> + callback <code style="color:green">create_effect</code>: {{ottdp|1.5|no|ottdrev=r26747}} Harder to use, but also more powerful.
For each vehicle you have to decide for the method. You cannot use them both for the same vehicle 'item'.

{{ottdp|1.5|no|ottdrev=r26747}} Set the spawning model of visual effects for the vehicle, that is when the vehicle emits visual effects.
The visual appearance itself is defined by the callback 'create_effect'.

;EFFECT_SPAWN_MODEL_NONE
: Do not spawn any effects.
;EFFECT_SPAWN_MODEL_STEAM
: Gradually less effects when approaching max speed.
;EFFECT_SPAWN_MODEL_DIESEL
: Effect proportional to acceleration, no effect when idling at top speed.
;EFFECT_SPAWN_MODEL_ELECTRIC
: Random effect, gradually less likely when approaching max speed.
|-
| 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="wikitable sortable"
! 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)
| {{ottd|14}}{{nml|7.5}} 0 .. 32767 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
;SHIP_FLAG_SPRITE_STACK
:{{ottdp|1.7|no|ottdrev=r27668}} Enable [[NML:Vehicles#Composing_vehicles_from_multiple_sprites|composition from multiple sprites]].
|-
| 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]].
 {{ottdp|1.6|no|ottdrev=r27507}} Since OpenTTD r27507 also <code style="color:green">sound("sound.wav")</code> and <code style="color:green">import_sound(grfid, number)</code> are valid here.
|-
| 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)
|
There are two methods to set the visual effect of a vehicle:
* <code style="color:green">visual_effect</code>: Easy method for simple effects.
* <code style="color:green">effect_spawn_model</code> + callback <code style="color:green">create_effect</code>: {{ottdp|1.5|no|ottdrev=r26747}} Harder to use, but also more powerful.
For each vehicle you have to decide for the method. You cannot use them both for the same vehicle 'item'.

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.
|-
| <code style="color:green">effect_spawn_model</code>
| <code style="color:green">EFFECT_SPAWN_MODEL_XXX</code>
|
There are two methods to set the visual effect of a vehicle:
* <code style="color:green">visual_effect</code>: Easy method for simple effects.
* <code style="color:green">effect_spawn_model</code> + callback <code style="color:green">create_effect</code>: {{ottdp|1.5|no|ottdrev=r26747}} Harder to use, but also more powerful.
For each vehicle you have to decide for the method. You cannot use them both for the same vehicle 'item'.

{{ottdp|1.5|no|ottdrev=r26747}} Set the spawning model of visual effects for the vehicle, that is when the vehicle emits visual effects.
The visual appearance itself is defined by the callback 'create_effect'.

;EFFECT_SPAWN_MODEL_NONE
: Do not spawn any effects.
;EFFECT_SPAWN_MODEL_STEAM
: Gradually less effects when approaching max speed.
;EFFECT_SPAWN_MODEL_DIESEL
: Effect proportional to acceleration, no effect when idling at top speed.
;EFFECT_SPAWN_MODEL_ELECTRIC
: Random effect, gradually less likely when approaching max speed.
|-
| acceleration
| 1 ... 255
| {{ottd|14}} Acceleration in units of ~0.5 km/h per tick. 1 is the default and is the acceleration of default ships.
|}

==Aircraft properties==

{| class="wikitable sortable"
! 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
;AIRCRAFT_FLAG_SPRITE_STACK
:{{ottdp|1.7|no|ottdrev=r27668}} Enable [[NML:Vehicles#Composing_vehicles_from_multiple_sprites|composition from multiple sprites]]. This also affects custom rotor sprites.
|-
| 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
| {{ottd|1.3.1}} 0 ... 255 {{ottd|<1.3.1}} 0 ... 19
| {{ottd|1.3.1}} Default aircraft use values in the range 18 to 50 (= 6.75 to 18.75 mph/tick = 499.5 to 1387.5 mph/day), which is generally considered quite fast. 
{{ottd|<1.3.1}} In older OpenTTD, aircraft provided by NewGRF accelerate 166% faster than intended.
|-
| 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]].
 {{ottdp|1.6|no|ottdrev=r27507}} Since OpenTTD r27507 also <code style="color:green">sound("sound.wav")</code> and <code style="color:green">import_sound(grfid, number)</code> are valid here.
|}

==Vehicle variables==

Below an overview of all vehicle-specific variables. Note 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, similarly checking current_roadtype for a tram won't return a useful result.

===Variables without parameter===

{| class="wikitable sortable"
! 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.
|-
| position_in_articulated_veh
| 0 ... 255
| No
| {{nml|0.3}} {{ottdp|1.4|no|ottdrev=r26157}} The position of the current articulated vehicle from the start of the vehicle. The first will get value 0, the second one gets value 1, etc.
|-
| position_in_articulated_veh_from_end
| 0 ... 255
| No
| {{nml|0.3}} {{ottdp|1.4|no|ottdrev=r26157}} The position of the current articulated vehicle from the end of the vehicle. The last will get value 0, the second last one gets value 1, etc.
|-
| cargo_classes_in_consist
| Bitmask of CC_XXX
| No
|
[[NML:Cargos#Cargo classes|cargo classes]]
|-
| most_common_cargo_type
|
[[NML:Cargos#Cargo properties|Cargo label]]
| No
| The most common cargo type in the consist. Prior to nml r2320 this was known as most_common_refit, and didn't work, and was also incorrectly documented :)
|-
| most_common_cargo_subtype
| 0 ... 255
| No
| The most common cargo subtype for most_common_cargo_type
|-
| 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
|-
| flight_state
| 0 ... 28
| No
| {{nml|0.8.1}} Only for aircrafts.
|-
| 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 ... 0xFFFFFF
| Yes, always 0
| Is increased every time the vehicle moves a single step on the map. Useful for driving animations.
For that, make the animation use a number of frames, which is a power of two, i.e. 2, 4, 8, 16, 32, ... frames, and then use the lower n bits of motion_counter.
|-
| 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_flipped
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the sprite is reversed via flip-vehicle-in-depot (trains only), or if it's the rear-most part of a dual-head engine.
|-
| vehicle_is_reversed
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle has reversed an odd number of times
|-
| train_is_driving_backwards
| [0 <nowiki>|</nowiki> 1]
| No
| {{ottd|16}} Value is 1 if the train is driving backwards (trains only)
|-
| built_during_preview
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle was built during the exclusive preview stage
|-
| current_railtype
| Entry from railtype translation table or 0xFF
| No
| This variable is useless due to equivalent railtypes, use tile_xxx_railtype instead. If you do use this variable, it will not work as expected 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.
|-
| current_roadtype
| Entry from current_roadtype translation table or 0xFF
| No
| {{nml|0.5}} {{ottdp|1.10|no}} This variable is useless due to equivalent roadtypes, use tile_xxx_roadtype instead. Don't use this variable unless you've defined a roadtype translation table. If the road vehicle is running on a roadtype that is not listed in your roadtype translation table this variable will contain 0xFF. Checking this for a tram is not supported and will not return a useful result.
|-
| current_tramtype
| Entry from tramtype translation table or 0xFF
| No
| {{nml|0.5}} {{ottdp|1.10|no}} This variable is useless due to equivalent tramtypes, use tile_xxx_tramtype instead. Don't use this variable unless you've defined a tramtype translation table. If the road vehicle is running on a tramtype that is not listed in your tramtype translation table this variable will contain 0xFF. Checking this for a road vehicle that is not a tram is not supported and will not return a useful result.
|-
| tile_has_catenary
| [0 <nowiki>|</nowiki> 1]
| No
| {{ottdp|1.11|no}} True if the track_type on the tile has catenary. This is a little simplified as it is intended for sprite changes (e.g. raise/lower pantograph) and only checks for "some catenary". To distinguish different types of electric track, AC and DC voltages etc, ... use tile_xxx_railtype/tile_xxx_roadtype/tile_xxx_tramtype instead.
|-
| 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 or a name defined in item block
| 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
|-
| vehicle_is_unloading
| [0 <nowiki>|</nowiki> 1]
| No
| {{ottdp|1.5|2.5|ottdrev=r26430}} Value is 1 if the vehicle is unloading at a station and has not yet started loading new cargo.
|}

===Variables that require an argument===

{| class="wikitable sortable"
! 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">Argument 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_y_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_z_offset
| 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.
|-
| tile_supports_railtype tile_supports_roadtype tile_supports_tramtype
| Entry from rail/road/tram translation table
| [0 <nowiki>|</nowiki> 1]
| No
| {{ottdp|1.11|no}} Vehicles of the track_type label used as parameter are compatible with the rail/road/tram track_type on the current tile. Example: <code style="color:darkgreen">tile_supports_railtype(ELRL)</code>
|-
| tile_powers_railtype tile_powers_roadtype tile_powers_tramtype
| Entry from rail/road/tram translation table
| [0 <nowiki>|</nowiki> 1]
| No
| {{ottdp|1.11|no}} Vehicles of the track_type label used as parameter are powered on the rail/road/tram track_type on the current tile. Example: <code style="color:darkgreen">tile_powers_railtype(ELRL)</code>
|-
| tile_is_railtype tile_is_roadtype tile_is_tramtype
| Entry from rail/road/tram translation table
| [0 <nowiki>|</nowiki> 1]
| No
| {{ottdp|1.11|no}} The track_type label used as parameter is identical or equivalent (listed as alternate label in rail-/road-/tram-type property 1D) to the rail/road/tram track_type on the current tile. Example: <code style="color:darkgreen">tile_is_railtype(ELRL)</code>
|-
| has_badge
| Label from the [[NML:Badgetable|badgetable]].
| [0 <nowiki>|</nowiki> 1]
| yes
| {{ottd|15.0}} Check if the vehicle has that specific badge attached.
|-
| count_has_badge
| Label from the [[NML:Badgetable|badgetable]].
| 0..255
| no
| {{ottd|15.0}} The number of vehicles in the current consist that have that specific badge attached.
|-
| tile_has_railtype_badge
| Label from the [[NML:Badgetable|badgetable]].
| [0 <nowiki>|</nowiki> 1]
| no
| {{ottd|15.0}} Check if the rail type of the current tile occupied by the train has that specific badge attached. '''Trains only'''
|-
| tile_has_roadtype_badge
| Label from the [[NML:Badgetable|badgetable]].
| [0 <nowiki>|</nowiki> 1]
| no
| {{ottd|15.0}} Check if the road type of the current tile occupied by the road vehicle has that specific badge attached. '''RVs only'''
|-
| tile_has_tramtype_badge
| Label from the [[NML:Badgetable|badgetable]].
| [0 <nowiki>|</nowiki> 1]
| no
| {{ottd|15.0}} Check if the tram track type of the current tile occupied by the tram has that specific badge attached. '''Trams only'''
|}
<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="wikitable sortable"
! 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
| NOTE: As of OpenTTD 13, this feature is considered deprecated for most uses. Use variants instead. 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 to select specific sprites for the vehicle's current cargo subtype.
|-
| 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">getbits(extra_callback_info1, 0, 8)</code> 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">getbits(extra_callback_info1, 0, 8)</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.

The vehicle ID for the articulated part must be in the range 0 .. 16383.

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. If a wagon is inserted in the middle, all wagons are removed and attached one-by-one in the new order. This callback has to be defined at the engine. The scopes behave different than usual though:
* <code style="color:darkgreen">SELF</code> refers to the wagon being attached. (despite the callback being defined at the engine)
* <code style="color:darkgreen">PARENT</code> refers to the consist of the engine up to the wagon before <code style="color:darkgreen">SELF</code>, i.e. not (yet) including the wagon being attached.
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.
* <code style="color:darkgreen">getbits(extra_callback_info1, 0, 8)</code>: The new cargo type.
* <code style="color:darkgreen">getbits(extra_callback_info1, 8, 8)</code>: The new cargo subtype (see <code style="color:darkgreen">cargo_subtype_text</code>-callback).
* <code style="color:darkgreen">getbits(extra_callback_info1, 16, 16)</code>: 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.
|-
| create_effect
| {{ottdp|1.5|no|ottdrev=r26747}} Trains, Road Vehicles, Ships
| No
| 0 .. 3 for number of effects. Optionally add <code style="color:darkgreen">CB_RESULT_CREATE_EFFECT_CENTER</code> and/or <code style="color:darkgreen">CB_RESULT_CREATE_EFFECT_NO_ROTATION</code>
| Called when a effect spawning model is defined via <code style="color:darkgreen">effect_spawn_model</code> resp. <code style="color:darkgreen">effect_spawn_model_and_powered</code>.

The result specifies how many effects shall be created.
The position and appearance of the individual effects is returned via registers 0x100 to 0x103:
<pre style="color:blue">
switch (FEAT_XXX, SELF, switch_name, [
STORE_TEMP(create_effect(EFFECT_SPRITE_XXX, 8, -3, 10), 0x100), // first effect,
STORE_TEMP(create_effect(EFFECT_SPRITE_YYY, 8, 3, 10), 0x101) // second effect, ...
]) {
return 2; // number of effects
}
</pre>
The register values are created using the <code style="color:darkgreen">create_effect(''effect_sprite'', ''l_x_offset'', ''t_y_offset'', ''z_offset'')</code> function:
* ''effect_sprite'': Sprite for the effect. One of <code style="color:darkgreen">EFFECT_SPRITE_</code>[<code style="color:darkgreen">NONE</code>|<code style="color:darkgreen">STEAM</code>|<code style="color:darkgreen">DIESEL</code>|<code style="color:darkgreen">ELECTRIC</code>|<code style="color:darkgreen">AIRCRAFT_BREAKDOWN_SMOKE</code>].
* ''l_x_offset'': Longitudinal or X position of the effect, depending on callback result <code style="color:darkgreen">CB_RESULT_CREATE_EFFECT_NO_ROTATION</code>.
* ''t_y_offset'': Transversal or Y position of the effect, depending on callback result <code style="color:darkgreen">CB_RESULT_CREATE_EFFECT_NO_ROTATION</code>.
* ''z_offset'': Z position of the effect.

Additional to the number of effects, the callback result may specify these flags:
;<code style="color:darkgreen">CB_RESULT_CREATE_EFFECT_CENTER</code>
:(Train and road vehicle only) If set, position effect relative to vehicle center instead of relative to vehicle sprite. (behaves the same for vehicles with length 8/8)
;<code style="color:darkgreen">CB_RESULT_CREATE_EFFECT_NO_ROTATION</code>
*If not set, the parameters to <code style="color:darkgreen">effect_sprite</code> describe longitudinal/transversal positions, which are rotate wrt. vehicle orientation.
*If set, the parameters to <code style="color:darkgreen">effect_sprite</code> describe X and Y positions, which are not automatically rotated.
|-
| reverse_build_probability
| {{nml|0.7.5}} {{ottd|14.0}} Trains
| No
| 0
| Probability of reversing rail vehicle, i.e. facing forward or backward, when purchased.
|-
| refit
| {{ottd|15.0}} All vehicle types
| Callback runs once, in purchase scope only
|
* 0 Don't change refittability (i.e. use whatever the evaluation of the various refittability vehicle props has determined).
* 1 Allow cargo type as a refit.
* 2 Disallow cargo type as a refit.
|

The custom refit callback allows overriding the refittablity of each cargo as defined by the standard vehicle properties. It will be called for each defined cargo type once after the game has loaded all NewGRF files. The callback is run in purchase list scope, i.e. for cargotype FF. No variables of an actual vehicle are available. Information about the cargo type the callback is called for is available in variables 10 and 18:
'''Note:''' As this callback is not re-evaluated after game initialization, using any dynamic variables like e.g. game date will lead to undefined and faulty behaviour.

This callback is available starting with {{ottdp|15|no|ottdrev=gd2496b6ec4}} OpenTTD 15.

See https://newgrf-specs.tt-wiki.net/wiki/Callbacks#Custom_refit_.28163.29
|}

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

{| class="wikitable sortable"
! 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
|
|-
| effect_spawn_model_and_powered
| Trains
| No
|
|-
| effect_spawn_model
| 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
|
|-
| curve_speed_mod
| {{nml|0.7}} {{ottd|12.0}} Trains
| No
|
|-
| name
| {{nml|0.7.2}} {{ottd|14.0}} All
| Yes
| Can be used to display vehicle name differently depending on context (purchase menu, depot, nested variant depth etc). <code style="color:darkgreen">extra_callback_info1</code> contains detailed information about context - please see https://newgrf-specs.tt-wiki.net/wiki/Callbacks#Engine_name_.28161.29
|}

===Sprites in GUI===
{{ottdp|1.2|no|ottdrev=r23080}} Since OpenTTD r23080 you can use variable <code style="color:darkgreen">getbits(extra_callback_info1, 0, 8)</code> to display different sprites in the GUI and on the map. Currently these cases are available:
{| |-
! getbits(extra_callback_info1, 0, 8) !! 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 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.

===Composing vehicles from multiple sprites===
{{ottdp|1.7|no|ottdrev=r27668}} Since OpenTTD r27668 you can draw vehicles by drawing multiple sprites on top of each other.
* The sprites can use different recolouring.
* When using 32bpp sprites, the sprites can use the alpha channel to blend with the other sprites. In particular you can use this to alpha-blend company colours over other sprites.

To enable this, you need to set <code style="color:darkgreen">XXX_FLAG_SPRITE_STACK</code> in the <code style="color:darkgreen">misc_flags</code> property.

When enabled, sprites are resolved multiple times while incrementing an iteration number, that can be read via
<code style="color:darkgreen">getbits(extra_callback_info1, 8, 8)</code>

For OpenTTD 1.7 to 12.0, this is limited to at most 4 sprites per articulated part.

Increased to 8 sprites per articulated part for OpenTTD 13.0 {{ottdp|13.0|no}}

In addition you need to set register 100 as additional result:
* <code style="color:darkgreen">STORE_TEMP(CB_FLAG_MORE_SPRITES | recolouring, 0x100)</code> if there are more sprites to draw.
* <code style="color:darkgreen">STORE_TEMP(recolouring, 0x100)</code> if there are no more sprites to draw.
"recolouring" can be:
* <code>PALETTE_USE_DEFAULT</code> to use the default vehicle recolouring.
* <code>PALETTE_IDENTITY</code> to use no recolouring
* Any other default or custom recolouring sprite.

===Sound events===

{| class="wikitable sortable"
! 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
|}

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

Note that while vehicle ID affects the order in which vehicles appear in the purchase menu, this can be overridden using the [[NML:Sorting vehicles in the purchase list|sort block]].

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

VariationalAction2/Vehicles

2026-06-05T07:52:28Z

Rito12: /* Test if rail or road type of the current type occupied by the vehicle has that specific badge attached (65) */ type -> tile

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

== Variables ==

{|
!Variable!![[GRFActionsDetailed|Size]]!!Version!!Description!!Available in purchase list
|-
|10||D||{{ottdp|1.2|no|ottdrev=r23080}}||Pick sprites for different GUI windows - See [[Action2/Vehicles]].||{{ottdp|1.2|no|ottdrev=r23080}}
|-
|40||D||{{ottdp|0.6|2.5}}||Position in consist and length of consist||no
|-
|41||D||{{ottdp|0.6|2.5}}||Position in and length of chain of consecutive vehicles with same ID||no
|-
|42||D||{{ottdp|0.6|2.5}}||Cargo types transported by consist||no
|-
|43||D||{{ottdp|0.6|2.5}}||Player info||{{ottdp|0.6|2.5|ottdrev=r4611|ttdprev=beta 2}}
|-
|44||D||{{ottdp|0.6|2.5|ttdprev=2.0.1 alpha 48}}||Aircraft info||no
|-
|45||D||{{ottdp|0.6|2.5|ttdprev=2.0.1 alpha 58}}||Curvature info||no
|-
|46||D||{{ottdp|0.6|2.5|ttdprev=2.0.1 alpha 59}}||Motion counter||no
|-
|47||D||{{ottdp|0.6|2.5}}||Vehicle cargo info||{{ottdp|0.7|no|ottdrev=r15542}} <ref name="var47">Variable 47 refers to the default cargo of the vehicle, when in purchase list. This differs from the cargo used in Action 3, which is 0xFF in purchase list. The "refit cycle" (F2) is currently always zero in the purchase list.</ref>
|-
|48||D||{{ottdp|0.6|2.5}}||Vehicle type information||{{ottdp|0.6|2.5|ottdrev=r5338|ttdprev=beta 2}}
|-
|49||D||{{ottdp|0.7|2.6|ottdrev=r13376|ttdprev=r2216}}||Year of construction (long format, 0 based)||{{ottdp|0.7|no|ottdrev=r13376}} <ref name="date">This is the current date</ref>
|-
|4A||D||{{ottdp|1.1|no|ottdrev=r20165}}||Info about current railtype/roadtype/tramtype||no
|-
|4B||D||{{ottdp|1.2|no|ottdrev=r23068}}||Long date of last servicing||{{ottdp|1.2|no|ottdrev=r23068}} <ref name="date" />
|-
|4C||D||{{ottdp|1.3|no|ottdrev=r24246}}||Current max speed including e.g track or timetable speed limits. Only valid for front vehicle. Note, units differ for each vehicle type<ref name="speed">See [[Action0Trains#Speed 09|train property 09]], [[Action0RoadVehicles|road vehicle property 08]] (not 15, even when using realistic acceleration), [[Action0Ships|ship property 0B]] and [[Action0Planes|aircraft property 0C]].</ref>||no
|-
|4D||D||{{ottdp|1.4|no|ottdrev=r26157}}||Position within articulated vehicle||no
|-
|60||D||{{ottdp|0.6|2.5|ttdprev=2.0.1 alpha 57}}||Count Veh.ID occurence||no
|-
|61||-<ref>The size of the result matches the size of the queried variable.</ref>||{{ottdp|1.2|no|ottdrev=r22997}}||Query variable of n-th vehicle in chain||no
|-
|62||D||{{ottdp|1.2|no|ottdrev=r22998}}||Curvature/position difference for n-th vehicle in chain||no
|-
|63||D||{{ottdp|1.11|no|ottdrev=g868d84bbf}}||Test track-type of tile against another track-type||no
|-
|65||D||{{ottdp|15|no}}||Test if rail or road type of the current type occupied by the vehicle has that specific badge attached||no
|-
|7A||D||{{ottdp|15|no}}||Test if the vehicle has that specific badge attached||yes
|-
|97||B||{{ottdp|0.6|2.0}}||Tick counter, increased every engine tick||no
|-
|B2||W||||Vehicle status: bit0 = vehicle invisible (in tunnel/depot), bit1 = stopped, bit7 = crashed||no
|-
|B4||W||{{ottdp|0.6|2.0}}||Current speed. Note, units differ for each vehicle type<ref name="speed" />||no
|-
|B9||B||{{ottdp|0.6|2.0}}||Cargo type (type B from the list at [[CargoTypes]]; climate dependent)||no
|-
|C0||W||{{ottdp|0.6|2.0}}||Engine age in days {{ottdp|1.2|2.5|ottdrev=r22816|ttdprev=alpha 61}} Valid for wagons and articulated parts as well.||no
|-
|C4||B||{{ottdp|0.6|2.0}}||Year built (counted from 1920), note this is modified when Cht: Year is used||{{ottdp|0.6|no|ottdrev=r4611}} <ref name="date" />
|-
|C6||W||{{ottdp|0.6|2.0}}||Vehicle type ID <ref>{{ottdp|0.7|no}} In OpenTTD 0.7 and newer this is the GRF-local ID of the vehicle. Earlier versions of OpenTTD and TTDPatch report the [[VehicleIDs|TTD ID]]. For trains this is the same; for other vehicle types they differ.</ref> (useful for [[Callbacks#Can wagon be attached (1D)|Callback 1D]])||no
|-
|C8||B||{{ottdp|0.6|2.0}}||Sprite type; FD for trains forward, FE or FF when reversed||no
|-
|C9||B||{{ottdp|0.6|2.0}}||Day counter; increased daily||no
|-
|DA||W||{{ottdp|0.6|2.0}}||Next wagon index, FFFF if last wagon (use shift-num=08 and check for FF)||no
|-
|F2||B||{{ottdp|0.6|2.5}}||Refit cycle, how many times refitted to the same cargo type||{{ottdp|0.7|no|ottdrev=r15542}} <ref name="var47" />
|-
|F4||D||{{ottdp|0.5|2.0|ottdrev=3594}}||Current horsepower of train consist||no
|-
|FE||W||{{ottdp|0.6|2.5}}||Modflags||no
|-
|FF||B||{{ottdp|0.6|2.5}}||Modflags||no
|}

<references />

For other 80+x variables confer the [http://marcin.ttdpatch.net/sv1codec/TTD-locations.html#_VehicleArray TTD vehicle structure].

Variables 40, 41, 42 and 43 are cached. This means that while they are in principle computationally expensive, they can be used without impacting performance. Variables 45 and 60 are also computationally expensive but cannot be cached, and should therefore be used sparingly. If possible 80+x variables are to be preferred.

Cached variables are updated when the game is loaded, when the consist enters or is rearranged in a depot, and when the train reverses.

In the purchase list only a few variables are available. Especially the front vehicle (related object) cannot be accessed, nor other articulated parts.

== Description ==
=== Position and length (40, 41) ===

'''Format:''' 00nnbbff

{| |-
!Variable!!Value
|-
|ff||position of vehicle within the consist counted from the engine (front), e.g. the engine would have ff=0, the 1st wagon or mail compartment of planes would have ff=1, the 2nd wagon or the rotor of helicopters would have ff=2, the 3rd wagon would have ff=3 etc
|-
|bb||same as ff, but counted from the end, i.e. the last wagon has bb=0, the next-to-last wagon has bb=1 etc.
|-
|nn||Total number of vehicles in the consist, including shadow and rotor for aircraft.
* In var 40 this is zero-based. That is, the value returned is one less than the actual number of vehicles. A train with engine and three wagons has nn=3.
* In var 41 this is one-based. That is, the value returned is the actual number of vehicles.
|}

For variable 40, these numbers refer to the whole consist, but for variable 41, they only refer to the chain of consecutive vehicles with the same ID as the current wagon (including itself, but possibly excluding the engine):

[[File:vehicle_var40_41.png]]

Note however, that accessing the "related" object (i.e. the locomotive) doesn´t make much sense for vars 40/41, except for var40 when in a [[Callbacks#Can wagon be attached 1D|callback 1D]] chain.

=== Consist cargo (42) ===

'''Format:''' uuiicctt

{| |-
!Variable!!Value
|-
|tt||a bit mask of all [[Action0Cargos#Cargo classes 16|cargo classes]] transported by the consist
|-
|cc||the most common [[CargoTypes|cargo type]] (from the column for type A)
|-
|ii||the most common refit cycle (var. F2) of cargo type cc
|-
|uu||the result of ORing the bits of prop. 25 from all vehicles in the train
|}

If used with VarAction2 type 81 (vehicle) it returns only cargo from this vehicle on, with type 82 (engine) that of the whole consist.
See also variable 47 for more details on the cargo carried by a vehicle.

{{grfTill|7}} For GRF versions 7 and before "cc" is the untranslated bit number from [[Action0/Cargos#Bit_number_for_bitmasks_.2808.29|cargo property 8]].

{{grfFrom|8}} With GRF version 8 the meaning of "cc" changes. If the grf file has installed a [[Action0/Global_Settings#Cargo_translation_table_.2809.29|cargo translation table]], the value in "cc" is the index of the cargo in that table; or FF if the cargo is not present in the table.

=== Player info (43) ===

'''Format:''' Ccttmmnn

{| |-
!Variable!!Value
|-
|nn||the number of the current player from 0 to 7 (up to E (14) in OpenTTD since r14735)
|-
|mm||the multiplayer player number with the host player (or the single player) being 0 and the client player being 1
|-
|tt||the player type, see below for possible values
|-
|c||the primary player colour
|-
|C||{{ottdp|0.6|2.5|ttdprev=r1405}} the secondary player colour, equal to c if none (since r1405)
|}

{| |-
!tt value!!Meaning
|-
|0||Player is human player (permanent company)
|-
|1||Player is AI player (not managed)
|-
|2||{{ottdp|no|2.5}} Player is a human managing an AI company
|-
|3||{{ottdp|no|2.5}} Player is human player's original company, now temporarily AI controlled
|}

{{ottdp|0.6|2.5|ttdprev=r1497}} Since r1497, when the vehicle sprite is being displayed in an exclusive offer window or new vehicle news message, or in other circumstances when no player is associated with the vehicle, nn will be FF.

=== Aircraft info (44) ===

'''Format:''' xxxxhhtt

hh is the height of the aircraft above ground, or more properly above the height of its shadow. Buildings, including the heliport, don't count as "ground", i.e. to get the height above a heliport, you have to subtract the heliport height from hh.

tt is the type of the current airport: 0=small, 1=large, 2=heliport, 3=oil rig. The current airport is the target airport for aircraft that have finished the ascent and are in flight.

=== Curvature info (45) ===

'''Format:''' xxxTxBxF

This returns the amount of curvature between the adjacent wagon pairs. It is useful for train vehicles that normally tilt in curves. The curvature is the difference in direction between the surrounding vehicles:

F = for the front pair (previous wagon to current wagon, 0 if vehicle is first)

B = for the back pair (current wagon to next wagon, 0 if wagon is last)

T = for the triplet (previous wagon to next wagon; is zero in an S-bend)

Possible values:

{| |-
!Decimal!!Hex!!Meaning
|-
| -4||C||180° curve left (T only)
|-
| -3||D||135° curve left (T only)
|-
| -2||E||90° curve left
|-
| -1||F||45° curve left
|-
|0||0||no curve
|-
|1||1||45° curve right
|-
|2||2||90° curve right
|-
|3||3||135° curve right (T only)
|-
|4||4||180° curve right (T only)
|}

=== Motion counter (46) ===

'''Format:''' 32-bit value

This variable counts the amount of motion that a vehicle has done.  It is only valid for the first vehicle in a consist (i.e. use VarAction2 type 82!).  Its value is in units of 1/4096 of a tile.  A vehicle actually moves visibly every time the motion counter increases by 256, and since a tile consists of 16 such subunits, 16*256=4096 motion units mean motion across one tile.

The most useful way to access it is probably with <shiftnum>=08 and an appropriate <andmask>.  For example, to achieve an animation with one frame per vehicle motion and 16 frames in total for motion across an entire tile, you would use <shiftnum>=08 and <andmask>=0F.  For an animation with one frame every two vehicle motions and 4 frames total, use <shiftnum>=09 and <andmask>=03.

If the vehicle is going very fast (>160 mph for trains), it may move by several 1/16ths of a tile at once, and thus some frames may be skipped, but the animation will still remain in sync with the motion.

Note that vehicle graphics are only updated every time the vehicle actually moves, so checking the lower byte is probably pointless, and only needed internally to achieve sufficient precision.

=== Vehicle cargo info (47) ===

'''Format:''' ccccwwtt

{| |-
!Variable!!Value
|-
|tt||the [[CargoTypes|cargo type]] transported by the vehicle (from the column for type A); translated if a translation table has been installed
|-
|ww||cargo unit weight in 1/16 tons, same as [[Action0Cargos#Weight of one unit of the cargo 0F|cargo prop. 0F]]
|-
|cccc||the [[Action0Cargos#Cargo classes 16|cargo class]] value of the cargo transported by the vehicle
|}

Note that if the grf has installed a [[Action0/Global_Settings#Cargo_translation_table_.2809.29|cargo translation table]], the value in "tt" is the slot number in that table, irrespective of which actual slot or bit the cargo is using in the game. If a table has been installed, but the current cargo is not listed there, "tt" will be set to FF.

Unlike variable 42, this variable returns the info of the current vehicle only, not the consist.

=== Vehicle type information (48) ===

'''Format:''' xxxxxxff

The bits of ff are:

{| |-
!Bit!!Value!!Meaning
|-
|0||1||Vehicle type is available on the market
|-
|1||2||Vehicle type is in the testing phase
|-
|2||4||Exclusive testing offer for a human player active
|}

All other bits in ff are undefined and must be masked out.

=== Information about current railtype/roadtype/tramtype (4A) ===

'''Format:''' xxxxFFrr

The lower byte (rr) contains the (translated) railtype/roadtype/tramtype the vehicle is currently driving on.
If the railtype/roadtype/tramtype has no entry in the railtype/roadtype/tramtype translation table of the GRF, this value will be 0xFF.
If no translation table is present, the raw value will be returned.
Note: only exact matches of rail-/road-/-tram-types are reported. If the translation table of the GRF does not contain the exact track-type 0xFF is returned, even if the translation table contains equivalent track-types (according to rail-/road-/tram-type property 1D). Use variable 63 to test for compatibility/poweredness/equivalency with track-types known to both the vehicle and the track-type NewGRF.

The variable only reports about the tracks the vehicle is using: on a level crossing with rail, road and tram tracks, the vehicle (train, road vehicle, tram) can only query the track type it belongs to.

The second byte (FF) contains the following flags:

{| |-
!Bit!!Value!!Meaning
|-
|0||1||The vehicle is/would be powered on the current railtype (this is independent from powered/non-powered wagon or anything)
|-
|1||2||{{ottdp|1.11|no|ottdrev=gf1bc4d840}} Set, if the track-type has catenary. This is independent of the vehicle: a NewGRF can define an engine as powered on non-electrified track (bit 0), and show a raised pantograph (bit 1) to look like a dual-powered engine. This bit is a simplified as it only checks for "some catenary". To distinguish different types of catenaries, AC and DC voltages, ... use variable 63 instead.
|}

All other bits are reserved, and must be masked.

All other bytes are reserved, and must be masked.

=== Position within articulated vehicle (4D) ===

'''Format:''' xxxxbbff

{| |-
!Variable!!Value
|-
|ff||Position of vehicle (articulated part) within the articulated vehicle, counted from the first part, starting with 0.
|-
|bb||Position of vehicle (articulated part) within the articulated vehicle, counted from the last part, starting with 0.
|-
|xx||Reserved, do not access.
|}

The total number of articulated parts of a vehicle equals ff + 1 + bb.

For road vehicles "ff" and "bb" currently equal var 40, since there are no road vehicle wagons yet.

=== Count Veh.ID occurence (60) ===

'''Format:''' xxxxxxnn

The 60+x parameter is the vehicle ID to look for, and the returned nn is the number of vehicles in the consist that have this ID. If used with VarAction2 type 81, only the current vehicle and onwards will be check, with VarAction2 type 82, all vehicles in the consist will be counted.

=== Query variable of n-th vehicle in chain (61) ===

This is a special variable to get the contents of another variable of a different vehicle in the vehicle chain. It is only supported for trains and road vehicles. It is not supported during a callback that is used to modify vehicle properties to avoid circular dependencies, which currently limits this variable to callbacks 1D, 2D, 31 and 32 plus outside callback scope.

Temporary register 10F is interpreted as a signed integer and specifies the offset in the chain from the current vehicle. 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.

The 60+x parameter specifies the variable to access and temporary register 10E is passed as the new 60+x parameter. Passing 61 as the variable is not allowed. Currently only vehicle specific variables listed on this page plus global variable 25 and {{ottdp|1.3|no|ottdrev=r24527}} 5F are accessible through var 61.

The resulting value will have the size of whatever variable is queried.

=== Curvature/position difference for n-th vehicle in chain (62) ===

'''Format:''' zzyyxxFD

This variable is only supported for trains and road vehicles.

The 60+x parameter is interpreted as a signed integer and specifies the offset in the chain from the current vehicle. 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.

The lowest nibble (D) contains the direction difference between the selected vehicle and this vehicle, the possible values are identical to those of [[#Curvature_info_.2845.29|variable 45]].

The next nibble (F) has the following meaning:
{| |-
!Bit!!Value!!Meaning
|-
|3||8||The vehicle is currently hidden
|}

The upper three bytes contain the signed difference of the X/Y/Z position between the selected vehicle and this vehicle.

=== Track-type test against another track-type (63) ===

{{ottdp|1.11|no|ottdrev=g868d84bbf}}

'''Format:''' xxxxxxFF

This variable is only supported for trains and road vehicles.

The 60+x parameter is an index into the rail-/road-/tram-type translation table.
The result value reports how vehicles of this type would behave on the current tile.
This allows vehicles to behave or look differently on various track-types independent of their own track-type.

The lower byte (FF) contains some flags:
{|
|-
!Bit!!Value!!Meaning
|-
|0||1||The track-type from the 60+x parameter is known. If unset, all other flags are unset as well, no information can be given.
|-
|1||2||Vehicles with type from the 60+x parameter are compatible with the track on the current tile.
|-
|2||4||Vehicles with type from the 60+x parameter are powered on the track of the current tile.
|-
|3||8||The track-type from the 60+x parameter is identical or equivalent (listed as alternate label in rail-/road-/tram-type property 1D) to the track-type of the current tile.
|}

The remaining bytes are reserved, and must be masked.

=== Test if rail or road type of the current tile occupied by the vehicle has that specific badge attached (65) ===

{{ottdp|15|no}}

This variable only works for trains and road vehicles.
The specifications are the same as for [[#Test_if_the_vehicle_has_that_specific_badge_attached.287A.29|variable 7A]].

=== Test if the vehicle has that specific badge attached (7A) ===

{{ottdp|15|no}}

The 60+x parameter is the index into the badge table.
The returned value is in range [0, 1].

=== Modflags (FE and FF) ===

The bits in FE mostly relate to gradualloading.  A few useful bits for grf authors are;

{| |-
!Bit!!Version!!Value of the bit
|-
|1||{{ottdp|1.5|2.5|ottdrev=r26430}}||Vehicle is still unloading and has not yet started loading new cargo at the current station.
|-
|5||{{ottdp|0.6|2.5}}||Vehicle is powered (engine or powered wagon, mainly useful for the latter)
|-
|6||{{ottdp|0.6|2.5}}||Vehicle would be powered (engine or powered wagon) if there were suitable track. (E.g. electric train in mixed train on normal track)
|-
|8 <ref>This bit is only accurate for the first vehicle in the consist.</ref>||{{ottdp|0.6|2.5}}||This bit is flipped every time the train reverses direction
|-
|10||{{ottdp|0.6|2.5|ttdprev=r1334}}||Vehicle was built during the exclusive preview
|-
|11 <ref>This bit is only accurate for the first vehicle in the consist.</ref>||{{ottd|16}}||The train is driving backwards (trains only)
|}
<references/>

variable FF is actually the high byte of variable FE, so FE bit 8 is the same as FF bit 0.

Other bits are reserved; most are actually used for TTDPatch internal states.

VariationalAction2/Vehicles

2026-06-05T07:43:33Z

Rito12: /* Test if rail or road type of the current type occupied by the vehicle has that specific badge attached (65) */

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

== Variables ==

{|
!Variable!![[GRFActionsDetailed|Size]]!!Version!!Description!!Available in purchase list
|-
|10||D||{{ottdp|1.2|no|ottdrev=r23080}}||Pick sprites for different GUI windows - See [[Action2/Vehicles]].||{{ottdp|1.2|no|ottdrev=r23080}}
|-
|40||D||{{ottdp|0.6|2.5}}||Position in consist and length of consist||no
|-
|41||D||{{ottdp|0.6|2.5}}||Position in and length of chain of consecutive vehicles with same ID||no
|-
|42||D||{{ottdp|0.6|2.5}}||Cargo types transported by consist||no
|-
|43||D||{{ottdp|0.6|2.5}}||Player info||{{ottdp|0.6|2.5|ottdrev=r4611|ttdprev=beta 2}}
|-
|44||D||{{ottdp|0.6|2.5|ttdprev=2.0.1 alpha 48}}||Aircraft info||no
|-
|45||D||{{ottdp|0.6|2.5|ttdprev=2.0.1 alpha 58}}||Curvature info||no
|-
|46||D||{{ottdp|0.6|2.5|ttdprev=2.0.1 alpha 59}}||Motion counter||no
|-
|47||D||{{ottdp|0.6|2.5}}||Vehicle cargo info||{{ottdp|0.7|no|ottdrev=r15542}} <ref name="var47">Variable 47 refers to the default cargo of the vehicle, when in purchase list. This differs from the cargo used in Action 3, which is 0xFF in purchase list. The "refit cycle" (F2) is currently always zero in the purchase list.</ref>
|-
|48||D||{{ottdp|0.6|2.5}}||Vehicle type information||{{ottdp|0.6|2.5|ottdrev=r5338|ttdprev=beta 2}}
|-
|49||D||{{ottdp|0.7|2.6|ottdrev=r13376|ttdprev=r2216}}||Year of construction (long format, 0 based)||{{ottdp|0.7|no|ottdrev=r13376}} <ref name="date">This is the current date</ref>
|-
|4A||D||{{ottdp|1.1|no|ottdrev=r20165}}||Info about current railtype/roadtype/tramtype||no
|-
|4B||D||{{ottdp|1.2|no|ottdrev=r23068}}||Long date of last servicing||{{ottdp|1.2|no|ottdrev=r23068}} <ref name="date" />
|-
|4C||D||{{ottdp|1.3|no|ottdrev=r24246}}||Current max speed including e.g track or timetable speed limits. Only valid for front vehicle. Note, units differ for each vehicle type<ref name="speed">See [[Action0Trains#Speed 09|train property 09]], [[Action0RoadVehicles|road vehicle property 08]] (not 15, even when using realistic acceleration), [[Action0Ships|ship property 0B]] and [[Action0Planes|aircraft property 0C]].</ref>||no
|-
|4D||D||{{ottdp|1.4|no|ottdrev=r26157}}||Position within articulated vehicle||no
|-
|60||D||{{ottdp|0.6|2.5|ttdprev=2.0.1 alpha 57}}||Count Veh.ID occurence||no
|-
|61||-<ref>The size of the result matches the size of the queried variable.</ref>||{{ottdp|1.2|no|ottdrev=r22997}}||Query variable of n-th vehicle in chain||no
|-
|62||D||{{ottdp|1.2|no|ottdrev=r22998}}||Curvature/position difference for n-th vehicle in chain||no
|-
|63||D||{{ottdp|1.11|no|ottdrev=g868d84bbf}}||Test track-type of tile against another track-type||no
|-
|65||D||{{ottdp|15|no}}||Test if rail or road type of the current type occupied by the vehicle has that specific badge attached||no
|-
|7A||D||{{ottdp|15|no}}||Test if the vehicle has that specific badge attached||yes
|-
|97||B||{{ottdp|0.6|2.0}}||Tick counter, increased every engine tick||no
|-
|B2||W||||Vehicle status: bit0 = vehicle invisible (in tunnel/depot), bit1 = stopped, bit7 = crashed||no
|-
|B4||W||{{ottdp|0.6|2.0}}||Current speed. Note, units differ for each vehicle type<ref name="speed" />||no
|-
|B9||B||{{ottdp|0.6|2.0}}||Cargo type (type B from the list at [[CargoTypes]]; climate dependent)||no
|-
|C0||W||{{ottdp|0.6|2.0}}||Engine age in days {{ottdp|1.2|2.5|ottdrev=r22816|ttdprev=alpha 61}} Valid for wagons and articulated parts as well.||no
|-
|C4||B||{{ottdp|0.6|2.0}}||Year built (counted from 1920), note this is modified when Cht: Year is used||{{ottdp|0.6|no|ottdrev=r4611}} <ref name="date" />
|-
|C6||W||{{ottdp|0.6|2.0}}||Vehicle type ID <ref>{{ottdp|0.7|no}} In OpenTTD 0.7 and newer this is the GRF-local ID of the vehicle. Earlier versions of OpenTTD and TTDPatch report the [[VehicleIDs|TTD ID]]. For trains this is the same; for other vehicle types they differ.</ref> (useful for [[Callbacks#Can wagon be attached (1D)|Callback 1D]])||no
|-
|C8||B||{{ottdp|0.6|2.0}}||Sprite type; FD for trains forward, FE or FF when reversed||no
|-
|C9||B||{{ottdp|0.6|2.0}}||Day counter; increased daily||no
|-
|DA||W||{{ottdp|0.6|2.0}}||Next wagon index, FFFF if last wagon (use shift-num=08 and check for FF)||no
|-
|F2||B||{{ottdp|0.6|2.5}}||Refit cycle, how many times refitted to the same cargo type||{{ottdp|0.7|no|ottdrev=r15542}} <ref name="var47" />
|-
|F4||D||{{ottdp|0.5|2.0|ottdrev=3594}}||Current horsepower of train consist||no
|-
|FE||W||{{ottdp|0.6|2.5}}||Modflags||no
|-
|FF||B||{{ottdp|0.6|2.5}}||Modflags||no
|}

<references />

For other 80+x variables confer the [http://marcin.ttdpatch.net/sv1codec/TTD-locations.html#_VehicleArray TTD vehicle structure].

Variables 40, 41, 42 and 43 are cached. This means that while they are in principle computationally expensive, they can be used without impacting performance. Variables 45 and 60 are also computationally expensive but cannot be cached, and should therefore be used sparingly. If possible 80+x variables are to be preferred.

Cached variables are updated when the game is loaded, when the consist enters or is rearranged in a depot, and when the train reverses.

In the purchase list only a few variables are available. Especially the front vehicle (related object) cannot be accessed, nor other articulated parts.

== Description ==
=== Position and length (40, 41) ===

'''Format:''' 00nnbbff

{| |-
!Variable!!Value
|-
|ff||position of vehicle within the consist counted from the engine (front), e.g. the engine would have ff=0, the 1st wagon or mail compartment of planes would have ff=1, the 2nd wagon or the rotor of helicopters would have ff=2, the 3rd wagon would have ff=3 etc
|-
|bb||same as ff, but counted from the end, i.e. the last wagon has bb=0, the next-to-last wagon has bb=1 etc.
|-
|nn||Total number of vehicles in the consist, including shadow and rotor for aircraft.
* In var 40 this is zero-based. That is, the value returned is one less than the actual number of vehicles. A train with engine and three wagons has nn=3.
* In var 41 this is one-based. That is, the value returned is the actual number of vehicles.
|}

For variable 40, these numbers refer to the whole consist, but for variable 41, they only refer to the chain of consecutive vehicles with the same ID as the current wagon (including itself, but possibly excluding the engine):

[[File:vehicle_var40_41.png]]

Note however, that accessing the "related" object (i.e. the locomotive) doesn´t make much sense for vars 40/41, except for var40 when in a [[Callbacks#Can wagon be attached 1D|callback 1D]] chain.

=== Consist cargo (42) ===

'''Format:''' uuiicctt

{| |-
!Variable!!Value
|-
|tt||a bit mask of all [[Action0Cargos#Cargo classes 16|cargo classes]] transported by the consist
|-
|cc||the most common [[CargoTypes|cargo type]] (from the column for type A)
|-
|ii||the most common refit cycle (var. F2) of cargo type cc
|-
|uu||the result of ORing the bits of prop. 25 from all vehicles in the train
|}

If used with VarAction2 type 81 (vehicle) it returns only cargo from this vehicle on, with type 82 (engine) that of the whole consist.
See also variable 47 for more details on the cargo carried by a vehicle.

{{grfTill|7}} For GRF versions 7 and before "cc" is the untranslated bit number from [[Action0/Cargos#Bit_number_for_bitmasks_.2808.29|cargo property 8]].

{{grfFrom|8}} With GRF version 8 the meaning of "cc" changes. If the grf file has installed a [[Action0/Global_Settings#Cargo_translation_table_.2809.29|cargo translation table]], the value in "cc" is the index of the cargo in that table; or FF if the cargo is not present in the table.

=== Player info (43) ===

'''Format:''' Ccttmmnn

{| |-
!Variable!!Value
|-
|nn||the number of the current player from 0 to 7 (up to E (14) in OpenTTD since r14735)
|-
|mm||the multiplayer player number with the host player (or the single player) being 0 and the client player being 1
|-
|tt||the player type, see below for possible values
|-
|c||the primary player colour
|-
|C||{{ottdp|0.6|2.5|ttdprev=r1405}} the secondary player colour, equal to c if none (since r1405)
|}

{| |-
!tt value!!Meaning
|-
|0||Player is human player (permanent company)
|-
|1||Player is AI player (not managed)
|-
|2||{{ottdp|no|2.5}} Player is a human managing an AI company
|-
|3||{{ottdp|no|2.5}} Player is human player's original company, now temporarily AI controlled
|}

{{ottdp|0.6|2.5|ttdprev=r1497}} Since r1497, when the vehicle sprite is being displayed in an exclusive offer window or new vehicle news message, or in other circumstances when no player is associated with the vehicle, nn will be FF.

=== Aircraft info (44) ===

'''Format:''' xxxxhhtt

hh is the height of the aircraft above ground, or more properly above the height of its shadow. Buildings, including the heliport, don't count as "ground", i.e. to get the height above a heliport, you have to subtract the heliport height from hh.

tt is the type of the current airport: 0=small, 1=large, 2=heliport, 3=oil rig. The current airport is the target airport for aircraft that have finished the ascent and are in flight.

=== Curvature info (45) ===

'''Format:''' xxxTxBxF

This returns the amount of curvature between the adjacent wagon pairs. It is useful for train vehicles that normally tilt in curves. The curvature is the difference in direction between the surrounding vehicles:

F = for the front pair (previous wagon to current wagon, 0 if vehicle is first)

B = for the back pair (current wagon to next wagon, 0 if wagon is last)

T = for the triplet (previous wagon to next wagon; is zero in an S-bend)

Possible values:

{| |-
!Decimal!!Hex!!Meaning
|-
| -4||C||180° curve left (T only)
|-
| -3||D||135° curve left (T only)
|-
| -2||E||90° curve left
|-
| -1||F||45° curve left
|-
|0||0||no curve
|-
|1||1||45° curve right
|-
|2||2||90° curve right
|-
|3||3||135° curve right (T only)
|-
|4||4||180° curve right (T only)
|}

=== Motion counter (46) ===

'''Format:''' 32-bit value

This variable counts the amount of motion that a vehicle has done.  It is only valid for the first vehicle in a consist (i.e. use VarAction2 type 82!).  Its value is in units of 1/4096 of a tile.  A vehicle actually moves visibly every time the motion counter increases by 256, and since a tile consists of 16 such subunits, 16*256=4096 motion units mean motion across one tile.

The most useful way to access it is probably with <shiftnum>=08 and an appropriate <andmask>.  For example, to achieve an animation with one frame per vehicle motion and 16 frames in total for motion across an entire tile, you would use <shiftnum>=08 and <andmask>=0F.  For an animation with one frame every two vehicle motions and 4 frames total, use <shiftnum>=09 and <andmask>=03.

If the vehicle is going very fast (>160 mph for trains), it may move by several 1/16ths of a tile at once, and thus some frames may be skipped, but the animation will still remain in sync with the motion.

Note that vehicle graphics are only updated every time the vehicle actually moves, so checking the lower byte is probably pointless, and only needed internally to achieve sufficient precision.

=== Vehicle cargo info (47) ===

'''Format:''' ccccwwtt

{| |-
!Variable!!Value
|-
|tt||the [[CargoTypes|cargo type]] transported by the vehicle (from the column for type A); translated if a translation table has been installed
|-
|ww||cargo unit weight in 1/16 tons, same as [[Action0Cargos#Weight of one unit of the cargo 0F|cargo prop. 0F]]
|-
|cccc||the [[Action0Cargos#Cargo classes 16|cargo class]] value of the cargo transported by the vehicle
|}

Note that if the grf has installed a [[Action0/Global_Settings#Cargo_translation_table_.2809.29|cargo translation table]], the value in "tt" is the slot number in that table, irrespective of which actual slot or bit the cargo is using in the game. If a table has been installed, but the current cargo is not listed there, "tt" will be set to FF.

Unlike variable 42, this variable returns the info of the current vehicle only, not the consist.

=== Vehicle type information (48) ===

'''Format:''' xxxxxxff

The bits of ff are:

{| |-
!Bit!!Value!!Meaning
|-
|0||1||Vehicle type is available on the market
|-
|1||2||Vehicle type is in the testing phase
|-
|2||4||Exclusive testing offer for a human player active
|}

All other bits in ff are undefined and must be masked out.

=== Information about current railtype/roadtype/tramtype (4A) ===

'''Format:''' xxxxFFrr

The lower byte (rr) contains the (translated) railtype/roadtype/tramtype the vehicle is currently driving on.
If the railtype/roadtype/tramtype has no entry in the railtype/roadtype/tramtype translation table of the GRF, this value will be 0xFF.
If no translation table is present, the raw value will be returned.
Note: only exact matches of rail-/road-/-tram-types are reported. If the translation table of the GRF does not contain the exact track-type 0xFF is returned, even if the translation table contains equivalent track-types (according to rail-/road-/tram-type property 1D). Use variable 63 to test for compatibility/poweredness/equivalency with track-types known to both the vehicle and the track-type NewGRF.

The variable only reports about the tracks the vehicle is using: on a level crossing with rail, road and tram tracks, the vehicle (train, road vehicle, tram) can only query the track type it belongs to.

The second byte (FF) contains the following flags:

{| |-
!Bit!!Value!!Meaning
|-
|0||1||The vehicle is/would be powered on the current railtype (this is independent from powered/non-powered wagon or anything)
|-
|1||2||{{ottdp|1.11|no|ottdrev=gf1bc4d840}} Set, if the track-type has catenary. This is independent of the vehicle: a NewGRF can define an engine as powered on non-electrified track (bit 0), and show a raised pantograph (bit 1) to look like a dual-powered engine. This bit is a simplified as it only checks for "some catenary". To distinguish different types of catenaries, AC and DC voltages, ... use variable 63 instead.
|}

All other bits are reserved, and must be masked.

All other bytes are reserved, and must be masked.

=== Position within articulated vehicle (4D) ===

'''Format:''' xxxxbbff

{| |-
!Variable!!Value
|-
|ff||Position of vehicle (articulated part) within the articulated vehicle, counted from the first part, starting with 0.
|-
|bb||Position of vehicle (articulated part) within the articulated vehicle, counted from the last part, starting with 0.
|-
|xx||Reserved, do not access.
|}

The total number of articulated parts of a vehicle equals ff + 1 + bb.

For road vehicles "ff" and "bb" currently equal var 40, since there are no road vehicle wagons yet.

=== Count Veh.ID occurence (60) ===

'''Format:''' xxxxxxnn

The 60+x parameter is the vehicle ID to look for, and the returned nn is the number of vehicles in the consist that have this ID. If used with VarAction2 type 81, only the current vehicle and onwards will be check, with VarAction2 type 82, all vehicles in the consist will be counted.

=== Query variable of n-th vehicle in chain (61) ===

This is a special variable to get the contents of another variable of a different vehicle in the vehicle chain. It is only supported for trains and road vehicles. It is not supported during a callback that is used to modify vehicle properties to avoid circular dependencies, which currently limits this variable to callbacks 1D, 2D, 31 and 32 plus outside callback scope.

Temporary register 10F is interpreted as a signed integer and specifies the offset in the chain from the current vehicle. 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.

The 60+x parameter specifies the variable to access and temporary register 10E is passed as the new 60+x parameter. Passing 61 as the variable is not allowed. Currently only vehicle specific variables listed on this page plus global variable 25 and {{ottdp|1.3|no|ottdrev=r24527}} 5F are accessible through var 61.

The resulting value will have the size of whatever variable is queried.

=== Curvature/position difference for n-th vehicle in chain (62) ===

'''Format:''' zzyyxxFD

This variable is only supported for trains and road vehicles.

The 60+x parameter is interpreted as a signed integer and specifies the offset in the chain from the current vehicle. 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.

The lowest nibble (D) contains the direction difference between the selected vehicle and this vehicle, the possible values are identical to those of [[#Curvature_info_.2845.29|variable 45]].

The next nibble (F) has the following meaning:
{| |-
!Bit!!Value!!Meaning
|-
|3||8||The vehicle is currently hidden
|}

The upper three bytes contain the signed difference of the X/Y/Z position between the selected vehicle and this vehicle.

=== Track-type test against another track-type (63) ===

{{ottdp|1.11|no|ottdrev=g868d84bbf}}

'''Format:''' xxxxxxFF

This variable is only supported for trains and road vehicles.

The 60+x parameter is an index into the rail-/road-/tram-type translation table.
The result value reports how vehicles of this type would behave on the current tile.
This allows vehicles to behave or look differently on various track-types independent of their own track-type.

The lower byte (FF) contains some flags:
{|
|-
!Bit!!Value!!Meaning
|-
|0||1||The track-type from the 60+x parameter is known. If unset, all other flags are unset as well, no information can be given.
|-
|1||2||Vehicles with type from the 60+x parameter are compatible with the track on the current tile.
|-
|2||4||Vehicles with type from the 60+x parameter are powered on the track of the current tile.
|-
|3||8||The track-type from the 60+x parameter is identical or equivalent (listed as alternate label in rail-/road-/tram-type property 1D) to the track-type of the current tile.
|}

The remaining bytes are reserved, and must be masked.

=== Test if rail or road type of the current type occupied by the vehicle has that specific badge attached (65) ===

{{ottdp|15|no}}

This variable only works for trains and road vehicles.
The specifications are the same as for [[#Test_if_the_vehicle_has_that_specific_badge_attached.287A.29|variable 7A]].

=== Test if the vehicle has that specific badge attached (7A) ===

{{ottdp|15|no}}

The 60+x parameter is the index into the badge table.
The returned value is in range [0, 1].

=== Modflags (FE and FF) ===

The bits in FE mostly relate to gradualloading.  A few useful bits for grf authors are;

{| |-
!Bit!!Version!!Value of the bit
|-
|1||{{ottdp|1.5|2.5|ottdrev=r26430}}||Vehicle is still unloading and has not yet started loading new cargo at the current station.
|-
|5||{{ottdp|0.6|2.5}}||Vehicle is powered (engine or powered wagon, mainly useful for the latter)
|-
|6||{{ottdp|0.6|2.5}}||Vehicle would be powered (engine or powered wagon) if there were suitable track. (E.g. electric train in mixed train on normal track)
|-
|8 <ref>This bit is only accurate for the first vehicle in the consist.</ref>||{{ottdp|0.6|2.5}}||This bit is flipped every time the train reverses direction
|-
|10||{{ottdp|0.6|2.5|ttdprev=r1334}}||Vehicle was built during the exclusive preview
|-
|11 <ref>This bit is only accurate for the first vehicle in the consist.</ref>||{{ottd|16}}||The train is driving backwards (trains only)
|}
<references/>

variable FF is actually the high byte of variable FE, so FE bit 8 is the same as FF bit 0.

Other bits are reserved; most are actually used for TTDPatch internal states.

VariationalAction2/Vehicles

2026-06-05T07:41:35Z

Rito12: Add variables 7A and 65.

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

== Variables ==

{|
!Variable!![[GRFActionsDetailed|Size]]!!Version!!Description!!Available in purchase list
|-
|10||D||{{ottdp|1.2|no|ottdrev=r23080}}||Pick sprites for different GUI windows - See [[Action2/Vehicles]].||{{ottdp|1.2|no|ottdrev=r23080}}
|-
|40||D||{{ottdp|0.6|2.5}}||Position in consist and length of consist||no
|-
|41||D||{{ottdp|0.6|2.5}}||Position in and length of chain of consecutive vehicles with same ID||no
|-
|42||D||{{ottdp|0.6|2.5}}||Cargo types transported by consist||no
|-
|43||D||{{ottdp|0.6|2.5}}||Player info||{{ottdp|0.6|2.5|ottdrev=r4611|ttdprev=beta 2}}
|-
|44||D||{{ottdp|0.6|2.5|ttdprev=2.0.1 alpha 48}}||Aircraft info||no
|-
|45||D||{{ottdp|0.6|2.5|ttdprev=2.0.1 alpha 58}}||Curvature info||no
|-
|46||D||{{ottdp|0.6|2.5|ttdprev=2.0.1 alpha 59}}||Motion counter||no
|-
|47||D||{{ottdp|0.6|2.5}}||Vehicle cargo info||{{ottdp|0.7|no|ottdrev=r15542}} <ref name="var47">Variable 47 refers to the default cargo of the vehicle, when in purchase list. This differs from the cargo used in Action 3, which is 0xFF in purchase list. The "refit cycle" (F2) is currently always zero in the purchase list.</ref>
|-
|48||D||{{ottdp|0.6|2.5}}||Vehicle type information||{{ottdp|0.6|2.5|ottdrev=r5338|ttdprev=beta 2}}
|-
|49||D||{{ottdp|0.7|2.6|ottdrev=r13376|ttdprev=r2216}}||Year of construction (long format, 0 based)||{{ottdp|0.7|no|ottdrev=r13376}} <ref name="date">This is the current date</ref>
|-
|4A||D||{{ottdp|1.1|no|ottdrev=r20165}}||Info about current railtype/roadtype/tramtype||no
|-
|4B||D||{{ottdp|1.2|no|ottdrev=r23068}}||Long date of last servicing||{{ottdp|1.2|no|ottdrev=r23068}} <ref name="date" />
|-
|4C||D||{{ottdp|1.3|no|ottdrev=r24246}}||Current max speed including e.g track or timetable speed limits. Only valid for front vehicle. Note, units differ for each vehicle type<ref name="speed">See [[Action0Trains#Speed 09|train property 09]], [[Action0RoadVehicles|road vehicle property 08]] (not 15, even when using realistic acceleration), [[Action0Ships|ship property 0B]] and [[Action0Planes|aircraft property 0C]].</ref>||no
|-
|4D||D||{{ottdp|1.4|no|ottdrev=r26157}}||Position within articulated vehicle||no
|-
|60||D||{{ottdp|0.6|2.5|ttdprev=2.0.1 alpha 57}}||Count Veh.ID occurence||no
|-
|61||-<ref>The size of the result matches the size of the queried variable.</ref>||{{ottdp|1.2|no|ottdrev=r22997}}||Query variable of n-th vehicle in chain||no
|-
|62||D||{{ottdp|1.2|no|ottdrev=r22998}}||Curvature/position difference for n-th vehicle in chain||no
|-
|63||D||{{ottdp|1.11|no|ottdrev=g868d84bbf}}||Test track-type of tile against another track-type||no
|-
|65||D||{{ottdp|15|no}}||Test if rail or road type of the current type occupied by the vehicle has that specific badge attached||no
|-
|7A||D||{{ottdp|15|no}}||Test if the vehicle has that specific badge attached||yes
|-
|97||B||{{ottdp|0.6|2.0}}||Tick counter, increased every engine tick||no
|-
|B2||W||||Vehicle status: bit0 = vehicle invisible (in tunnel/depot), bit1 = stopped, bit7 = crashed||no
|-
|B4||W||{{ottdp|0.6|2.0}}||Current speed. Note, units differ for each vehicle type<ref name="speed" />||no
|-
|B9||B||{{ottdp|0.6|2.0}}||Cargo type (type B from the list at [[CargoTypes]]; climate dependent)||no
|-
|C0||W||{{ottdp|0.6|2.0}}||Engine age in days {{ottdp|1.2|2.5|ottdrev=r22816|ttdprev=alpha 61}} Valid for wagons and articulated parts as well.||no
|-
|C4||B||{{ottdp|0.6|2.0}}||Year built (counted from 1920), note this is modified when Cht: Year is used||{{ottdp|0.6|no|ottdrev=r4611}} <ref name="date" />
|-
|C6||W||{{ottdp|0.6|2.0}}||Vehicle type ID <ref>{{ottdp|0.7|no}} In OpenTTD 0.7 and newer this is the GRF-local ID of the vehicle. Earlier versions of OpenTTD and TTDPatch report the [[VehicleIDs|TTD ID]]. For trains this is the same; for other vehicle types they differ.</ref> (useful for [[Callbacks#Can wagon be attached (1D)|Callback 1D]])||no
|-
|C8||B||{{ottdp|0.6|2.0}}||Sprite type; FD for trains forward, FE or FF when reversed||no
|-
|C9||B||{{ottdp|0.6|2.0}}||Day counter; increased daily||no
|-
|DA||W||{{ottdp|0.6|2.0}}||Next wagon index, FFFF if last wagon (use shift-num=08 and check for FF)||no
|-
|F2||B||{{ottdp|0.6|2.5}}||Refit cycle, how many times refitted to the same cargo type||{{ottdp|0.7|no|ottdrev=r15542}} <ref name="var47" />
|-
|F4||D||{{ottdp|0.5|2.0|ottdrev=3594}}||Current horsepower of train consist||no
|-
|FE||W||{{ottdp|0.6|2.5}}||Modflags||no
|-
|FF||B||{{ottdp|0.6|2.5}}||Modflags||no
|}

<references />

For other 80+x variables confer the [http://marcin.ttdpatch.net/sv1codec/TTD-locations.html#_VehicleArray TTD vehicle structure].

Variables 40, 41, 42 and 43 are cached. This means that while they are in principle computationally expensive, they can be used without impacting performance. Variables 45 and 60 are also computationally expensive but cannot be cached, and should therefore be used sparingly. If possible 80+x variables are to be preferred.

Cached variables are updated when the game is loaded, when the consist enters or is rearranged in a depot, and when the train reverses.

In the purchase list only a few variables are available. Especially the front vehicle (related object) cannot be accessed, nor other articulated parts.

== Description ==
=== Position and length (40, 41) ===

'''Format:''' 00nnbbff

{| |-
!Variable!!Value
|-
|ff||position of vehicle within the consist counted from the engine (front), e.g. the engine would have ff=0, the 1st wagon or mail compartment of planes would have ff=1, the 2nd wagon or the rotor of helicopters would have ff=2, the 3rd wagon would have ff=3 etc
|-
|bb||same as ff, but counted from the end, i.e. the last wagon has bb=0, the next-to-last wagon has bb=1 etc.
|-
|nn||Total number of vehicles in the consist, including shadow and rotor for aircraft.
* In var 40 this is zero-based. That is, the value returned is one less than the actual number of vehicles. A train with engine and three wagons has nn=3.
* In var 41 this is one-based. That is, the value returned is the actual number of vehicles.
|}

For variable 40, these numbers refer to the whole consist, but for variable 41, they only refer to the chain of consecutive vehicles with the same ID as the current wagon (including itself, but possibly excluding the engine):

[[File:vehicle_var40_41.png]]

Note however, that accessing the "related" object (i.e. the locomotive) doesn´t make much sense for vars 40/41, except for var40 when in a [[Callbacks#Can wagon be attached 1D|callback 1D]] chain.

=== Consist cargo (42) ===

'''Format:''' uuiicctt

{| |-
!Variable!!Value
|-
|tt||a bit mask of all [[Action0Cargos#Cargo classes 16|cargo classes]] transported by the consist
|-
|cc||the most common [[CargoTypes|cargo type]] (from the column for type A)
|-
|ii||the most common refit cycle (var. F2) of cargo type cc
|-
|uu||the result of ORing the bits of prop. 25 from all vehicles in the train
|}

If used with VarAction2 type 81 (vehicle) it returns only cargo from this vehicle on, with type 82 (engine) that of the whole consist.
See also variable 47 for more details on the cargo carried by a vehicle.

{{grfTill|7}} For GRF versions 7 and before "cc" is the untranslated bit number from [[Action0/Cargos#Bit_number_for_bitmasks_.2808.29|cargo property 8]].

{{grfFrom|8}} With GRF version 8 the meaning of "cc" changes. If the grf file has installed a [[Action0/Global_Settings#Cargo_translation_table_.2809.29|cargo translation table]], the value in "cc" is the index of the cargo in that table; or FF if the cargo is not present in the table.

=== Player info (43) ===

'''Format:''' Ccttmmnn

{| |-
!Variable!!Value
|-
|nn||the number of the current player from 0 to 7 (up to E (14) in OpenTTD since r14735)
|-
|mm||the multiplayer player number with the host player (or the single player) being 0 and the client player being 1
|-
|tt||the player type, see below for possible values
|-
|c||the primary player colour
|-
|C||{{ottdp|0.6|2.5|ttdprev=r1405}} the secondary player colour, equal to c if none (since r1405)
|}

{| |-
!tt value!!Meaning
|-
|0||Player is human player (permanent company)
|-
|1||Player is AI player (not managed)
|-
|2||{{ottdp|no|2.5}} Player is a human managing an AI company
|-
|3||{{ottdp|no|2.5}} Player is human player's original company, now temporarily AI controlled
|}

{{ottdp|0.6|2.5|ttdprev=r1497}} Since r1497, when the vehicle sprite is being displayed in an exclusive offer window or new vehicle news message, or in other circumstances when no player is associated with the vehicle, nn will be FF.

=== Aircraft info (44) ===

'''Format:''' xxxxhhtt

hh is the height of the aircraft above ground, or more properly above the height of its shadow. Buildings, including the heliport, don't count as "ground", i.e. to get the height above a heliport, you have to subtract the heliport height from hh.

tt is the type of the current airport: 0=small, 1=large, 2=heliport, 3=oil rig. The current airport is the target airport for aircraft that have finished the ascent and are in flight.

=== Curvature info (45) ===

'''Format:''' xxxTxBxF

This returns the amount of curvature between the adjacent wagon pairs. It is useful for train vehicles that normally tilt in curves. The curvature is the difference in direction between the surrounding vehicles:

F = for the front pair (previous wagon to current wagon, 0 if vehicle is first)

B = for the back pair (current wagon to next wagon, 0 if wagon is last)

T = for the triplet (previous wagon to next wagon; is zero in an S-bend)

Possible values:

{| |-
!Decimal!!Hex!!Meaning
|-
| -4||C||180° curve left (T only)
|-
| -3||D||135° curve left (T only)
|-
| -2||E||90° curve left
|-
| -1||F||45° curve left
|-
|0||0||no curve
|-
|1||1||45° curve right
|-
|2||2||90° curve right
|-
|3||3||135° curve right (T only)
|-
|4||4||180° curve right (T only)
|}

=== Motion counter (46) ===

'''Format:''' 32-bit value

This variable counts the amount of motion that a vehicle has done.  It is only valid for the first vehicle in a consist (i.e. use VarAction2 type 82!).  Its value is in units of 1/4096 of a tile.  A vehicle actually moves visibly every time the motion counter increases by 256, and since a tile consists of 16 such subunits, 16*256=4096 motion units mean motion across one tile.

The most useful way to access it is probably with <shiftnum>=08 and an appropriate <andmask>.  For example, to achieve an animation with one frame per vehicle motion and 16 frames in total for motion across an entire tile, you would use <shiftnum>=08 and <andmask>=0F.  For an animation with one frame every two vehicle motions and 4 frames total, use <shiftnum>=09 and <andmask>=03.

If the vehicle is going very fast (>160 mph for trains), it may move by several 1/16ths of a tile at once, and thus some frames may be skipped, but the animation will still remain in sync with the motion.

Note that vehicle graphics are only updated every time the vehicle actually moves, so checking the lower byte is probably pointless, and only needed internally to achieve sufficient precision.

=== Vehicle cargo info (47) ===

'''Format:''' ccccwwtt

{| |-
!Variable!!Value
|-
|tt||the [[CargoTypes|cargo type]] transported by the vehicle (from the column for type A); translated if a translation table has been installed
|-
|ww||cargo unit weight in 1/16 tons, same as [[Action0Cargos#Weight of one unit of the cargo 0F|cargo prop. 0F]]
|-
|cccc||the [[Action0Cargos#Cargo classes 16|cargo class]] value of the cargo transported by the vehicle
|}

Note that if the grf has installed a [[Action0/Global_Settings#Cargo_translation_table_.2809.29|cargo translation table]], the value in "tt" is the slot number in that table, irrespective of which actual slot or bit the cargo is using in the game. If a table has been installed, but the current cargo is not listed there, "tt" will be set to FF.

Unlike variable 42, this variable returns the info of the current vehicle only, not the consist.

=== Vehicle type information (48) ===

'''Format:''' xxxxxxff

The bits of ff are:

{| |-
!Bit!!Value!!Meaning
|-
|0||1||Vehicle type is available on the market
|-
|1||2||Vehicle type is in the testing phase
|-
|2||4||Exclusive testing offer for a human player active
|}

All other bits in ff are undefined and must be masked out.

=== Information about current railtype/roadtype/tramtype (4A) ===

'''Format:''' xxxxFFrr

The lower byte (rr) contains the (translated) railtype/roadtype/tramtype the vehicle is currently driving on.
If the railtype/roadtype/tramtype has no entry in the railtype/roadtype/tramtype translation table of the GRF, this value will be 0xFF.
If no translation table is present, the raw value will be returned.
Note: only exact matches of rail-/road-/-tram-types are reported. If the translation table of the GRF does not contain the exact track-type 0xFF is returned, even if the translation table contains equivalent track-types (according to rail-/road-/tram-type property 1D). Use variable 63 to test for compatibility/poweredness/equivalency with track-types known to both the vehicle and the track-type NewGRF.

The variable only reports about the tracks the vehicle is using: on a level crossing with rail, road and tram tracks, the vehicle (train, road vehicle, tram) can only query the track type it belongs to.

The second byte (FF) contains the following flags:

{| |-
!Bit!!Value!!Meaning
|-
|0||1||The vehicle is/would be powered on the current railtype (this is independent from powered/non-powered wagon or anything)
|-
|1||2||{{ottdp|1.11|no|ottdrev=gf1bc4d840}} Set, if the track-type has catenary. This is independent of the vehicle: a NewGRF can define an engine as powered on non-electrified track (bit 0), and show a raised pantograph (bit 1) to look like a dual-powered engine. This bit is a simplified as it only checks for "some catenary". To distinguish different types of catenaries, AC and DC voltages, ... use variable 63 instead.
|}

All other bits are reserved, and must be masked.

All other bytes are reserved, and must be masked.

=== Position within articulated vehicle (4D) ===

'''Format:''' xxxxbbff

{| |-
!Variable!!Value
|-
|ff||Position of vehicle (articulated part) within the articulated vehicle, counted from the first part, starting with 0.
|-
|bb||Position of vehicle (articulated part) within the articulated vehicle, counted from the last part, starting with 0.
|-
|xx||Reserved, do not access.
|}

The total number of articulated parts of a vehicle equals ff + 1 + bb.

For road vehicles "ff" and "bb" currently equal var 40, since there are no road vehicle wagons yet.

=== Count Veh.ID occurence (60) ===

'''Format:''' xxxxxxnn

The 60+x parameter is the vehicle ID to look for, and the returned nn is the number of vehicles in the consist that have this ID. If used with VarAction2 type 81, only the current vehicle and onwards will be check, with VarAction2 type 82, all vehicles in the consist will be counted.

=== Query variable of n-th vehicle in chain (61) ===

This is a special variable to get the contents of another variable of a different vehicle in the vehicle chain. It is only supported for trains and road vehicles. It is not supported during a callback that is used to modify vehicle properties to avoid circular dependencies, which currently limits this variable to callbacks 1D, 2D, 31 and 32 plus outside callback scope.

Temporary register 10F is interpreted as a signed integer and specifies the offset in the chain from the current vehicle. 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.

The 60+x parameter specifies the variable to access and temporary register 10E is passed as the new 60+x parameter. Passing 61 as the variable is not allowed. Currently only vehicle specific variables listed on this page plus global variable 25 and {{ottdp|1.3|no|ottdrev=r24527}} 5F are accessible through var 61.

The resulting value will have the size of whatever variable is queried.

=== Curvature/position difference for n-th vehicle in chain (62) ===

'''Format:''' zzyyxxFD

This variable is only supported for trains and road vehicles.

The 60+x parameter is interpreted as a signed integer and specifies the offset in the chain from the current vehicle. 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.

The lowest nibble (D) contains the direction difference between the selected vehicle and this vehicle, the possible values are identical to those of [[#Curvature_info_.2845.29|variable 45]].

The next nibble (F) has the following meaning:
{| |-
!Bit!!Value!!Meaning
|-
|3||8||The vehicle is currently hidden
|}

The upper three bytes contain the signed difference of the X/Y/Z position between the selected vehicle and this vehicle.

=== Track-type test against another track-type (63) ===

{{ottdp|1.11|no|ottdrev=g868d84bbf}}

'''Format:''' xxxxxxFF

This variable is only supported for trains and road vehicles.

The 60+x parameter is an index into the rail-/road-/tram-type translation table.
The result value reports how vehicles of this type would behave on the current tile.
This allows vehicles to behave or look differently on various track-types independent of their own track-type.

The lower byte (FF) contains some flags:
{|
|-
!Bit!!Value!!Meaning
|-
|0||1||The track-type from the 60+x parameter is known. If unset, all other flags are unset as well, no information can be given.
|-
|1||2||Vehicles with type from the 60+x parameter are compatible with the track on the current tile.
|-
|2||4||Vehicles with type from the 60+x parameter are powered on the track of the current tile.
|-
|3||8||The track-type from the 60+x parameter is identical or equivalent (listed as alternate label in rail-/road-/tram-type property 1D) to the track-type of the current tile.
|}

The remaining bytes are reserved, and must be masked.

=== Test if rail or road type of the current type occupied by the vehicle has that specific badge attached (65) ===

{{ottdp|15|no}}

This variable only works for trains and road vehicles.
The specifications are the same as for [[#Curvature_info_.2845.29|variable 7A]].

=== Test if the vehicle has that specific badge attached (7A) ===

{{ottdp|15|no}}

The 60+x parameter is the index into the badge table.
The returned value is in range [0, 1].

=== Modflags (FE and FF) ===

The bits in FE mostly relate to gradualloading.  A few useful bits for grf authors are;

{| |-
!Bit!!Version!!Value of the bit
|-
|1||{{ottdp|1.5|2.5|ottdrev=r26430}}||Vehicle is still unloading and has not yet started loading new cargo at the current station.
|-
|5||{{ottdp|0.6|2.5}}||Vehicle is powered (engine or powered wagon, mainly useful for the latter)
|-
|6||{{ottdp|0.6|2.5}}||Vehicle would be powered (engine or powered wagon) if there were suitable track. (E.g. electric train in mixed train on normal track)
|-
|8 <ref>This bit is only accurate for the first vehicle in the consist.</ref>||{{ottdp|0.6|2.5}}||This bit is flipped every time the train reverses direction
|-
|10||{{ottdp|0.6|2.5|ttdprev=r1334}}||Vehicle was built during the exclusive preview
|-
|11 <ref>This bit is only accurate for the first vehicle in the consist.</ref>||{{ottd|16}}||The train is driving backwards (trains only)
|}
<references/>

variable FF is actually the high byte of variable FE, so FE bit 8 is the same as FF bit 0.

Other bits are reserved; most are actually used for TTDPatch internal states.

VariationalAction2/Vehicles

2026-06-05T07:12:57Z

Rito12: Remove empty headers

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

== Variables ==

{|
!Variable!![[GRFActionsDetailed|Size]]!!Version!!Description!!Available in purchase list
|-
|10||D||{{ottdp|1.2|no|ottdrev=r23080}}||Pick sprites for different GUI windows - See [[Action2/Vehicles]].||{{ottdp|1.2|no|ottdrev=r23080}}
|-
|40||D||{{ottdp|0.6|2.5}}||Position in consist and length of consist||no
|-
|41||D||{{ottdp|0.6|2.5}}||Position in and length of chain of consecutive vehicles with same ID||no
|-
|42||D||{{ottdp|0.6|2.5}}||Cargo types transported by consist||no
|-
|43||D||{{ottdp|0.6|2.5}}||Player info||{{ottdp|0.6|2.5|ottdrev=r4611|ttdprev=beta 2}}
|-
|44||D||{{ottdp|0.6|2.5|ttdprev=2.0.1 alpha 48}}||Aircraft info||no
|-
|45||D||{{ottdp|0.6|2.5|ttdprev=2.0.1 alpha 58}}||Curvature info||no
|-
|46||D||{{ottdp|0.6|2.5|ttdprev=2.0.1 alpha 59}}||Motion counter||no
|-
|47||D||{{ottdp|0.6|2.5}}||Vehicle cargo info||{{ottdp|0.7|no|ottdrev=r15542}} <ref name="var47">Variable 47 refers to the default cargo of the vehicle, when in purchase list. This differs from the cargo used in Action 3, which is 0xFF in purchase list. The "refit cycle" (F2) is currently always zero in the purchase list.</ref>
|-
|48||D||{{ottdp|0.6|2.5}}||Vehicle type information||{{ottdp|0.6|2.5|ottdrev=r5338|ttdprev=beta 2}}
|-
|49||D||{{ottdp|0.7|2.6|ottdrev=r13376|ttdprev=r2216}}||Year of construction (long format, 0 based)||{{ottdp|0.7|no|ottdrev=r13376}} <ref name="date">This is the current date</ref>
|-
|4A||D||{{ottdp|1.1|no|ottdrev=r20165}}||Info about current railtype/roadtype/tramtype||no
|-
|4B||D||{{ottdp|1.2|no|ottdrev=r23068}}||Long date of last servicing||{{ottdp|1.2|no|ottdrev=r23068}} <ref name="date" />
|-
|4C||D||{{ottdp|1.3|no|ottdrev=r24246}}||Current max speed including e.g track or timetable speed limits. Only valid for front vehicle. Note, units differ for each vehicle type<ref name="speed">See [[Action0Trains#Speed 09|train property 09]], [[Action0RoadVehicles|road vehicle property 08]] (not 15, even when using realistic acceleration), [[Action0Ships|ship property 0B]] and [[Action0Planes|aircraft property 0C]].</ref>||no
|-
|4D||D||{{ottdp|1.4|no|ottdrev=r26157}}||Position within articulated vehicle||no
|-
|60||D||{{ottdp|0.6|2.5|ttdprev=2.0.1 alpha 57}}||Count Veh.ID occurence||no
|-
|61||-<ref>The size of the result matches the size of the queried variable.</ref>||{{ottdp|1.2|no|ottdrev=r22997}}||Query variable of n-th vehicle in chain||no
|-
|62||D||{{ottdp|1.2|no|ottdrev=r22998}}||Curvature/position difference for n-th vehicle in chain||no
|-
|63||D||{{ottdp|1.11|no|ottdrev=g868d84bbf}}||Test track-type of tile against another track-type||no
|-
|97||B||{{ottdp|0.6|2.0}}||Tick counter, increased every engine tick||no
|-
|B2||W||||Vehicle status: bit0 = vehicle invisible (in tunnel/depot), bit1 = stopped, bit7 = crashed||no
|-
|B4||W||{{ottdp|0.6|2.0}}||Current speed. Note, units differ for each vehicle type<ref name="speed" />||no
|-
|B9||B||{{ottdp|0.6|2.0}}||Cargo type (type B from the list at [[CargoTypes]]; climate dependent)||no
|-
|C0||W||{{ottdp|0.6|2.0}}||Engine age in days {{ottdp|1.2|2.5|ottdrev=r22816|ttdprev=alpha 61}} Valid for wagons and articulated parts as well.||no
|-
|C4||B||{{ottdp|0.6|2.0}}||Year built (counted from 1920), note this is modified when Cht: Year is used||{{ottdp|0.6|no|ottdrev=r4611}} <ref name="date" />
|-
|C6||W||{{ottdp|0.6|2.0}}||Vehicle type ID <ref>{{ottdp|0.7|no}} In OpenTTD 0.7 and newer this is the GRF-local ID of the vehicle. Earlier versions of OpenTTD and TTDPatch report the [[VehicleIDs|TTD ID]]. For trains this is the same; for other vehicle types they differ.</ref> (useful for [[Callbacks#Can wagon be attached (1D)|Callback 1D]])||no
|-
|C8||B||{{ottdp|0.6|2.0}}||Sprite type; FD for trains forward, FE or FF when reversed||no
|-
|C9||B||{{ottdp|0.6|2.0}}||Day counter; increased daily||no
|-
|DA||W||{{ottdp|0.6|2.0}}||Next wagon index, FFFF if last wagon (use shift-num=08 and check for FF)||no
|-
|F2||B||{{ottdp|0.6|2.5}}||Refit cycle, how many times refitted to the same cargo type||{{ottdp|0.7|no|ottdrev=r15542}} <ref name="var47" />
|-
|F4||D||{{ottdp|0.5|2.0|ottdrev=3594}}||Current horsepower of train consist||no
|-
|FE||W||{{ottdp|0.6|2.5}}||Modflags||no
|-
|FF||B||{{ottdp|0.6|2.5}}||Modflags||no
|}

<references />

For other 80+x variables confer the [http://marcin.ttdpatch.net/sv1codec/TTD-locations.html#_VehicleArray TTD vehicle structure].

Variables 40, 41, 42 and 43 are cached. This means that while they are in principle computationally expensive, they can be used without impacting performance. Variables 45 and 60 are also computationally expensive but cannot be cached, and should therefore be used sparingly. If possible 80+x variables are to be preferred.

Cached variables are updated when the game is loaded, when the consist enters or is rearranged in a depot, and when the train reverses.

In the purchase list only a few variables are available. Especially the front vehicle (related object) cannot be accessed, nor other articulated parts.

== Description ==
=== Position and length (40, 41) ===

'''Format:''' 00nnbbff

{| |-
!Variable!!Value
|-
|ff||position of vehicle within the consist counted from the engine (front), e.g. the engine would have ff=0, the 1st wagon or mail compartment of planes would have ff=1, the 2nd wagon or the rotor of helicopters would have ff=2, the 3rd wagon would have ff=3 etc
|-
|bb||same as ff, but counted from the end, i.e. the last wagon has bb=0, the next-to-last wagon has bb=1 etc.
|-
|nn||Total number of vehicles in the consist, including shadow and rotor for aircraft.
* In var 40 this is zero-based. That is, the value returned is one less than the actual number of vehicles. A train with engine and three wagons has nn=3.
* In var 41 this is one-based. That is, the value returned is the actual number of vehicles.
|}

For variable 40, these numbers refer to the whole consist, but for variable 41, they only refer to the chain of consecutive vehicles with the same ID as the current wagon (including itself, but possibly excluding the engine):

[[File:vehicle_var40_41.png]]

Note however, that accessing the "related" object (i.e. the locomotive) doesn´t make much sense for vars 40/41, except for var40 when in a [[Callbacks#Can wagon be attached 1D|callback 1D]] chain.

=== Consist cargo (42) ===

'''Format:''' uuiicctt

{| |-
!Variable!!Value
|-
|tt||a bit mask of all [[Action0Cargos#Cargo classes 16|cargo classes]] transported by the consist
|-
|cc||the most common [[CargoTypes|cargo type]] (from the column for type A)
|-
|ii||the most common refit cycle (var. F2) of cargo type cc
|-
|uu||the result of ORing the bits of prop. 25 from all vehicles in the train
|}

If used with VarAction2 type 81 (vehicle) it returns only cargo from this vehicle on, with type 82 (engine) that of the whole consist.
See also variable 47 for more details on the cargo carried by a vehicle.

{{grfTill|7}} For GRF versions 7 and before "cc" is the untranslated bit number from [[Action0/Cargos#Bit_number_for_bitmasks_.2808.29|cargo property 8]].

{{grfFrom|8}} With GRF version 8 the meaning of "cc" changes. If the grf file has installed a [[Action0/Global_Settings#Cargo_translation_table_.2809.29|cargo translation table]], the value in "cc" is the index of the cargo in that table; or FF if the cargo is not present in the table.

=== Player info (43) ===

'''Format:''' Ccttmmnn

{| |-
!Variable!!Value
|-
|nn||the number of the current player from 0 to 7 (up to E (14) in OpenTTD since r14735)
|-
|mm||the multiplayer player number with the host player (or the single player) being 0 and the client player being 1
|-
|tt||the player type, see below for possible values
|-
|c||the primary player colour
|-
|C||{{ottdp|0.6|2.5|ttdprev=r1405}} the secondary player colour, equal to c if none (since r1405)
|}

{| |-
!tt value!!Meaning
|-
|0||Player is human player (permanent company)
|-
|1||Player is AI player (not managed)
|-
|2||{{ottdp|no|2.5}} Player is a human managing an AI company
|-
|3||{{ottdp|no|2.5}} Player is human player's original company, now temporarily AI controlled
|}

{{ottdp|0.6|2.5|ttdprev=r1497}} Since r1497, when the vehicle sprite is being displayed in an exclusive offer window or new vehicle news message, or in other circumstances when no player is associated with the vehicle, nn will be FF.

=== Aircraft info (44) ===

'''Format:''' xxxxhhtt

hh is the height of the aircraft above ground, or more properly above the height of its shadow. Buildings, including the heliport, don't count as "ground", i.e. to get the height above a heliport, you have to subtract the heliport height from hh.

tt is the type of the current airport: 0=small, 1=large, 2=heliport, 3=oil rig. The current airport is the target airport for aircraft that have finished the ascent and are in flight.

=== Curvature info (45) ===

'''Format:''' xxxTxBxF

This returns the amount of curvature between the adjacent wagon pairs. It is useful for train vehicles that normally tilt in curves. The curvature is the difference in direction between the surrounding vehicles:

F = for the front pair (previous wagon to current wagon, 0 if vehicle is first)

B = for the back pair (current wagon to next wagon, 0 if wagon is last)

T = for the triplet (previous wagon to next wagon; is zero in an S-bend)

Possible values:

{| |-
!Decimal!!Hex!!Meaning
|-
| -4||C||180° curve left (T only)
|-
| -3||D||135° curve left (T only)
|-
| -2||E||90° curve left
|-
| -1||F||45° curve left
|-
|0||0||no curve
|-
|1||1||45° curve right
|-
|2||2||90° curve right
|-
|3||3||135° curve right (T only)
|-
|4||4||180° curve right (T only)
|}

=== Motion counter (46) ===

'''Format:''' 32-bit value

This variable counts the amount of motion that a vehicle has done.  It is only valid for the first vehicle in a consist (i.e. use VarAction2 type 82!).  Its value is in units of 1/4096 of a tile.  A vehicle actually moves visibly every time the motion counter increases by 256, and since a tile consists of 16 such subunits, 16*256=4096 motion units mean motion across one tile.

The most useful way to access it is probably with <shiftnum>=08 and an appropriate <andmask>.  For example, to achieve an animation with one frame per vehicle motion and 16 frames in total for motion across an entire tile, you would use <shiftnum>=08 and <andmask>=0F.  For an animation with one frame every two vehicle motions and 4 frames total, use <shiftnum>=09 and <andmask>=03.

If the vehicle is going very fast (>160 mph for trains), it may move by several 1/16ths of a tile at once, and thus some frames may be skipped, but the animation will still remain in sync with the motion.

Note that vehicle graphics are only updated every time the vehicle actually moves, so checking the lower byte is probably pointless, and only needed internally to achieve sufficient precision.

=== Vehicle cargo info (47) ===

'''Format:''' ccccwwtt

{| |-
!Variable!!Value
|-
|tt||the [[CargoTypes|cargo type]] transported by the vehicle (from the column for type A); translated if a translation table has been installed
|-
|ww||cargo unit weight in 1/16 tons, same as [[Action0Cargos#Weight of one unit of the cargo 0F|cargo prop. 0F]]
|-
|cccc||the [[Action0Cargos#Cargo classes 16|cargo class]] value of the cargo transported by the vehicle
|}

Note that if the grf has installed a [[Action0/Global_Settings#Cargo_translation_table_.2809.29|cargo translation table]], the value in "tt" is the slot number in that table, irrespective of which actual slot or bit the cargo is using in the game. If a table has been installed, but the current cargo is not listed there, "tt" will be set to FF.

Unlike variable 42, this variable returns the info of the current vehicle only, not the consist.

=== Vehicle type information (48) ===

'''Format:''' xxxxxxff

The bits of ff are:

{| |-
!Bit!!Value!!Meaning
|-
|0||1||Vehicle type is available on the market
|-
|1||2||Vehicle type is in the testing phase
|-
|2||4||Exclusive testing offer for a human player active
|}

All other bits in ff are undefined and must be masked out.

=== Information about current railtype/roadtype/tramtype (4A) ===

'''Format:''' xxxxFFrr

The lower byte (rr) contains the (translated) railtype/roadtype/tramtype the vehicle is currently driving on.
If the railtype/roadtype/tramtype has no entry in the railtype/roadtype/tramtype translation table of the GRF, this value will be 0xFF.
If no translation table is present, the raw value will be returned.
Note: only exact matches of rail-/road-/-tram-types are reported. If the translation table of the GRF does not contain the exact track-type 0xFF is returned, even if the translation table contains equivalent track-types (according to rail-/road-/tram-type property 1D). Use variable 63 to test for compatibility/poweredness/equivalency with track-types known to both the vehicle and the track-type NewGRF.

The variable only reports about the tracks the vehicle is using: on a level crossing with rail, road and tram tracks, the vehicle (train, road vehicle, tram) can only query the track type it belongs to.

The second byte (FF) contains the following flags:

{| |-
!Bit!!Value!!Meaning
|-
|0||1||The vehicle is/would be powered on the current railtype (this is independent from powered/non-powered wagon or anything)
|-
|1||2||{{ottdp|1.11|no|ottdrev=gf1bc4d840}} Set, if the track-type has catenary. This is independent of the vehicle: a NewGRF can define an engine as powered on non-electrified track (bit 0), and show a raised pantograph (bit 1) to look like a dual-powered engine. This bit is a simplified as it only checks for "some catenary". To distinguish different types of catenaries, AC and DC voltages, ... use variable 63 instead.
|}

All other bits are reserved, and must be masked.

All other bytes are reserved, and must be masked.

=== Position within articulated vehicle (4D) ===

'''Format:''' xxxxbbff

{| |-
!Variable!!Value
|-
|ff||Position of vehicle (articulated part) within the articulated vehicle, counted from the first part, starting with 0.
|-
|bb||Position of vehicle (articulated part) within the articulated vehicle, counted from the last part, starting with 0.
|-
|xx||Reserved, do not access.
|}

The total number of articulated parts of a vehicle equals ff + 1 + bb.

For road vehicles "ff" and "bb" currently equal var 40, since there are no road vehicle wagons yet.

=== Count Veh.ID occurence (60) ===

'''Format:''' xxxxxxnn

The 60+x parameter is the vehicle ID to look for, and the returned nn is the number of vehicles in the consist that have this ID. If used with VarAction2 type 81, only the current vehicle and onwards will be check, with VarAction2 type 82, all vehicles in the consist will be counted.

=== Query variable of n-th vehicle in chain (61) ===

This is a special variable to get the contents of another variable of a different vehicle in the vehicle chain. It is only supported for trains and road vehicles. It is not supported during a callback that is used to modify vehicle properties to avoid circular dependencies, which currently limits this variable to callbacks 1D, 2D, 31 and 32 plus outside callback scope.

Temporary register 10F is interpreted as a signed integer and specifies the offset in the chain from the current vehicle. 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.

The 60+x parameter specifies the variable to access and temporary register 10E is passed as the new 60+x parameter. Passing 61 as the variable is not allowed. Currently only vehicle specific variables listed on this page plus global variable 25 and {{ottdp|1.3|no|ottdrev=r24527}} 5F are accessible through var 61.

The resulting value will have the size of whatever variable is queried.

=== Curvature/position difference for n-th vehicle in chain (62) ===

'''Format:''' zzyyxxFD

This variable is only supported for trains and road vehicles.

The 60+x parameter is interpreted as a signed integer and specifies the offset in the chain from the current vehicle. 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.

The lowest nibble (D) contains the direction difference between the selected vehicle and this vehicle, the possible values are identical to those of [[#Curvature_info_.2845.29|variable 45]].

The next nibble (F) has the following meaning:
{| |-
!Bit!!Value!!Meaning
|-
|3||8||The vehicle is currently hidden
|}

The upper three bytes contain the signed difference of the X/Y/Z position between the selected vehicle and this vehicle.

=== Track-type test against another track-type (63) ===

{{ottdp|1.11|no|ottdrev=g868d84bbf}}

'''Format:''' xxxxxxFF

This variable is only supported for trains and road vehicles.

The 60+x parameter is an index into the rail-/road-/tram-type translation table.
The result value reports how vehicles of this type would behave on the current tile.
This allows vehicles to behave or look differently on various track-types independent of their own track-type.

The lower byte (FF) contains some flags:
{|
|-
!Bit!!Value!!Meaning
|-
|0||1||The track-type from the 60+x parameter is known. If unset, all other flags are unset as well, no information can be given.
|-
|1||2||Vehicles with type from the 60+x parameter are compatible with the track on the current tile.
|-
|2||4||Vehicles with type from the 60+x parameter are powered on the track of the current tile.
|-
|3||8||The track-type from the 60+x parameter is identical or equivalent (listed as alternate label in rail-/road-/tram-type property 1D) to the track-type of the current tile.
|}

The remaining bytes are reserved, and must be masked.

=== Modflags (FE and FF) ===

The bits in FE mostly relate to gradualloading.  A few useful bits for grf authors are;

{| |-
!Bit!!Version!!Value of the bit
|-
|1||{{ottdp|1.5|2.5|ottdrev=r26430}}||Vehicle is still unloading and has not yet started loading new cargo at the current station.
|-
|5||{{ottdp|0.6|2.5}}||Vehicle is powered (engine or powered wagon, mainly useful for the latter)
|-
|6||{{ottdp|0.6|2.5}}||Vehicle would be powered (engine or powered wagon) if there were suitable track. (E.g. electric train in mixed train on normal track)
|-
|8 <ref>This bit is only accurate for the first vehicle in the consist.</ref>||{{ottdp|0.6|2.5}}||This bit is flipped every time the train reverses direction
|-
|10||{{ottdp|0.6|2.5|ttdprev=r1334}}||Vehicle was built during the exclusive preview
|-
|11 <ref>This bit is only accurate for the first vehicle in the consist.</ref>||{{ottd|16}}||The train is driving backwards (trains only)
|}
<references/>

variable FF is actually the high byte of variable FE, so FE bit 8 is the same as FF bit 0.

Other bits are reserved; most are actually used for TTDPatch internal states.

Action0

2026-05-08T08:33:58Z

Rito12: /* Feature */ Fix last commit.

==Introduction==

Action 0 allows to change the feature properties of 'features', i.e. vehicles, stations, bridges, houses and more.
Each feature has its own very specific properties. These are explained in detail in their separate pages.

You will also find the minimum version requirements for properites on the pages.
Note, that due to the nature of Action 0 unknown properties cannot be ignored. Only a whole Action 0 can be skipped.
OpenTTD and TTDPatch will disable GRFs once they encounter an unknown property. So, if you use some properties for optional features, which you want to disable for older versions of OpenTTD or TTDPatch, you have to skip the Action 0 using [[Action9|Action 9]].

== Syntax ==

The data for Action 0 looks as follows:

<Sprite-number> * <Length> 00 <Feature> <Num-props> <Num-info> <Id> (<Property <New-info>)...

Here is a short overview of what every term means:

{| |-
!Element!![[GRFActionsDetailed|Size]]!!Description
|-
|<Sprite-number> ||dec||A sequential sprite number
|-
|<Length> ||dec||The total number of bytes in the action
|-
|00 ||B||Action type. In this case, 00
|-
|<Feature> ||B||Which type of feature you would like to change
|-
|<Num-props> ||B||How many properties you would like to change per vehicle or station
|-
|<Num-info> ||B||How many vehicles/stations you would like to change
|-
|<Id> ||B*||The ID of the first vehicle/station to change
|-
|<Property> ||B||What property to change for each vehicle/station
|-
|<New-info> ||V||The new value of the property
|}
You can put an Action 0 anywhere after [[Action8|Action 8]] in the GRF file.

{{ottdp|0.6|2.5|ttdprev=2.0.1 alpha 61}} The <Id> is an extended byte since TTDPatch 2.0.1 alpha 61, to support the definition of >255 sound effects.

{{ottdp|0.7|ottdrev=r13482}} {{grf|7|<7}} In OpenTTD since r13482, extended IDs (up to 65535) can be used for vehicles as well. However there is currently a caveat that articulated parts must be below 128.
{{ottdp|1.2}} {{grf|8}} In OpenTTD 1.2, extended IDs (up to 65535) can be used for vehicles as well. The ID for articulated vehicles must be below 16384.

== Descriptions ==

=== Sprite-number ===

Action 0 can appear anywhere in the GRF file, so set it to the sprite number you are currently at.

=== Length ===

The total number of bytes in Action 0. Start counting from <Action>, the bit that sets the pseudo-sprite to act as the specified action.

=== Action ===

The type of action this pseudo-sprites defines. It should be 00 here because we want this pseudo-sprite to act as Action 0.

=== Feature ===

This sets the type of [[Features|feature]] that you wish to change. Set it to:
{|
!Value
!colspan="2"|[[Features|Feature]]
|-
|00 || [[Action0/Vehicles/Trains|Trains]]
|rowspan="4"|[[Action0/Vehicles|Common vehicle properties]]
|-
|01 || [[Action0/Vehicles/RoadVehicles|Road Vehicles]]
|-
|02 || [[Action0/Vehicles/Ships|Ships]]
|-
|03 || [[Action0/Vehicles/Planes|Aircraft]]
|-
|04
|colspan="2"| [[Action0/Stations|Stations]]
|-
|05
|colspan="2"| [[Action0/Canals|Canals]]
|-
|06
|colspan="2"| [[Action0/Bridges|Bridges]]
|-
|07
|colspan="2"| [[Action0/Houses|Houses]] (see [[DefaultHouseProps|defaults]])
|-
|08
|colspan="2"| [[Action0/Global Settings|Global Settings]]
|-
|09
|colspan="2"| [[Action0/Industry Tiles|Industry Tiles]] (see [[IndustryTileDefaultProps|defaults]])
|-
|0A
|colspan="2"| [[Action0/Industries|Industries]] (see [[IndustryDefaultProps|defaults]])
|-
|0B
|colspan="2"| [[Action0/Cargos|Cargos]] (see [[CargoDefaultProps|defaults]])
|-
|0C
|colspan="2"| [[Action0/Sound Effects|Sound Effects]]
|-
|0D
|colspan="2"| [[Action0/Airports|Airports]]
|-
|0F
|colspan="2"| [[Action0/Objects|Objects]]
|-
|10
|colspan="2"| {{ottdp|1.0|no|ottdrev=r18969}} [[Action0/Railtypes|Rail Types]]
|-
|11
|colspan="2"| {{ottdp|1.1|no|ottdrev=r19204}} [[Action0/Airport Tiles|Airport Tiles]]
|-
|12
|colspan="2"| {{ottdp|1.10|no|ottdrev=gc02ef3e456}} [[Action0/Roadtypes|Road Types]]
|-
|13
|colspan="2"| {{ottdp|1.10|no|ottdrev=gc02ef3e456}} [[Action0/Tramtypes|Tram Types]]
|-
|14
|colspan="2"| {{ottdp|14|no|ottdrev=g4c1406a4b5}} [[Action0/Road Stops|Road Stops]]
|-
|15
|colspan="2"| {{ottdp|15|no|ottdrev=g8f14894024}} [[Action0/Badges|Badges]]
|}

=== Num-props ===

This is the number of properties that you wish to change per vehicle or station. Note: even if you wish to set the same properties to the same value for different vehicles then you must still repeat the properties and their values for each vehicle.

=== Num-info ===

Simply the number of vehicles that you will change using this action 0.

=== Id ===
The [[VehicleIDs|Vehicle ID]] of the first vehicle or station to change. If num-info is greater than one, this vehicle/station and the following vehicles/stations will be changed.

=== Property ===

The number of the property that will be changed. This and the New-info section are repeated as many times as there are properties to set; in total, there are <
num-props> property bytes.

See relevant sub-section (links at the bottom) for more details.

=== New-info ===

The new information that will replace the previous information for the specified property. This is a variable size; dependent upon the property. Each property byte is followed by <num-info> new-info sections.
The appropriate \b, \w, and \d escape sequences can be quite useful for most <
new-info>s. See [[GRFActionsDetailed#Byte order|the discussion of escape sequences]] for further information.

==Example==

Action0

2026-05-08T08:32:56Z

Rito12: /* Feature */ Make "types" separate word.

==Introduction==

Action 0 allows to change the feature properties of 'features', i.e. vehicles, stations, bridges, houses and more.
Each feature has its own very specific properties. These are explained in detail in their separate pages.

You will also find the minimum version requirements for properites on the pages.
Note, that due to the nature of Action 0 unknown properties cannot be ignored. Only a whole Action 0 can be skipped.
OpenTTD and TTDPatch will disable GRFs once they encounter an unknown property. So, if you use some properties for optional features, which you want to disable for older versions of OpenTTD or TTDPatch, you have to skip the Action 0 using [[Action9|Action 9]].

== Syntax ==

The data for Action 0 looks as follows:

<Sprite-number> * <Length> 00 <Feature> <Num-props> <Num-info> <Id> (<Property <New-info>)...

Here is a short overview of what every term means:

{| |-
!Element!![[GRFActionsDetailed|Size]]!!Description
|-
|<Sprite-number> ||dec||A sequential sprite number
|-
|<Length> ||dec||The total number of bytes in the action
|-
|00 ||B||Action type. In this case, 00
|-
|<Feature> ||B||Which type of feature you would like to change
|-
|<Num-props> ||B||How many properties you would like to change per vehicle or station
|-
|<Num-info> ||B||How many vehicles/stations you would like to change
|-
|<Id> ||B*||The ID of the first vehicle/station to change
|-
|<Property> ||B||What property to change for each vehicle/station
|-
|<New-info> ||V||The new value of the property
|}
You can put an Action 0 anywhere after [[Action8|Action 8]] in the GRF file.

{{ottdp|0.6|2.5|ttdprev=2.0.1 alpha 61}} The <Id> is an extended byte since TTDPatch 2.0.1 alpha 61, to support the definition of >255 sound effects.

{{ottdp|0.7|ottdrev=r13482}} {{grf|7|<7}} In OpenTTD since r13482, extended IDs (up to 65535) can be used for vehicles as well. However there is currently a caveat that articulated parts must be below 128.
{{ottdp|1.2}} {{grf|8}} In OpenTTD 1.2, extended IDs (up to 65535) can be used for vehicles as well. The ID for articulated vehicles must be below 16384.

== Descriptions ==

=== Sprite-number ===

Action 0 can appear anywhere in the GRF file, so set it to the sprite number you are currently at.

=== Length ===

The total number of bytes in Action 0. Start counting from <Action>, the bit that sets the pseudo-sprite to act as the specified action.

=== Action ===

The type of action this pseudo-sprites defines. It should be 00 here because we want this pseudo-sprite to act as Action 0.

=== Feature ===

This sets the type of [[Features|feature]] that you wish to change. Set it to:
{|
!Value
!colspan="2"|[[Features|Feature]]
|-
|00 || [[Action0/Vehicles/Trains|Trains]]
|rowspan="4"|[[Action0/Vehicles|Common vehicle properties]]
|-
|01 || [[Action0/Vehicles/RoadVehicles|Road Vehicles]]
|-
|02 || [[Action0/Vehicles/Ships|Ships]]
|-
|03 || [[Action0/Vehicles/Planes|Aircraft]]
|-
|04
|colspan="2"| [[Action0/Stations|Stations]]
|-
|05
|colspan="2"| [[Action0/Canals|Canals]]
|-
|06
|colspan="2"| [[Action0/Bridges|Bridges]]
|-
|07
|colspan="2"| [[Action0/Houses|Houses]] (see [[DefaultHouseProps|defaults]])
|-
|08
|colspan="2"| [[Action0/Global Settings|Global Settings]]
|-
|09
|colspan="2"| [[Action0/Industry Tiles|Industry Tiles]] (see [[IndustryTileDefaultProps|defaults]])
|-
|0A
|colspan="2"| [[Action0/Industries|Industries]] (see [[IndustryDefaultProps|defaults]])
|-
|0B
|colspan="2"| [[Action0/Cargos|Cargos]] (see [[CargoDefaultProps|defaults]])
|-
|0C
|colspan="2"| [[Action0/Sound Effects|Sound Effects]]
|-
|0D
|colspan="2"| [[Action0/Airports|Airports]]
|-
|0F
|colspan="2"| [[Action0/Objects|Objects]]
|-
|10
|colspan="2"| {{ottdp|1.0|no|ottdrev=r18969}} [[Action0/Rail Types|Railtypes]]
|-
|11
|colspan="2"| {{ottdp|1.1|no|ottdrev=r19204}} [[Action0/Airport Tiles|Airport Tiles]]
|-
|12
|colspan="2"| {{ottdp|1.10|no|ottdrev=gc02ef3e456}} [[Action0/Road Types|Roadtypes]]
|-
|13
|colspan="2"| {{ottdp|1.10|no|ottdrev=gc02ef3e456}} [[Action0/Tram Types|Tramtypes]]
|-
|14
|colspan="2"| {{ottdp|14|no|ottdrev=g4c1406a4b5}} [[Action0/Road Stops|Road Stops]]
|-
|15
|colspan="2"| {{ottdp|15|no|ottdrev=g8f14894024}} [[Action0/Badges|Badges]]
|}

=== Num-props ===

This is the number of properties that you wish to change per vehicle or station. Note: even if you wish to set the same properties to the same value for different vehicles then you must still repeat the properties and their values for each vehicle.

=== Num-info ===

Simply the number of vehicles that you will change using this action 0.

=== Id ===
The [[VehicleIDs|Vehicle ID]] of the first vehicle or station to change. If num-info is greater than one, this vehicle/station and the following vehicles/stations will be changed.

=== Property ===

The number of the property that will be changed. This and the New-info section are repeated as many times as there are properties to set; in total, there are <
num-props> property bytes.

See relevant sub-section (links at the bottom) for more details.

=== New-info ===

The new information that will replace the previous information for the specified property. This is a variable size; dependent upon the property. Each property byte is followed by <num-info> new-info sections.
The appropriate \b, \w, and \d escape sequences can be quite useful for most <
new-info>s. See [[GRFActionsDetailed#Byte order|the discussion of escape sequences]] for further information.

==Example==

Badge labels

2026-04-19T21:49:08Z

Rito12: /* Introduction */ Update link.

{{NMLNavBlocksyntax}}

== Introduction ==
This page is dedicated for tracking registered badge labels.
If you write or publish a NewGRF which introduces a new badge label, please also add comment about it here.
However, before you introduces a new label reconsider if any of available labels fulfills the same purpose. Do not introduces two or more labels for same purpose.
If you introduce a new class, please also provide a table for badges that belong to it.
For ease of maintenance keep alphabetical order.

'''Note:''' This page is maintained manually and some grf developers oppose to that despicable labor. Therefore you might also want to visit https://github.com/Rito13/BaNaNaS-get_badge_labels/blob/main/gen_docs%2Fbadges%2Fpublic_labels.md, which is updated automatically with content uploaded to BaNaNaS.

== Classes ==

{| class="wikitable sortable"
! Label !! Introduced by !! Comment
|-
| flag || OpenTTD default badges || Country/Region
|-
| livery || OpenTTD default badges || Livery
|-
| power || OpenTTD default badges || Propulsion
|-
| region || OpenTTD default badges || Region
|-
| role || OpenTTD default badges || Role
|-
| zone || OpenTTD default badges || Zone
|}

== Badges ==

=== Flag ===
{| class="wikitable sortable"
! Label !! Introduced by !! Comment
|-
| flag/AD || OpenTTD default badges || Andorra
|}

=== Livery ===
{| class="wikitable sortable"
! Label !! Introduced by !! Comment
|-
| livery/2cc || OpenTTD default badges || Dual company colour (2CC)
|-
| livery/random/1cc || OpenTTD default badges || Random based on first company colour
|-
| livery/random/2cc || OpenTTD default badges || Random based on second company colour
|}

=== Power ===
{| class="wikitable sortable"
! Label !! Introduced by !! Comment
|-
| power/battery || OpenTTD default badges || Battery
|-
| power/diesel || OpenTTD default badges || Diesel
|-
| power/electric || OpenTTD default badges || Electric
|-
| power/electric/ac || OpenTTD default badges || Electric (AC)
|-
| power/electric/dc || OpenTTD default badges || Electric (DC)
|-
| power/steam || OpenTTD default badges || Steam
|-
| power/turbine || OpenTTD default badges || Gas Turbine
|}

=== Region ===
{| class="wikitable sortable"
! Label !! Introduced by !! Comment
|-
| region/africa || OpenTTD default badges || Africa
|-
| region/africa/eastern || OpenTTD default badges || Eastern Africa
|-
| region/africa/middle || OpenTTD default badges || Middle Africa
|-
| region/africa/northern || OpenTTD default badges || Northern Africa
|-
| region/africa/southern || OpenTTD default badges || Southern Africa
|-
| region/africa/western || OpenTTD default badges || Western Africa
|-
| region/america || OpenTTD default badges || Americas
|-
| region/america/caribbean || OpenTTD default badges || Caribbean
|-
| region/america/central || OpenTTD default badges || Central America
|-
| region/america/northern || OpenTTD default badges || Northern America
|-
| region/america/south || OpenTTD default badges || South America
|-
| region/asia || OpenTTD default badges || Asia
|-
| region/asia/central || OpenTTD default badges || Central Asia
|-
| region/asia/eastern || OpenTTD default badges || Eastern Asia
|-
| region/asia/southeastern || OpenTTD default badges || South-eastern Asia
|-
| region/asia/southern || OpenTTD default badges || Southern Asia
|-
| region/asia/western || OpenTTD default badges || Western Asia
|-
| region/europe || OpenTTD default badges || Europe
|-
| region/europe/eastern || OpenTTD default badges || Eastern Europe
|-
| region/europe/northern || OpenTTD default badges || Northern Europe
|-
| region/europe/southern || OpenTTD default badges || Southern Europe
|-
| region/europe/western || OpenTTD default badges || Western Europe
|-
| region/oceania || OpenTTD default badges || Oceania
|-
| region/oceania/australia_and_new_zealand || OpenTTD default badges || Australia and New Zealand
|-
| region/oceania/melanesia || OpenTTD default badges || Melanesia
|-
| region/oceania/micronesia || OpenTTD default badges || Micronesia
|-
| region/oceania/polynesia || OpenTTD default badges || Polynesia
|}

=== Role ===
{| class="wikitable sortable"
! Label !! Introduced by !! Comment
|-
| role/banking || OpenTTD default badges || Banking
|-
| role/express_freight || OpenTTD default badges || Express freight
|-
| role/express_passenger || OpenTTD default badges || Express passenger
|-
| role/freight || OpenTTD default badges || Freight
|-
| role/heavy_freight || OpenTTD default badges || Heavy freight
|-
| role/light_freight || OpenTTD default badges || Light freight
|-
| role/mail || OpenTTD default badges || Mail
|-
| role/mixed || OpenTTD default badges || Mixed
|-
| role/passenger || OpenTTD default badges || Passenger
|-
| role/prototype || OpenTTD default badges || Prototype
|-
| role/restaurant_car || OpenTTD default badges || Restaurant car
|-
| role/shunting || OpenTTD default badges || Shunting
|-
| role/snowplough || OpenTTD default badges || Snowplough
|-
| role/utility || OpenTTD default badges || Utility
|}

=== Zone ===
{| class="wikitable sortable"
! Label !! Introduced by !! Comment
|-
| zone/agricultural || OpenTTD default badges || Agricultural
|-
| zone/com || OpenTTD default badges || Commercial
|-
| zone/com/high || OpenTTD default badges || High density commercial
|-
| zone/com/low || OpenTTD default badges || Low density commercial
|-
| zone/com/medium || OpenTTD default badges || Medium density commercial
|-
| zone/forestry || OpenTTD default badges || Forestry
|-
| zone/general || OpenTTD default badges || General
|-
| zone/ind || OpenTTD default badges || Industrial
|-
| zone/ind/high || OpenTTD default badges || High density industrial
|-
| zone/ind/low || OpenTTD default badges || Low density industrial
|-
| zone/ind/medium || OpenTTD default badges || Medium density industrial
|-
| zone/leisure || OpenTTD default badges || Leisure
|-
| zone/mixed || OpenTTD default badges || Commercial & residential
|-
| zone/mixed/high || OpenTTD default badges || High density commercial & residential
|-
| zone/mixed/low || OpenTTD default badges || Low density commercial & residential
|-
| zone/mixed/medium || OpenTTD default badges || Medium density commercial & residential
|-
| zone/other || OpenTTD default badges || Other
|-
| zone/public || OpenTTD default badges || Public
|-
| zone/res || OpenTTD default badges || Residential
|-
| zone/res/high || OpenTTD default badges || High density residential
|-
| zone/res/low || OpenTTD default badges || Low density residential
|-
| zone/res/medium || OpenTTD default badges || Medium density residential
|-
| zone/transport || OpenTTD default badges || Transport
|}

NML:Badges

2026-04-15T14:34:13Z

Rito12: Add nml since.

{{NMLNavPropVarCB}}

'''Since''' {{ottd|15.0}} {{nml|0.9.0}}

item (FEAT_BADGES, item_name) { ... }

==Badge properties==

{| class="wikitable sortable"
! property
! value range
! comment
|-
| label
| string with <code style="color:green">/</code> as delimiter
| ''' For sake of compatibility and user experience, consider using [[NML:Badge labels|labels already introduced]] by other NewGRFs.'''
Badges with label without <code style="color:green">/</code> are considered to be classes.
Labels for other badges should match following syntax:
<code style="color:green">"label_of_class_they_belong_to/label_for_the_badge"</code>
|-
| name
| string
| Name of this badge or badge class.
|-
| flags
| bitmask(BADGE_FLAG_XXX, ...);
|
; COPY_TO_RELATED_ENTITY
: Badge can be copied to related entity (e.g. badge on a railtype can be copied to rail vehicles of that railtype.)
; NAME_LIST_STOP
: Stops adding more names to the visible name list.
; NAME_LIST_FIRST_ONLY
: Add this name to the visible name list only if this is the first name.
; USE_COMPANY_COLOUR
: Recolour badge depending on company that player currently controls.
; NAME_SKIP
: Allow the badge to be excluded from the badge name list.
|}

== Badge variables ==

{| class="wikitable sortable"
! name
! value range
! comment
|-
| intro_date
| date(yyyy, mm, dd)
| Introduction date of entity (or current date if entity type does not have an introduction date). See <code style="color: green">introduction_date</code> in [[NML:Vehicles#Properties common to all vehicle types|vehicle properties]].
|}

== Badge callbacks ==

'''Note: By design badges are meant to only be up to 12 pixels tall.'''

{| class="wikitable sortable"
! callback
! return value
! comment
|-
| default
| spriteset
| Graphics for the badge or badge class.
|-
|
aircraft 
airports 
airporttiles 
houses 
industries 
industrytiles 
objects 
railtypes 
roadstops 
roadtypes 
roadvehs 
ships 
stations 
trains 
tramtypes 
| spriteset
| Override default graphics when used by other specific feature.
|}

== Prerequisites ==

Badges require a [[NML:Badgetable|badgetable]] to be defined for most common usage scenarios (eg to refer to a badge from an item block). This is not a hard requirement and can be omitted if you are, for example, creating badges that other newGRFs can later refer to

Eg for <code style="color:green">power/diesel</code> to be used in the badges property for a vehicle, the badge table must contain entries for both <code style="color:green">power</code> and <code style="color:green">power/diesel</code>

== Example code ==

<pre style="color:blue">

badgetable {
"power",
"power/diesel",
"power/steam"
}

item (FEAT_BADGES, power) {
property {
label: "power";
name: string(STR_POWER);
}
}

# This badge will not show a sprite in the purchase menu
item (FEAT_BADGES, diesel) {
property {
label: "power/diesel";
name: string(STR_POWER_DIESEL);
}
}

# This badge will show a sprite in the purchase menu
item (FEAT_BADGES, steam) {
property {
label: "power/steam";
name: string(STR_POWER_STEAM);
}
graphics {
default: sprite_steam;
}
}
</pre>

NML:Stations

2026-04-15T14:31:53Z

Rito12: /* Station properties */ Litle tweaks.

{{NMLNavPropVarCB}}
Stations are supported since {{nml|0.7}}.

==Station sections==

Stations can be built from multiple sections. Station tiles will remember, which tiles were built together in one action.
* Building a 2x5 station in one action creates a single station section of size 2x5.
* Building a 2x5 station by placing two 1x5 areas next to each other in two actions creates two station sections of size 1x5; even when using the same station type from the same NewGRF.

[[File:station_sections.png|800px]]

Overbuilding stations and removing station tiles will remove tiles from station sections.
* On construction all station sections are contiguous rectangular NxM tile ares. (regular station section)
* When tiles are overbuilt or tiles are removed, station sections may end up non-rectangular and non-contiguous. (irregular station section)
Station tiles can query their position inside a contiguous line of tiles from the same section.
* This is great as long as the section remains regular.
* If tiles are non-contiguous, they are indistinguishable from tiles of other sections.

For irregular sections the "position" inside the section will become rather arbitrary.
The picture shows the perspective of each tile of a irregular section as "(platform, position)/(num-platforms, length)":

[[File:station_sections_irregular.png|800px]]

==Tile types==

When station sections are built, they can store a "tile type" for each tile using the <code style="color:darkgreen">select_tile_type</code> callback.

Tile types have multiple usages:
* The type can be read via the <code style="color:darkgreen">tile_type</code> variable, and can act as persistent storage.
* It decides whether the tile is traversible by trains, or whether it is a building without tracks.
* It decides whether catenary pylons and/or wires shall be drawn/hidden on the tile. Note: even non-track station buildings have a rail type, and can draw catenary.

The tile type is immutable after construction. So, unlike the platform/position information, the tile type will never change after construction, even if tiles of the station section are removed or overbuilt.

The number of tile types is quite limited: 4 per orientation, 8 in total.
'''Note:''' Since {{ottd|15.0}} {{nml|0.7.6}} it is possible to register up to 256 tile types.
* Tile types 0, 2, 4 and 6 are used for station sections with tracks in X direction (⤢).
* Tile types 1, 3, 5 and 7 are used for station sections with tracks in Y direciton (⤡).
* Callback <code style="color:darkgreen">select_tile_type</code> decides between the pairs (0,1), (2,3), (4,5), (6,7) during construction. The orientation is always picked by the player.

==Station properties==

{| class="wikitable sortable"
! property
! value range
! comment
|-
| class
| String literal of length 4
|
'''This property ''must'' be set first, before any other properties or graphics.''' 
Stations belonging to the same class are grouped in the GUI. 
There is one special class:
* "WAYP": The station type will be shown in the waypoint construction window, instead of the station construction window.
{{ottdp|15.0}} Station classes which start with the byte FF are considered waypoint classes, and will appear in the waypoint construction window instead of the station construction window.
|-
| classname
| string
| You only need to set this for one station in every class.
|-
| name
| string
| For example: string(STR_50S_STATION)
|-
| disabled_platforms disabled_length
| bitmask(1, 2, 3, 4, 5, 6, 7, 8)
|
Restricts the possible number-of-platforms and platform-lengths the player can build as one section.
* Sizes 1 to 7 can be disabled individually,
* "size 8" is used for anything bigger than 7.
To put restrictions on sizes bigger than 7 (for example, only allow even sizes), you can use callback <code style="color:darkgreen">tile_check</code>.
 Note: Players can remove single tiles from any station, so stations sections can end up with forbidden sizes anyway.
|-
| cargo_threshold
| 0..4095
| Threshold between <code style="color:darkgreen">little</code> and <code style="color:darkgreen">lots</code> spritesets, see [[NML:Spritegroup#Stations|spritegroup]] for details.
|-
| draw_pylon_tiles hide_wire_tiles non_traversable_tiles 
| bitmask(0, 1, 2, 3, 4, 5, 6, 7)
| '''Deprecated since '''{{nml|0.7.6}}''' , replaced by '''<code style="color:darkgreen">tile_flags</code>'''.''' 
Specifies which [[#Tile_types|tile types]] are traversible/non-traversible, and whether pylons and/or catenary shall be drawn for electrified rail types.
Note: it is common that all tile types behave the same, you may want to use the short cuts
* <code style="color:darkgreen">0</code> for no tile types, and
* <code style="color:darkgreen">STAT_ALL_TILES</code> for all tile types.
|-
| cargo_random_triggers
| Array of cargo labels from the [[NML:Cargotable|cargotable]]
| Cargo types, which will [[NML:Random_switch#Stations|trigger re-randomization]] when delivered, loaded or unloaded at the station.
|-
| general_flags
| bitmask(STAT_FLAG_XXX, STAT_FLAG_YYY, ...)
|
;STAT_FLAG_DISTRIBUTED_CARGO_BY_PERIMETER {{nml|0.9.0}}
:Specifies whether waiting cargo amounts are scaled by station '''perimeter''' for spriteset selection, see [[NML:Spritegroup#Stations|spritegroup]] for details.
:Since {{ottd|16.0}} if <code style="color:darkgreen">STAT_FLAG_DISTRIBUTED_CARGO_BY_AREA</code> is also set it does not do anything.
;STAT_FLAG_DISTRIBUTED_CARGO_BY_AREA {{ottd|16.0}} {{nml|0.9.0}}
:Specifies whether waiting cargo amounts are scaled by station '''area''' for spriteset selection, see [[NML:Spritegroup#Stations|spritegroup]] for details.
;STAT_FLAG_RANDOM_ANIMATION
:If set, callback <code style="color:darkgreen">anim_next_frame</code> will get random data in <code style="color:darkgreen">extra_callback_info1</code>
;STAT_FLAG_CUSTOM_FOUNDATIONS
:Enables callback <code style="color:darkgreen">foundations</code>, see below.
;STAT_FLAG_EXTENDED_FOUNDATIONS
:Selects between two possible spriteset formats for callback <code style="color:darkgreen">foundations</code>, see below.
;STAT_FLAG_DISTRIBUTED_CARGO
:Deprecated since {{nml|0.9.0}}.
|-
| 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(STAT_ANIM_XXX, ANIM_TRIGGER_STAT_YYY, ...)
| Enables callback <code style="color:darkgreen">anim_control</code> for specified triggers:
;STAT_ANIM_IS_BUILT
:Tile is built. (all new-built/overbuilt tiles)
;STAT_ANIM_CARGO_ARRIVES
:Cargo is deliverd from industry to station. (all station tiles)
;STAT_ANIM_CARGO_REMOVED
:All cargo was loaded onto a vehicle, no more cargo (of this type) is waiting. (all station tiles)
;STAT_ANIM_TRAIN_ENTERS
:Train stops at station. (all tiles of platform)
;STAT_ANIM_TRAIN_LEAVES
:Train leaves station. (all tiles of platform)
;STAT_ANIM_TRAIN_LOAD_UNLOAD
:Train is loading or unloading. (all tiles of platform)
;STAT_ANIM_250_TICKS
:Every 250 ticks. (synchronized for all tiles of the station)
;{{ottd|15.0}} ANIM_TRIGGER_STAT_TILELOOP
:Tile is processed in the periodic processing loop
;{{ottd|15.0}} ANIM_TRIGGER_STAT_TRAIN_RESERVES
:Train reserves platform (using PBS)
|-
| badges
| Array of badge labels from the [[NML:Badgetable|badgetable]].
| Since {{ottd|15.0}}
|-
| tile_flags
| Array of <code>bitmask(STAT_TILE_XXX, ...)</code>
| Since {{ottd|15.0}} {{nml|0.7.6}} 
Each element of array corresponds to one tile type. Array should always have even number of elements. 
'''XXX''' should be replaced by one of the following:
; PYLON
: Draw pylon on tile with that type.
; NOWIRE
: Hide wire on tile with that type.
; BLOCKED
: Do not allow trains to enter tile with that type.
|}

==Station variables==

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

{| class="wikitable sortable"
! name
! value range
! comment
|-
| random_bits_station
| 0..65535
| 16 random bits, shared between all station sections (rail station sections, airports, ...)
|-
| 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="wikitable sortable"
! 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="wikitable sortable"
! name
! value range
! comment
|-
| tile_type
| 0..7
; 0..255 {{ottd|15.0}}
| The type of tile, as decided by <code style="color:darkgreen">select_tile_type</code>. Bit 0 also tells the orientation.
|-
| 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.
|-
| random_bits_tile
| 0..15
| 4 random bits, specific to this station 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="wikitable sortable"
! 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_grfid
| tile- and platform-offset <ref name="offset"/>
| 32-bit GRFID
| GRFID of the NewGRF defining the given station tile.
|-
| 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_tile_type
| tile- and platform-offset <ref name="offset"/>
| 0..7
; 0..255 {{ottd|15.0}}
| [[#Tile_types|Tile type]] of the given tile. The orientation bit is adjusted to be relative to the current tile's orientation:
* 0, 2, 4, 6: Tracks are parallel.
* 1, 3, 5, 7: Tracks are perpendicular.
|-
| 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 [[#Station_sections|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.
|-
| has_badge
| Label from the [[NML:Badgetable|badgetable]].
| [0 <nowiki>|</nowiki> 1]
| {{ottd|15.0}} Check if the rail station has that specific badge attached.
|}
<references/>

==Station callbacks==

The following table contains a list of available station 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 cargo is waiting at the station. If multiple cargo types are waiting at the station, OpenTTD will pick one of the options the station provides.
If none of the listed cargo types is waiting at the station, the <code style="color:darkgreen">default</code> callback will be used.

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="wikitable sortable"
! callback
! return value
! comment
|-
| default
| spritegroup
| See [[#Graphics|below]].
|-
| purchase
| spritegroup or spriteset
| See [[#Graphics|below]]. If a spritegroup is linked instead of a spriteset, the "zero cargo amount" spriteset is used.
|-
| custom_spritesets
| Array of spritesets
| See [[#Graphics|below]].
|-
| sprite_layouts
| Array of spritelayouts
| See [[#Graphics|below]]. The number of sprite_layouts must be even, alternating X (⤢) and Y (⤡) orientations.
|-
| select_sprite_layout
| index into sprite_layouts[]
| See [[#Graphics|below]]. The result's even-/oddness is ignored. The orientation is always adjusted by OpenTTD.
|-
| purchase_select_sprite_layout
| index into sprite_layouts[]
| See [[#Graphics|below]]. The result's even-/oddness is ignored. The orientation is always adjusted by OpenTTD.
|-
| prepare_layout
| expression list
| See [[#Graphics|below]].
|-
| purchase_prepare_layout
| expression list
| See [[#Graphics|below]].
|-
| foundations
| sprite set
| See [[#foundations|below]].
|-
| availability
| [0 <nowiki>|</nowiki> 1]
| Return 1 to make the station show up in the build window
|-
| tile_check
| Same as for the [[NML:IndustryTiles#Location check results|location_check]] industry callback
| Decide whether station may be built on this tile. This is an additional check to all built-in checks (like slope checks), you can only further restrict construction, not lessen conditions.

Called before constructing the station section, so nothing exists on the map yet. Since the station isn't built yet, so you can't access station variables.
Only these variables are available: company-information, and the class, height, slope, terrain type and water status of nearby tiles.
* <code style="color:darkgreen">getbits(extra_callback_info1, 4, 4)</code>: The [[NML:List_of_tile_slopes|tile slope]] of the tile.
* <code style="color:darkgreen">getbits(extra_callback_info1, 0, 4)</code>: The [[NML:List_of_tile_slopes|tile slope]] of the tile, adjusted by station orientation:
** unmodified in X direction (⤢)
** mirrored in Y direction (⤡)
* <code style="color:darkgreen">getbits(extra_callback_info2, 0, 8)</code>: Tile position along the new-built platform. (0 = north tile)
* <code style="color:darkgreen">getbits(extra_callback_info2, 8, 8)</code>: Platform number within the new-built section. (0 = north platform)
* <code style="color:darkgreen">getbits(extra_callback_info2, 16, 8)</code>: Length of the new section being built.
* <code style="color:darkgreen">getbits(extra_callback_info2, 24, 8)</code>: Number of platforms in the new section being built.

|-
| select_tile_type
| [0 <nowiki>|</nowiki> 2 <nowiki>|</nowiki> 4 <nowiki>|</nowiki> 6]

Since {{ottdp|15}}, even values up to FE can be returned as long as the tile is defined.
| Decides which tile type to store for each tile during construction. The lowest bit is always defined by the station orientation, no matter the callback result. See also [[#Tile_types|tile type above]].

Called before constructing the station section, so nothing exists on the map yet. Since the station isn't built yet, so you can't access station variables.
Only these variables are available: company-information, and the class, height, slope, terrain type and water status of nearby tiles.
* <code style="color:darkgreen">getbits(extra_callback_info1, 0, 4)</code>: Tile position along the new-built platform. (0 = north tile)
* <code style="color:darkgreen">getbits(extra_callback_info1, 4, 4)</code>: Tile position along the new-built platform. (0 = south tile)
* <code style="color:darkgreen">getbits(extra_callback_info1, 8, 4)</code>: Platform number within the new-built section. (0 = north platform)
* <code style="color:darkgreen">getbits(extra_callback_info1, 12, 4)</code>: Platform number within the new-built section. (0 = south platform)
* <code style="color:darkgreen">getbits(extra_callback_info1, 16, 4)</code>: Length of the new section being built.
* <code style="color:darkgreen">getbits(extra_callback_info1, 20, 4)</code>: Number of platforms in the new section being built.
* <code style="color:darkgreen">getbits(extra_callback_info1, 24, 8)</code>: Original tile type in static layout.

|-
| 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>: 32 random bits, if enabled in the <code style="color:darkgreen">general_flags</code> property.
Returning a sound effect in the high byte will cause that sound effect to be played.

Note: Every time the animation frame is changed the map tile will be refreshed, even if the selected graphics stay the same. Therefore using the animation frame as a timer should be avoided, and animation triggers should be preferred instead.
|-
| anim_control
| Next animation frame or CB_RESULT_XXX
|
Called whenever an animation trigger happens. Return the animation frame to show, or CB_RESULT_XXX with XXX = [CB_RESULT_START_ANIMATION <nowiki>|</nowiki> STOP_ANIMATION <nowiki>|</nowiki> DO_NOTHING] to respectively start the animation in its current frame, stop the animation or do nothing. Returning a sound effect in the high byte will cause that sound effect to be played.
* <code style="color:darkgreen">extra_callback_info1</code>: 32 random bits. The low 16 bits are always different for each station tile, but the high 16 bits are the same for all triggered tiles.
* <code style="color:darkgreen">getbits(extra_callback_info2, 0, 8)</code>: Reason for the callback trigger (STAT_ANIM_xxx). Note that you need to enable the wanted triggers in the <code style="color:darkgreen">animation_triggers</code> property.
* <code style="color:darkgreen">getbits(extra_callback_info2, 8, 8)</code>: Cargo-type involved in the trigger. Only applies to STAT_ANIM_CARGO_ARRIVES, STAT_ANIM_CARGO_REMOVED, STAT_ANIM_TRAIN_LOAD_UNLOAD.
Note: Every time the animation frame is changed the map tile will be refreshed, even if the selected graphics stay the same. Therefore using the animation frame as a timer should be avoided, and animation triggers should be preferred instead.
|-
| anim_speed
| 0 .. 16
| Decide the time an animation frame should last. Return value is interpreted as (num_ticks = 2^anim_speed), which each tick lasting 30 ms. Avoid using this callback if possible, since it has to be called each tick for every animated tile. This can be used to create animation frames that last between 30 ms and 33 minutes.
|}

=== Graphics ===

[[File:Nml_station_graphics.dot.png|1000px]]

=== foundations ===

If <code style="color:darkgreen">STAT_FLAG_CUSTOM_FOUNDATIONS</code> is enabled in <code style="color:darkgreen">general_flags</code> you can draw custom foundation for station tiles on sloped terrain.

There are two options for providing foundation sprites:

==== STAT_FLAG_EXTENDED_FOUNDATIONS not set ====
The callback should return a spriteset looking like this:

[[File:simple_foundations.png]]

The foundations will be drawn by combining multiple sprites, as needed for the slope.

==== STAT_FLAG_EXTENDED_FOUNDATIONS ====
The callback should return a spritset looking like this:

[[File:extended_foundations.png]]

In addition you will have to check
* <code style="color:darkgreen">getbits(extra_callback_info2, 16, 2)</code>:
** 0: sprites as in template above.
** 1: sprites like before, but with no wall on NW edge.
** 2: sprites like before, but with no wall on NE edge.
** 3: sprites like before, but with no walls on either north edge.

NML:Stations

2026-04-15T14:30:43Z

Rito12: /* Station properties */ Update to nml #422.

{{NMLNavPropVarCB}}
Stations are supported since {{nml|0.7}}.

==Station sections==

Stations can be built from multiple sections. Station tiles will remember, which tiles were built together in one action.
* Building a 2x5 station in one action creates a single station section of size 2x5.
* Building a 2x5 station by placing two 1x5 areas next to each other in two actions creates two station sections of size 1x5; even when using the same station type from the same NewGRF.

[[File:station_sections.png|800px]]

Overbuilding stations and removing station tiles will remove tiles from station sections.
* On construction all station sections are contiguous rectangular NxM tile ares. (regular station section)
* When tiles are overbuilt or tiles are removed, station sections may end up non-rectangular and non-contiguous. (irregular station section)
Station tiles can query their position inside a contiguous line of tiles from the same section.
* This is great as long as the section remains regular.
* If tiles are non-contiguous, they are indistinguishable from tiles of other sections.

For irregular sections the "position" inside the section will become rather arbitrary.
The picture shows the perspective of each tile of a irregular section as "(platform, position)/(num-platforms, length)":

[[File:station_sections_irregular.png|800px]]

==Tile types==

When station sections are built, they can store a "tile type" for each tile using the <code style="color:darkgreen">select_tile_type</code> callback.

Tile types have multiple usages:
* The type can be read via the <code style="color:darkgreen">tile_type</code> variable, and can act as persistent storage.
* It decides whether the tile is traversible by trains, or whether it is a building without tracks.
* It decides whether catenary pylons and/or wires shall be drawn/hidden on the tile. Note: even non-track station buildings have a rail type, and can draw catenary.

The tile type is immutable after construction. So, unlike the platform/position information, the tile type will never change after construction, even if tiles of the station section are removed or overbuilt.

The number of tile types is quite limited: 4 per orientation, 8 in total.
'''Note:''' Since {{ottd|15.0}} {{nml|0.7.6}} it is possible to register up to 256 tile types.
* Tile types 0, 2, 4 and 6 are used for station sections with tracks in X direction (⤢).
* Tile types 1, 3, 5 and 7 are used for station sections with tracks in Y direciton (⤡).
* Callback <code style="color:darkgreen">select_tile_type</code> decides between the pairs (0,1), (2,3), (4,5), (6,7) during construction. The orientation is always picked by the player.

==Station properties==

{| class="wikitable sortable"
! property
! value range
! comment
|-
| class
| String literal of length 4
|
'''This property ''must'' be set first, before any other properties or graphics.''' 
Stations belonging to the same class are grouped in the GUI. 
There is one special class:
* "WAYP": The station type will be shown in the waypoint construction window, instead of the station construction window.
{{ottdp|15}} Station classes which start with the byte FF are considered waypoint classes, and will appear in the waypoint construction window instead of the station construction window.
|-
| classname
| string
| You only need to set this for one station in every class.
|-
| name
| string
| For example: string(STR_50S_STATION)
|-
| disabled_platforms disabled_length
| bitmask(1, 2, 3, 4, 5, 6, 7, 8)
|
Restricts the possible number-of-platforms and platform-lengths the player can build as one section.
* Sizes 1 to 7 can be disabled individually,
* "size 8" is used for anything bigger than 7.
To put restrictions on sizes bigger than 7 (for example, only allow even sizes), you can use callback <code style="color:darkgreen">tile_check</code>.
 Note: Players can remove single tiles from any station, so stations sections can end up with forbidden sizes anyway.
|-
| cargo_threshold
| 0..4095
| Threshold between <code style="color:darkgreen">little</code> and <code style="color:darkgreen">lots</code> spritesets, see [[NML:Spritegroup#Stations|spritegroup]] for details.
|-
| draw_pylon_tiles hide_wire_tiles non_traversable_tiles 
| bitmask(0, 1, 2, 3, 4, 5, 6, 7)
| '''Deprecated since '''{{nml|0.7.6}}''' , replaced by '''<code style="color:darkgreen">tile_flags</code>'''.''' 
Specifies which [[#Tile_types|tile types]] are traversible/non-traversible, and whether pylons and/or catenary shall be drawn for electrified rail types.
Note: it is common that all tile types behave the same, you may want to use the short cuts
* <code style="color:darkgreen">0</code> for no tile types, and
* <code style="color:darkgreen">STAT_ALL_TILES</code> for all tile types.
|-
| cargo_random_triggers
| Array of cargo labels from the [[NML:Cargotable|cargotable]]
| Cargo types, which will [[NML:Random_switch#Stations|trigger re-randomization]] when delivered, loaded or unloaded at the station.
|-
| general_flags
| bitmask(STAT_FLAG_XXX, STAT_FLAG_YYY, ...)
|
;STAT_FLAG_DISTRIBUTED_CARGO_BY_PERIMETER {{nml|0.9.0}}
:Specifies whether waiting cargo amounts are scaled by station '''perimeter''' for spriteset selection, see [[NML:Spritegroup#Stations|spritegroup]] for details.
:Since {{ottd|16.0}} if STAT_FLAG_DISTRIBUTED_CARGO_BY_AREA is also set it does not do anything.
;STAT_FLAG_DISTRIBUTED_CARGO_BY_AREA {{ottd|16.0}} {{nml|0.9.0}}
:Specifies whether waiting cargo amounts are scaled by station '''area''' for spriteset selection, see [[NML:Spritegroup#Stations|spritegroup]] for details.
;STAT_FLAG_RANDOM_ANIMATION
:If set, callback <code style="color:darkgreen">anim_next_frame</code> will get random data in <code style="color:darkgreen">extra_callback_info1</code>
;STAT_FLAG_CUSTOM_FOUNDATIONS
:Enables callback <code style="color:darkgreen">foundations</code>, see below.
;STAT_FLAG_EXTENDED_FOUNDATIONS
:Selects between two possible spriteset formats for callback <code style="color:darkgreen">foundations</code>, see below.
;STAT_FLAG_DISTRIBUTED_CARGO
:Deprecated since {{nml|0.9.0}}.
|-
| 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(STAT_ANIM_XXX, ANIM_TRIGGER_STAT_YYY, ...)
| Enables callback <code style="color:darkgreen">anim_control</code> for specified triggers:
;STAT_ANIM_IS_BUILT
:Tile is built. (all new-built/overbuilt tiles)
;STAT_ANIM_CARGO_ARRIVES
:Cargo is deliverd from industry to station. (all station tiles)
;STAT_ANIM_CARGO_REMOVED
:All cargo was loaded onto a vehicle, no more cargo (of this type) is waiting. (all station tiles)
;STAT_ANIM_TRAIN_ENTERS
:Train stops at station. (all tiles of platform)
;STAT_ANIM_TRAIN_LEAVES
:Train leaves station. (all tiles of platform)
;STAT_ANIM_TRAIN_LOAD_UNLOAD
:Train is loading or unloading. (all tiles of platform)
;STAT_ANIM_250_TICKS
:Every 250 ticks. (synchronized for all tiles of the station)
;{{ottd|15.0}} ANIM_TRIGGER_STAT_TILELOOP
:Tile is processed in the periodic processing loop
;{{ottd|15.0}} ANIM_TRIGGER_STAT_TRAIN_RESERVES
:Train reserves platform (using PBS)
|-
| badges
| Array of badge labels from the [[NML:Badgetable|badgetable]].
| Since {{ottd|15.0}}
|-
| tile_flags
| Array of <code>bitmask(STAT_TILE_XXX, ...)</code>
| Since {{ottd|15.0}} {{nml|0.7.6}} 
Each element of array corresponds to one tile type. Array should always have even number of elements. 
'''XXX''' should be replaced by one of the following:
; PYLON
: Draw pylon on tile with that type.
; NOWIRE
: Hide wire on tile with that type.
; BLOCKED
: Do not allow trains to enter tile with that type.
|}

==Station variables==

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

{| class="wikitable sortable"
! name
! value range
! comment
|-
| random_bits_station
| 0..65535
| 16 random bits, shared between all station sections (rail station sections, airports, ...)
|-
| 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="wikitable sortable"
! 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="wikitable sortable"
! name
! value range
! comment
|-
| tile_type
| 0..7
; 0..255 {{ottd|15.0}}
| The type of tile, as decided by <code style="color:darkgreen">select_tile_type</code>. Bit 0 also tells the orientation.
|-
| 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.
|-
| random_bits_tile
| 0..15
| 4 random bits, specific to this station 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="wikitable sortable"
! 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_grfid
| tile- and platform-offset <ref name="offset"/>
| 32-bit GRFID
| GRFID of the NewGRF defining the given station tile.
|-
| 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_tile_type
| tile- and platform-offset <ref name="offset"/>
| 0..7
; 0..255 {{ottd|15.0}}
| [[#Tile_types|Tile type]] of the given tile. The orientation bit is adjusted to be relative to the current tile's orientation:
* 0, 2, 4, 6: Tracks are parallel.
* 1, 3, 5, 7: Tracks are perpendicular.
|-
| 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 [[#Station_sections|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.
|-
| has_badge
| Label from the [[NML:Badgetable|badgetable]].
| [0 <nowiki>|</nowiki> 1]
| {{ottd|15.0}} Check if the rail station has that specific badge attached.
|}
<references/>

==Station callbacks==

The following table contains a list of available station 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 cargo is waiting at the station. If multiple cargo types are waiting at the station, OpenTTD will pick one of the options the station provides.
If none of the listed cargo types is waiting at the station, the <code style="color:darkgreen">default</code> callback will be used.

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="wikitable sortable"
! callback
! return value
! comment
|-
| default
| spritegroup
| See [[#Graphics|below]].
|-
| purchase
| spritegroup or spriteset
| See [[#Graphics|below]]. If a spritegroup is linked instead of a spriteset, the "zero cargo amount" spriteset is used.
|-
| custom_spritesets
| Array of spritesets
| See [[#Graphics|below]].
|-
| sprite_layouts
| Array of spritelayouts
| See [[#Graphics|below]]. The number of sprite_layouts must be even, alternating X (⤢) and Y (⤡) orientations.
|-
| select_sprite_layout
| index into sprite_layouts[]
| See [[#Graphics|below]]. The result's even-/oddness is ignored. The orientation is always adjusted by OpenTTD.
|-
| purchase_select_sprite_layout
| index into sprite_layouts[]
| See [[#Graphics|below]]. The result's even-/oddness is ignored. The orientation is always adjusted by OpenTTD.
|-
| prepare_layout
| expression list
| See [[#Graphics|below]].
|-
| purchase_prepare_layout
| expression list
| See [[#Graphics|below]].
|-
| foundations
| sprite set
| See [[#foundations|below]].
|-
| availability
| [0 <nowiki>|</nowiki> 1]
| Return 1 to make the station show up in the build window
|-
| tile_check
| Same as for the [[NML:IndustryTiles#Location check results|location_check]] industry callback
| Decide whether station may be built on this tile. This is an additional check to all built-in checks (like slope checks), you can only further restrict construction, not lessen conditions.

Called before constructing the station section, so nothing exists on the map yet. Since the station isn't built yet, so you can't access station variables.
Only these variables are available: company-information, and the class, height, slope, terrain type and water status of nearby tiles.
* <code style="color:darkgreen">getbits(extra_callback_info1, 4, 4)</code>: The [[NML:List_of_tile_slopes|tile slope]] of the tile.
* <code style="color:darkgreen">getbits(extra_callback_info1, 0, 4)</code>: The [[NML:List_of_tile_slopes|tile slope]] of the tile, adjusted by station orientation:
** unmodified in X direction (⤢)
** mirrored in Y direction (⤡)
* <code style="color:darkgreen">getbits(extra_callback_info2, 0, 8)</code>: Tile position along the new-built platform. (0 = north tile)
* <code style="color:darkgreen">getbits(extra_callback_info2, 8, 8)</code>: Platform number within the new-built section. (0 = north platform)
* <code style="color:darkgreen">getbits(extra_callback_info2, 16, 8)</code>: Length of the new section being built.
* <code style="color:darkgreen">getbits(extra_callback_info2, 24, 8)</code>: Number of platforms in the new section being built.

|-
| select_tile_type
| [0 <nowiki>|</nowiki> 2 <nowiki>|</nowiki> 4 <nowiki>|</nowiki> 6]

Since {{ottdp|15}}, even values up to FE can be returned as long as the tile is defined.
| Decides which tile type to store for each tile during construction. The lowest bit is always defined by the station orientation, no matter the callback result. See also [[#Tile_types|tile type above]].

Called before constructing the station section, so nothing exists on the map yet. Since the station isn't built yet, so you can't access station variables.
Only these variables are available: company-information, and the class, height, slope, terrain type and water status of nearby tiles.
* <code style="color:darkgreen">getbits(extra_callback_info1, 0, 4)</code>: Tile position along the new-built platform. (0 = north tile)
* <code style="color:darkgreen">getbits(extra_callback_info1, 4, 4)</code>: Tile position along the new-built platform. (0 = south tile)
* <code style="color:darkgreen">getbits(extra_callback_info1, 8, 4)</code>: Platform number within the new-built section. (0 = north platform)
* <code style="color:darkgreen">getbits(extra_callback_info1, 12, 4)</code>: Platform number within the new-built section. (0 = south platform)
* <code style="color:darkgreen">getbits(extra_callback_info1, 16, 4)</code>: Length of the new section being built.
* <code style="color:darkgreen">getbits(extra_callback_info1, 20, 4)</code>: Number of platforms in the new section being built.
* <code style="color:darkgreen">getbits(extra_callback_info1, 24, 8)</code>: Original tile type in static layout.

|-
| 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>: 32 random bits, if enabled in the <code style="color:darkgreen">general_flags</code> property.
Returning a sound effect in the high byte will cause that sound effect to be played.

Note: Every time the animation frame is changed the map tile will be refreshed, even if the selected graphics stay the same. Therefore using the animation frame as a timer should be avoided, and animation triggers should be preferred instead.
|-
| anim_control
| Next animation frame or CB_RESULT_XXX
|
Called whenever an animation trigger happens. Return the animation frame to show, or CB_RESULT_XXX with XXX = [CB_RESULT_START_ANIMATION <nowiki>|</nowiki> STOP_ANIMATION <nowiki>|</nowiki> DO_NOTHING] to respectively start the animation in its current frame, stop the animation or do nothing. Returning a sound effect in the high byte will cause that sound effect to be played.
* <code style="color:darkgreen">extra_callback_info1</code>: 32 random bits. The low 16 bits are always different for each station tile, but the high 16 bits are the same for all triggered tiles.
* <code style="color:darkgreen">getbits(extra_callback_info2, 0, 8)</code>: Reason for the callback trigger (STAT_ANIM_xxx). Note that you need to enable the wanted triggers in the <code style="color:darkgreen">animation_triggers</code> property.
* <code style="color:darkgreen">getbits(extra_callback_info2, 8, 8)</code>: Cargo-type involved in the trigger. Only applies to STAT_ANIM_CARGO_ARRIVES, STAT_ANIM_CARGO_REMOVED, STAT_ANIM_TRAIN_LOAD_UNLOAD.
Note: Every time the animation frame is changed the map tile will be refreshed, even if the selected graphics stay the same. Therefore using the animation frame as a timer should be avoided, and animation triggers should be preferred instead.
|-
| anim_speed
| 0 .. 16
| Decide the time an animation frame should last. Return value is interpreted as (num_ticks = 2^anim_speed), which each tick lasting 30 ms. Avoid using this callback if possible, since it has to be called each tick for every animated tile. This can be used to create animation frames that last between 30 ms and 33 minutes.
|}

=== Graphics ===

[[File:Nml_station_graphics.dot.png|1000px]]

=== foundations ===

If <code style="color:darkgreen">STAT_FLAG_CUSTOM_FOUNDATIONS</code> is enabled in <code style="color:darkgreen">general_flags</code> you can draw custom foundation for station tiles on sloped terrain.

There are two options for providing foundation sprites:

==== STAT_FLAG_EXTENDED_FOUNDATIONS not set ====
The callback should return a spriteset looking like this:

[[File:simple_foundations.png]]

The foundations will be drawn by combining multiple sprites, as needed for the slope.

==== STAT_FLAG_EXTENDED_FOUNDATIONS ====
The callback should return a spritset looking like this:

[[File:extended_foundations.png]]

In addition you will have to check
* <code style="color:darkgreen">getbits(extra_callback_info2, 16, 2)</code>:
** 0: sprites as in template above.
** 1: sprites like before, but with no wall on NW edge.
** 2: sprites like before, but with no wall on NE edge.
** 3: sprites like before, but with no walls on either north edge.

Action0/Cargos

2026-04-07T10:34:54Z

Rito12: /* Properties */ COLOUR

== Introduction ==

The [[ttwiki:NewCargos|NewCargos]] switch of TTDPatch allows modifying the existing 12 cargos per climate, and allows adding 20 new cargos per climate as well. These cargo slots are numbered from 0 to 31, where slots 0-11 are used by default TTD cargos and slots 12-31 contain uninitialized garbage by default (so you can't trust them having meaningful information, you must set all of their properties).

{{ottdp|1.9|no|ottdrev=11ab3c4e}} OpenTTD 1.9 increases the number of cargos to 64.

== Properties ==

{| |-
!Number!![[GRFActionsDetailed|Size]]!!Version!!Description
|-
|08||B||{{ottdp|0.6|2.5}}||Bit number for bitmasks
|-
|09||W||{{ottdp|0.6|2.5}}||TextID for the cargo type name
|-
|0A||W||{{ottdp|0.6|2.5}}||TextID for the name of one unit from the cargo type
|-
|0B||W||{{ottdp|0.6|2.5}}||TextID to be displayed for 1 unit of cargo
|-
|0C||W||{{ottdp|0.6|2.5}}||TextID to be displayed for multiple units of cargo
|-
|0D||W||{{ottdp|0.6|2.5}}||TextID for cargo type abbreviation
|-
|0E||W||{{ottdp|0.6|2.5}}||Sprite number for the icon of the cargo
|-
|0F||B||{{ottdp|0.6|2.5}}||Weight of one unit of the cargo
|-
|10,11||B||{{ottdp|0.6|2.5}}||Penalty times
|-
|12||D||{{ottdp|0.6|2.5}}||Base price
|-
|13||B||{{ottdp|0.6|2.5}}||Colour for the station list window
|-
|14||B||{{ottdp|0.6|2.5}}||Colour for the cargo payment list window
|-
|15||B||{{ottdp|0.6|2.5}}||Freight status (for freight-weight-multiplier setting); 0=not freight, 1=is freight
|-
|16||W||{{ottdp|0.6|2.5}}||Cargo classes
|-
|17||D||{{ottdp|0.6|2.5}}||Cargo label
|-
|18||B||{{ottdp|0.6|2.5|ttdprev=alpha 72}}||Substitute type for town growth
|-
|19||W||{{ottdp|no|2.5|ttdprev=alpha 72}}||Multiplier for town growth
|-
|1A||B||{{ottdp|0.6|2.5|ttdprev=alpha 72}}||Callback flags
|-
|1B||W||{{ottdp|1.1|no|ottdrev=r21224}}||TextID for displaying the units of a cargo
|-
|1C||W||{{ottdp|1.1|no|ottdrev=r21224}}||TextID for displaying the amount of cargo
|-
|1D||W||{{ottdp|1.2|no|ottdrev=r23860}}||Capacity mulitplier
|-
|1E||B||{{ottdp|14.0|no}}||Town Production effect
|-
|1F||W||{{ottdp|14.0|no}}||Town Production multiplier
|}

== Descriptions ==

=== Bit number for bitmasks (08) ===

This value must be used in [[Action3]] and in cargo bit mask properties such as refit masks. Values 1C-1F should be safe to use (if they aren't already taken, of course) if you intend to maintain compatibility with GRFs unaware of the newcargos switch. Further assuming that no active GRFs support the toyland climate, you can use values 11-1A as well.

Additionally, you can use the value FFh to disable the given cargo slot. This way, it won't appear in cargo type lists, but it won't be removed from things already on the map. If you disable a cargo, you'll probably want to zero out the cargo label (property 17) as well.

This property only affects GRFs which do not have a [[Action0/Global Settings#Cargo_translation_table_.2809.29 | cargo translation table]]. GRFs with such a table generally use the index of the cargo in the table instead of the value of this property to access a cargo. As such this property is more or less a default value for GRFs without cargo translation table. If you are unsure what value to assign to this property, set it to the same value as the cargo slot ID.

=== TextID for the cargo type name (09) ===

This textID should refer to the name of the cargo, capitalized, to match the TTD style (e.g. "Passengers", "Coal", "Gold Ore", "Milk")

You can reuse existing [[TextIDs]] or create custom strings using [[Action4]] with an offset in the DCxx range. Note that you need to set language-id bit 7 as well in the Action4 for a custom string. (Also applies to properties 0A to 0D)

=== TextID for one unit of the type (0A) ===

This textID should refer to the cargo type name in the singular. Currently, this ID is used only in subsidy messages ("First Passenger service..." instead of "First Passengers service...", for example)

=== TextID for 1 unit of cargo (0B) ===

This textID will be used to display the amount of the cargo if there's exactly 1 unit waiting. Although there's only one unit waiting, you'll still have to use either the special character 7C (print signed word) or 87 (print amount in litres and add suffix " litres") so TTD removes the amount from its internal reference stack. For example, if you have a new cargo named "gold ore", this should be "\7C ton of gold ore", which will expand to "1 ton of gold ore". On the other hand, a liquid cargo named "milk" should be something like "\87 of milk", which will expand to either "100 litres of milk" or "1,000 litres of milk" (The multiplier for liquid cargos depends on miscmods.dontfixlitres. If it's on, the multiplier is 100, otherwise it's 1000)

=== TextID for multiple units of cargo (0C) ===

This textID will be used to display the amount of cargo if the amount waiting isn't exactly 1. You'll need the same special characters as above, but now they will be expanded according to the actual cargo waiting. Sticking to the example above, you'll need "\7C tons of gold ore" and "\87 of milk", which can expand to "42 tons of gold ore" and "42,000 litres of milk", accordingly. You will note that liquid cargos can have the same textID for both property 0B and 0C since they always use the plural form.

=== TextID for cargo type abbreviation (0D) ===

This textID will be used in the station list window to represent the cargo waiting. It should be a two-letter abbreviation prefixed by the special character 0E to switch to the microscopic font. The microscopic font has every letter capitalized, so capitalization isn't important here. Continuing the above example, gold ore could have this as "GO" and milk as "MK" ("ML" is already taken by mail).

=== Sprite number for icon (0E) ===

This is a sprite number of an old TTD sprite to be displayed in the station window for this cargo, or FFFFh if the icon should be found by following the action 3 associated with this cargo. The icon must not be bigger than 10x10 pixels. One icon will be shown for every 10 units of the cargo waiting, up to 23 icons, which is the maximum.

=== Weight of one unit of the cargo (0F) ===

This property defines the weight of 1 unit from the cargo, which will be used to calculate the weight of the vehicles when loaded. The unit is 1/16 ton (which is 62.5 kg). With the examples above, gold ore should have this as 16 (since 1 ton of gold ore should weigh exactly 1 ton), while milk should have this slightly above 16 (milk is denser than water).

=== Penalty times and price factor (10,11,12) ===

These three values define how much is paid for the delivery of the cargo type. The price factor is subject to inflation, but GRFs needn't care about this, the programme will adjust the price for them.

The income generated from cargo delivery is calculated as:

income=((((distance/2) * timefactor * amount_moved) >> 7) * cargopricefactor) >> 13

where

; a >> b : means a is arithmetically shifted right by b bits
; distance : is the Manhattan distance between the two station signs
; amount_moved : is the number of cargo units moved
; cargopricefactor : is the value you set in property 12. Inflation will be applied automatically on it.
; timefactor : is a multiplier in the range 0..255, calculated in the following way: (T1 is the value of property 10, T2 is the value of property 11, t is the time the delivery took, the unit is 185 game ticks (roughly 2.5 game days) )

if t<=T1 then timefactor=255
else if t<=(T1+T2) then timefactor=255-(t-T1)
else timefactor=255-(t-T1)-(t-T1-T2)
if the above rules result in a timefactor less than 31, 31 is used instead.

=== Color for the station list window (13) ===

This color index will be used to draw the rectangle representing the amount waiting from the current cargo type in the station list window. The index should be given for the DOS palette. OpenTTD and TTDPatch will automatically translate the index for the Windows palette, if they use the windows base graphics.

=== Color for the cargo payment list window (14) ===

The graph of the current cargo will be drawn using this color in the cargo payment rates graph. The index should be given for the DOS palette, the Windows version of TTDPatch will automatically translate the index for the Windows palette.

=== CargoClasses (16) ===

See [[Action0Trains#Cargo classes .2828.2C_29.29|train prop. 28/29]] for a description of the utility of this property.

The history of cargo classes is complex, and the meanings here may not be consistent with how classes are actually used by some grfs.

FIRS and Iron Horse do not conform to the classes here, and use the FRAX Cargo Class Scheme, please see: https://grf.farm/polar-fox/frax_latest.html

This is a bit mask of all cargo classes to which this cargo could belong.
The following classes are available:

{| class="wikitable
|-
!bit
!value
!class name
!wagon type<ref name=vehicle>Suggestion for vehicle types which transport this cargo</ref>
!usage<ref name=refitusage>Suggestion how to best make use of this class in the refit masks of vehicles OR to be included in the 'allowed classes' (train prop. 28), AND NOT in the 'disallowed classes' (train prop. 29)</ref>
!vehicle tips<ref name=vehicleuse>Suggestions this class should be used in the property which excludes a class of cargos from a vehicle. One specific type of cargo could appear both as liquid or as piece goods (e.g. milk), which depends on the actual representation. Thus excluding the other would disallow refit to that cargo.</ref>
!industry tips
|-
|0
|1
|Passengers
|passenger wagon
|OR
|never exclude
|do not combine with other flags
|-
|1
|2
|Mail
|closed or mail wagon
|OR
|never exclude
|do not combine with other flags
|-
|2
|4
|Express
|closed or mail wagon
|OR
|never exclude, suitable for airplane or maglev
|
|-
|3
|8
|Armored
|armored or mail wagon
|OR
|never exclude
|do not combine with other flags
|-
|4
|10
|Bulk (Uncountable)
|open or hopper wagon
|OR
|never exclude
|may be combined with Piece Goods or Liquid to simulate multiple modes of transport
|-
|5
|20
|Piece Goods (Countable)
|closed or open wagon
|OR
|never exclude
|may be combined with Bulk or Liquid to simulate multiple modes of transport
|-
|6
|40
|Liquid
|tank wagon
|OR
|never exclude
|may be combined with Piece Goods or Bulk to simulate multiple modes of transport
|-
|7
|80
|Refrigerated
|refrigerated wagon
|OR/AND NOT
|only exclude, when Piece Goods included
|also set Piece Goods
|-
|8
|100
|Hazardous
|unknown
|OR/AND NOT
|only exclude, when special wagons are provided.
|combine with Piece Goods, Liquid, Bulk or Express
|-
|9
|200
|Covered (weather protected)
|closed wagon, any other wagon with tarpaulin or weather cover
|OR/AND NOT
|do not exclude for Liquid
|combine with Piece Goods or Bulk
|-
|10
|400
|Oversized
|stake/flatbed wagon
|OR/AND NOT
|only exclude, when Piece Goods included
|combine with Piece Goods
|-
|11
|800
|Powderized (dry powdered materials that flow under air pressure)
|powder/silo vehicle equipped for compressed air unloading
|OR/AND NOT
|only exclude, when Bulk included
|combine with Bulk
|-
|12
|1000
|Non-pourable
|open wagon, but not hopper wagon
|AND NOT
|only exclude, when Bulk included
|combine with Bulk
|-
|13
|2000
|Potable
| exclude from non-food-grade vehicles
| AND NOT
| exclude
| set for all food-grade freight cargos
|-
|14
|4000
|Non-potable.
| exclude from food-grade vehicles
| AND NOT
| exclude
| set for all non-food-grade freight cargos
|-
|15
|8000
|special
|and not
|none
|special use
|do not set
|}

<references />

Only cargos which are in class 0 (passengers) will appear in bus stations. Only cargos which are ''not'' in class 0 will appear in truck stations.

Disclaimer: there is no guarantee that classes won't vary over time or between sets. The classes of a cargo may change between different versions of a specific industry/cargo newgrf, or different classes may be set for the same cargo label by different industry/cargo newgrfs. Feel free to use classes in your set for conveniently refitting to cargos, but if you - the vehicle author - care about specific cargos being transported in specific vehicles, use label based refits (changing labels without a very good reason is considered to be bad practice).

=== Cargo label (17) ===

Cargo labels are globally [[CargoTypes#Cargo Labels|unique identifiers]] for a cargo type. They are used to allow vehicle grfs to easily support many cargo types, whether they are active or not and no matter what slot or bit they are using.

Read about the [[Action0/Global Settings#Cargo translation table 09|cargo translation table]] for further info.

=== Substitute type and multiplier for town growth (18, 19) ===

These properties allow you to modify how a cargo type affects town growth. Property 18 can contain one of the following values:

{| |-
!Value!!Meaning!!{{ottdp|0.7|no}} Details<ref>This is the interpretation of OpenTTD. For TTDPatch see [http://www.tt-wiki.net/wiki/NewTownGrowthSwitches NewTownGrowthMechanism], which is quite different/unrelated.</ref>
|-
|00||Affect towns as passengers do||Cargo produced by houses is added to the statistics in the town GUI.
|-
|02||Affect towns as mail does||Cargo produced by houses is added to the statistics in the town GUI.
|-
|05||Affect towns as goods/candy does||See note about subsidies below.
|-
|09||Affect towns as water does||Second required cargo for towngrowth in the desert
|-
|0B||Affect towns as food/fizzy drinks do||First required cargo for towngrowth in desert/above snowline. Alse see note about subsidies below.
|-
|FF||Don't affect town growth (default)||
|}

<references />

{{ottdp|no|2.5|ttdprev=alpha 72}} The incoming cargo amount is multiplied by property 19, then divided by 256 before it is added to the town statistics. This allows you to have smaller or bigger impact than original cargoes do.

If no cargos in the game are defined as food (0B), towns above the snowline will not require food to grow. If no cargos in the game are defined as food (0B) or water (09), towns in desert will not require food or water to grow. This can be used positively for gameplay purposes, and is otherwise worth being aware of as an unintended side effect when designing cargos.

Please note that cargoes accepted by industries affect the closest town as well; for example, if you have an industry that accepts passengers, every passenger brought to the industry affects the town just like if they were transported to the town directly. Usually, it's not a good idea to have industries that process such cargoes; they should be accepted by towns only.

{{ottdp|0.6-1.1|no}} In OpenTTD up to 1.1 (not 1.2) property 18 also affects the creation of subsidies. Usually subsidies apply to cargo transportation between two industries. For cargos with substitution-type 05 or 0B the destination will be a town instead. Independent of property 18 subsidies from town to town are only created for cargo slot 0 (Passengers).

=== Callback flags (1A) ===

{| |-
!Bit!!Value!!Var. 0C!!Callback
|-
|0||1||39||Custom profit calculation
|-
|1||2||145||Custom station rating calculation
|}

=== TextID for displaying the units of a cargo (1B) ===

This textID is used by OpenTTD to show the "short cargo" form for cargo units, e.g. "10 litres" or "10 tonnes". This textID must be set after property 0B. The text this textID refers to should properly handle plurals, e.g. "\7B item\9A\15\80\9A\10\9A\11s\9A\12".

The default for this textID depends on the default for property 0B; if the default 0B string has "litre", then the default for this textID will be the unit for litres. OpenTTD maps the following textIDs so you don't need to provide translations:

{| |-
!textID!!String
|-
|004f||<num> passenger(s)
|-
|0050||<num> tonne(s)
|-
|0051||<num> bag(s)
|-
|0052||<num> litre(s)
|-
|0053||<num> item(s)
|-
|0054||<num> crate(s)
|}

The "tonne" and "litre" strings (textID 0050 and 0052) are automatically updated based on the user settings of unit display, e.g. they "tonne" might become "kg". The "(s)" is for display purposes; in reality that is a choice list.

=== TextID for displaying the amount of cargo (1C) ===

This textID is used by OpenTTD to show the "long cargo" form for cargo units, e.g. "10 litres of water" or "10 tonnes of coal". This textID must be set after property 0c. The text this textID refers to should properly handle plurals, e.g. "\7B item\9A\15\80\9A\10\9A\11s\9A\12 of livestock".

The default for this textID depends on the default for property 0C, but with support for plurals. For "X litre(s)" or "X tonne(s)" you should respectively use string codes 87 and 9A 0D.

=== Capacity multiplier (1D) ===

This defines the capacity (and indirectly loading speed) 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 0x100 (256) tons of coal or 0x100 (256) 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.

The default value of this property is:
{| |-
! Cargo slot !! Default cargo in this slot !! Property 1D !! Meaning
|-
| 00 || PASS || 0x400 || A vehicle carrying 1 ton of coal, can carry 4 passengers.
|-
| 02 || MAIL || 0x200 || A vehicle carrying 1 ton of coal, can carry 2 bags of mail.
|-
| 05 || GOOD, SWET || 0x200 || A vehicle carrying 1 ton of coal, can carry 2 crates of goods/sweets.
|-
| xx || (everything else) || 0x100 || All other slots default to 0x100, i.e. 1 unit of cargo equals 1 ton of coal.
|}

=== Town Production effect (1E) ===

This properties allow you to directly modify how a town produces cargo. Property 1E can contain one of the following values:

{| |-
!Value!!Meaning
|-
|00||Towns produce cargo as passengers
|-
|02||Towns produce cargo as mail
|-
|FF||Towns don't produce cargo (default)
|}

=== Town Production multiplier (1F) ===

Set this property to the amount of cargo a town will produce, relative to the normal amount for that town production effect (passengers or mail.) The default value is 0x100 (256), use a lower value to produce less cargo, or a higher value to produce more cargo.

Properties 1E and 1F are an alternative to the cargo production callback of houses, and allow for cargo to be set up to be produced by towns without having to redefine any houses, although it is not as flexible.

== Example ==

NML:Roadstops

2026-03-19T18:39:14Z

Rito12: /* Animation triggers */ Add missing flag.

{{NMLNavPropVarCB}}

Road stops can only be defined in OpenTTD {{ottd|14.0}} or later.

==Road stop IDs==
OpenTTD supports 64000 road stop types per game.

Rpad stop IDs are NewGRF-local and can therefore freely be chosen within the ID ranges.

A road stop is allocated by setting the 'class'-property, which should therefore be set first.

Road stop sprite layouts should always set a suitable ground tile sprite, and should not assume that a road type GRF will provide suitable overlay sprites.
Suggested ground sprite IDs include: GROUNDSPRITE_ROAD_X/GROUNDSPRITE_ROAD_Y (straight road on grass), 1314/1313 (straight road with pavement), 2692 - 2695 (bay road stop ground).

==Road stop properties==

{| class="wikitable sortable"
! property
! value range
! comment
|-
| class
| String literal of length 4
|
'''This property ''must'' be set first, before any other properties or graphics.''' 
Road stops belonging to the same class are grouped in the GUI. 
There is one special class:
* "WAYP": {{ottdp|15.0|no}} The road stop type will be shown in the waypoint construction window, instead of the station construction window.
{{ottdp|15}} Station classes which start with the byte FF are considered waypoint classes, and will appear in the waypoint construction window instead of the station construction window.
|-
| classname
| string
| You only need to set this for one road stop in every class.
|-
| name
| string
|
|-
| availability_type
| RST_AVAILABILITY_TYPE_XXX
| XXX = [PASSENGER <nowiki>|</nowiki> FREIGHT <nowiki>|</nowiki> ALL]
The default value is RST_AVAILABILITY_TYPE_ALL
|-
| draw_mode
| bitmask(RST_DRAW_FLAG_XXX, ...)
| See [[#List of draw mode flags|list of draw mode flags]]
The default value is bitmask(RST_DRAW_FLAG_BAY_ROAD, RST_DRAW_FLAG_DRIVE_THROUGH_ROAD_OVERLAY)
|-
| cargo_random_triggers
| Array of cargo labels from the [[NML:Cargotable|cargotable]]
| Cargo types, which will [[NML:Random_switch#Stations|trigger re-randomization]] when delivered, loaded or unloaded at the station.
|-
| 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
|
|
See [[#Animation_triggers|list of animation triggers]]
|-
| general_flags
| bitmask(RST_GENERAL_FLAG_XXX, ...)
| See [[#List of general flags|list of general flags]]
|-
| cost_multipliers
| [build_cost, clear_cost]
| Build and clear cost multipliers, 16 is the same as a non-NewGRF road stop
|-
| badges
| Array of badge labels from the [[NML:Badgetable|badgetable]].
| Since {{ottd|15.0}}
|}

===List of draw mode flags===

{| class="wikitable sortable"
! Name
! Meaning
|-
| RST_DRAW_FLAG_BAY_ROAD
| Draw road type ground sprite for bay stops.
|-
| RST_DRAW_FLAG_DRIVE_THROUGH_ROAD_OVERLAY
| Draw road overlays for drive-through stops.
|-
| RST_DRAW_FLAG_WAYPOINT_GROUND
| {{ottdp|15.0|no}} Draw spritelayout ground sprite on top of underlying road (if unset, the spritelayout ground sprite is not drawn).
|}

===List of general flags===

{| class="wikitable sortable"
! Name
! Meaning
|-
| RST_GENERAL_FLAG_RANDOM_ANIMATION
| Animation callback requires random bits in variable extra_callback_info1.
|-
| RST_GENERAL_FLAG_NO_CATENARY
| Do not show catenary graphics.
|-
| RST_GENERAL_FLAG_DRIVE_THROUGH_ONLY
| Only allow drive-through stops (not bay stops).
|-
| RST_GENERAL_FLAG_NO_AUTO_ROAD_CONNECTION
| Do not automatically build connecting road pieces.
|-
| RST_GENERAL_FLAG_BUILD_MENU_ROAD_ONLY
| Only show in the road build menu (not tram).
|-
| RST_GENERAL_FLAG_BUILD_MENU_TRAM_ONLY
| Only show in the tram build menu (not road).
|-
| RST_GENERAL_FLAG_DRAW_MODE_REGISTER
| {{ottdp|15.0|no}} Read the road stop draw mode from variable 0x100 (set using STORE_TEMP), this overrides the draw_mode property.
|}

==Road stop variables==

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

{| class="wikitable sortable"
! name
! value range
! comment
|-
| random_bits_station
| 0..65535
| 16 random bits, shared between all station sections (rail station sections, airports, ...)
|-
| 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:Stations|stations]] and [[NML:Airports|airports]]. They all require a single argument: a cargo type from your [[NML:Cargotable|cargo translation table]].

{| class="wikitable sortable"
! 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="wikitable sortable"
! name
! value range
! comment
|-
| view
| RST_VIEW_XXX
| The view/rotation of the road stop. See [[#List of road stop views|list of road stop views]]
|-
| stop_type
| RST_TYPE_XXX
| XXX = [BUS <nowiki>|</nowiki> TRUCK <nowiki>|</nowiki> {{ottdp|15}}WAYPOINT]
|-
| 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
|-
| has_road
| [0 <nowiki>|</nowiki> 1]
| 1 if this road stop has road
|-
| has_tram
| [0 <nowiki>|</nowiki> 1]
| 1 if this road stop has tram
|-
| road_type
| [Road type <nowiki>|</nowiki> 0xFF]
| Entry from [[NML:Railtypetable|roadtype translation table]], or 0xFF if there is no road
|-
| tram_type
| [Tram type <nowiki>|</nowiki> 0xFF]
| Entry from [[NML:Railtypetable|tramtype translation table]], or 0xFF if there is no tram
|-
| animation_frame
| 0 .. (frame_count - 1)
| Current animation frame, with the maximum defined in the <code style="color:darkgreen">animation_info</code> property.
|-
| 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.
|-
| 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.
|-
| random_bits_tile
| 0..255
| 8 random bits, specific to this road stop tile.
|-
| waiting_triggers
| 0..255
| Random triggers waiting to be matched. (see [[NML:Random switch|Random switch]])
|-
| drawn_in_gui
| [0 <nowiki>|</nowiki> 1]
| {{ottdp|15}} 1 if this road stop is being drawn in the build window
|}

===Variables that require one or more parameters===

{| class="wikitable sortable"
! name
! arguments
! value range
! comment
|-
| nearby_tile_slope
| x, y offset (-8..7)
|
| See tile_slope
|-
| 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. Only valid for tiles of the same object.
|-
| nearby_tile_is_road_stop
| x, y offset (-8..7)
| 0 .. 1
| Is the given tile a road stop?
|-
| nearby_tile_road_stop_id
| x, y offset (-8..7)
|
| Is nearby_tile_same_grf is true, ID of a road stop on a nearby tile
|-
| nearby_tile_same_grf
| x, y offset (-8..7)
| 0 .. 1
| Is a road stop on a nearby tile defined by the same GRF?
|-
| nearby_tile_other_grf
| x, y offset (-8..7)
| 0 .. 1
| Is a road stop on a nearby tile defined by another GRF?
|-
| nearby_tile_original_gfx
| x, y offset (-8..7)
| 0 .. 1
| Is a road stop on a nearby tile using original graphics?
|-
| nearby_tile_same_station
| x, y offset (-8..7)
| 0 .. 1
| Is a road stop on a nearby tile the same station as this?
|-
| nearby_tile_view
| x, y offset (-8..7)
| RST_VIEW_XXX
| The view/rotation of a nearby road stop tile. See [[#List of road stop views|list of road stop views]]
|-
| nearby_tile_different_view
| x, y offset (-8..7)
| 0 .. 1
| Is the view/rotation of a road stop on a nearby tile different to that of this tile?
|-
| nearby_tile_is_drive_through
| x, y offset (-8..7)
| 0 .. 1
| Is nearby road stop tile a drive-through road stop?
|-
| nearby_tile_stop_type
| x, y offset (-8..7)
| RST_TYPE_XXX
| Road stop type of a nearby tile. See stop_type
|-
| nearby_tile_same_stop_type
| x, y offset (-8..7)
| 0 .. 1
| Is the stop type of a nearby road stop tile the same as this tile?
|-
| nearby_tile_grfid
| x, y offset (-8..7)
| [0xFFFFFFFF <nowiki>|</nowiki> 0 <nowiki>|</nowiki> GRFID]
| 0xFFFFFFFF if the nearby tile is not a road stop, 0 if the nearby tile is a non-custom road stop, or else the GRFID of the NewGRF defining the road stop on the nearby tile
|-
| has_badge
| Label from the [[NML:Badgetable|badgetable]].
| [0 <nowiki>|</nowiki> 1]
| {{ottd|15.0}} Check if the road stop has that specific badge attached.
|}

===List of road stop views===

{| class="wikitable sortable"
! Name
! Type
! Meaning
|-
| RST_VIEW_BAY_NE
| Bay
| Facing north-east
|-
| RST_VIEW_BAY_SE
| Bay
| Facing south-east
|-
| RST_VIEW_BAY_SW
| Bay
| Facing south-west
|-
| RST_VIEW_BAY_NW
| Bay
| Facing north-west
|-
| RST_VIEW_DRIVE_THROUGH_X
| Drive-through
| X-axis: north-east to south-west
|-
| RST_VIEW_DRIVE_THROUGH_Y
| Drive-through
| Y-axis: north-west to south-east
|}

==Road stop callbacks==

{| class="wikitable sortable"
! callback
! return value
! comment
|-
| default
| Sprite layout
| Normal graphics for a road stop placed on the map
|-
| purchase <ref name="notyetbuilt">These callbacks are called when the road stop is not yet built</ref>
| Sprite layout
| Graphics shown in the build menu
|-
| availability
| 0 <nowiki>|</nowiki> 1
| Whether this road stop type is available in the build menu, 1 is available, 0 is unavailable
|-
| 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. 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>).
* <code style="color:darkgreen">extra_callback_info1</code>: 32 random bits, if the object flag OBJ_FLAG_RANDOM_ANIMATION is set.
|-
| 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. Returning a sound effect in the high byte will cause that sound effect to be played.
* <code style="color:darkgreen">extra_callback_info1</code>: 32 random bits, if the object flag OBJ_FLAG_RANDOM_ANIMATION is set.
* <code style="color:darkgreen">getbits(extra_callback_info2, 0, 8)</code>: Reason for the callback trigger, see the [[#Animation triggers| table]] below.
|-
| 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.
|}

===Animation triggers===

{| class="wikitable sortable"
! Animation trigger
! Description
! Happens on
! extra_callback_info2
|-
| ANIM_TRIGGER_ROAD_STOP_BUILT
| Road stop is built
| Newly built tile
|
|-
| ANIM_TRIGGER_ROAD_STOP_NEW_CARGO
| New cargo arrives at station
| All tiles
| Bits 8..15 contain the triggering cargo type
|-
| ANIM_TRIGGER_ROAD_STOP_CARGO_TAKEN
| CRGO removed from station
| All tiles
| Bits 8..15 contain the triggering cargo type
|-
| ANIM_TRIGGER_ROAD_STOP_VEH_ENTER
| Road vehicle enters stop (starts loading/unloading)
| Tile where the vehicle is
|
|-
| ANIM_TRIGGER_ROAD_STOP_VEH_LEAVE
| Road vehicle leaves stop (done loading/unloading)
| Tile where the vehicle is
|
|-
| ANIM_TRIGGER_ROAD_STOP_VEH_LOAD
| Road vehicle loads/unloads cargo
| Tile where the vehicle is
|
|-
| ANIM_TRIGGER_ROAD_STOP_250_TICKS
| Every 250 ticks
| All tiles
|
|-
| {{ottd|15.0}} ANIM_TRIGGER_ROAD_STOP_TILELOOP
| Tile is processed in the periodic processing loop
|
|
|}

NML:Stations

2026-03-19T18:32:04Z

Rito12: /* Station properties */ Add missing flags.

{{NMLNavPropVarCB}}
Stations are supported since {{nml|0.7}}.

==Station sections==

Stations can be built from multiple sections. Station tiles will remember, which tiles were built together in one action.
* Building a 2x5 station in one action creates a single station section of size 2x5.
* Building a 2x5 station by placing two 1x5 areas next to each other in two actions creates two station sections of size 1x5; even when using the same station type from the same NewGRF.

[[File:station_sections.png|800px]]

Overbuilding stations and removing station tiles will remove tiles from station sections.
* On construction all station sections are contiguous rectangular NxM tile ares. (regular station section)
* When tiles are overbuilt or tiles are removed, station sections may end up non-rectangular and non-contiguous. (irregular station section)
Station tiles can query their position inside a contiguous line of tiles from the same section.
* This is great as long as the section remains regular.
* If tiles are non-contiguous, they are indistinguishable from tiles of other sections.

For irregular sections the "position" inside the section will become rather arbitrary.
The picture shows the perspective of each tile of a irregular section as "(platform, position)/(num-platforms, length)":

[[File:station_sections_irregular.png|800px]]

==Tile types==

When station sections are built, they can store a "tile type" for each tile using the <code style="color:darkgreen">select_tile_type</code> callback.

Tile types have multiple usages:
* The type can be read via the <code style="color:darkgreen">tile_type</code> variable, and can act as persistent storage.
* It decides whether the tile is traversible by trains, or whether it is a building without tracks.
* It decides whether catenary pylons and/or wires shall be drawn/hidden on the tile. Note: even non-track station buildings have a rail type, and can draw catenary.

The tile type is immutable after construction. So, unlike the platform/position information, the tile type will never change after construction, even if tiles of the station section are removed or overbuilt.

The number of tile types is quite limited: 4 per orientation, 8 in total.
'''Note:''' Since {{ottd|15.0}} {{nml|0.7.6}} it is possible to register up to 256 tile types.
* Tile types 0, 2, 4 and 6 are used for station sections with tracks in X direction (⤢).
* Tile types 1, 3, 5 and 7 are used for station sections with tracks in Y direciton (⤡).
* Callback <code style="color:darkgreen">select_tile_type</code> decides between the pairs (0,1), (2,3), (4,5), (6,7) during construction. The orientation is always picked by the player.

==Station properties==

{| class="wikitable sortable"
! property
! value range
! comment
|-
| class
| String literal of length 4
|
'''This property ''must'' be set first, before any other properties or graphics.''' 
Stations belonging to the same class are grouped in the GUI. 
There is one special class:
* "WAYP": The station type will be shown in the waypoint construction window, instead of the station construction window.
{{ottdp|15}} Station classes which start with the byte FF are considered waypoint classes, and will appear in the waypoint construction window instead of the station construction window.
|-
| classname
| string
| You only need to set this for one station in every class.
|-
| name
| string
| For example: string(STR_50S_STATION)
|-
| disabled_platforms disabled_length
| bitmask(1, 2, 3, 4, 5, 6, 7, 8)
|
Restricts the possible number-of-platforms and platform-lengths the player can build as one section.
* Sizes 1 to 7 can be disabled individually,
* "size 8" is used for anything bigger than 7.
To put restrictions on sizes bigger than 7 (for example, only allow even sizes), you can use callback <code style="color:darkgreen">tile_check</code>.
 Note: Players can remove single tiles from any station, so stations sections can end up with forbidden sizes anyway.
|-
| cargo_threshold
| 0..4095
| Threshold between <code style="color:darkgreen">little</code> and <code style="color:darkgreen">lots</code> spritesets, see [[NML:Spritegroup#Stations|spritegroup]] for details.
|-
| draw_pylon_tiles hide_wire_tiles non_traversable_tiles 
| bitmask(0, 1, 2, 3, 4, 5, 6, 7)
| '''Deprecated since '''{{nml|0.7.6}}''' , replaced by '''<code style="color:darkgreen">tile_flags</code>'''.''' 
Specifies which [[#Tile_types|tile types]] are traversible/non-traversible, and whether pylons and/or catenary shall be drawn for electrified rail types.
Note: it is common that all tile types behave the same, you may want to use the short cuts
* <code style="color:darkgreen">0</code> for no tile types, and
* <code style="color:darkgreen">STAT_ALL_TILES</code> for all tile types.
|-
| cargo_random_triggers
| Array of cargo labels from the [[NML:Cargotable|cargotable]]
| Cargo types, which will [[NML:Random_switch#Stations|trigger re-randomization]] when delivered, loaded or unloaded at the station.
|-
| general_flags
| bitmask(STAT_FLAG_XXX, STAT_FLAG_YYY, ...)
|
;STAT_FLAG_DISTRIBUTED_CARGO
:Specifies whether waiting cargo amounts are scaled by station size for spriteset selection, see [[NML:Spritegroup#Stations|spritegroup]] for details.
;STAT_FLAG_RANDOM_ANIMATION
:If set, callback <code style="color:darkgreen">anim_next_frame</code> will get random data in <code style="color:darkgreen">extra_callback_info1</code>
;STAT_FLAG_CUSTOM_FOUNDATIONS
:Enables callback <code style="color:darkgreen">foundations</code>, see below.
;STAT_FLAG_EXTENDED_FOUNDATIONS
:Selects between two possible spriteset formats for callback <code style="color:darkgreen">foundations</code>, see below.
|-
| 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(STAT_ANIM_XXX, ANIM_TRIGGER_STAT_YYY, ...)
| Enables callback <code style="color:darkgreen">anim_control</code> for specified triggers:
;STAT_ANIM_IS_BUILT
:Tile is built. (all new-built/overbuilt tiles)
;STAT_ANIM_CARGO_ARRIVES
:Cargo is deliverd from industry to station. (all station tiles)
;STAT_ANIM_CARGO_REMOVED
:All cargo was loaded onto a vehicle, no more cargo (of this type) is waiting. (all station tiles)
;STAT_ANIM_TRAIN_ENTERS
:Train stops at station. (all tiles of platform)
;STAT_ANIM_TRAIN_LEAVES
:Train leaves station. (all tiles of platform)
;STAT_ANIM_TRAIN_LOAD_UNLOAD
:Train is loading or unloading. (all tiles of platform)
;STAT_ANIM_250_TICKS
:Every 250 ticks. (synchronized for all tiles of the station)
;{{ottd|15.0}} ANIM_TRIGGER_STAT_TILELOOP
:Tile is processed in the periodic processing loop
;{{ottd|15.0}} ANIM_TRIGGER_STAT_TRAIN_RESERVES
:Train reserves platform (using PBS)
|-
| badges
| Array of badge labels from the [[NML:Badgetable|badgetable]].
| Since {{ottd|15.0}}
|-
| tile_flags
| Array of <code>bitmask(STAT_TILE_XXX, ...)</code>
| Since {{ottd|15.0}} {{nml|0.7.6}} 
Each element of array corresponds to one tile type. Array should always have even number of elements. 
'''XXX''' should be replaced by one of the following:
; PYLON
: Draw pylon on tile with that type.
; NOWIRE
: Hide wire on tile with that type.
; BLOCKED
: Do not allow trains to enter tile with that type.
|}

==Station variables==

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

{| class="wikitable sortable"
! name
! value range
! comment
|-
| random_bits_station
| 0..65535
| 16 random bits, shared between all station sections (rail station sections, airports, ...)
|-
| 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="wikitable sortable"
! 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="wikitable sortable"
! name
! value range
! comment
|-
| tile_type
| 0..7
; 0..255 {{ottd|15.0}}
| The type of tile, as decided by <code style="color:darkgreen">select_tile_type</code>. Bit 0 also tells the orientation.
|-
| 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.
|-
| random_bits_tile
| 0..15
| 4 random bits, specific to this station 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="wikitable sortable"
! 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_grfid
| tile- and platform-offset <ref name="offset"/>
| 32-bit GRFID
| GRFID of the NewGRF defining the given station tile.
|-
| 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_tile_type
| tile- and platform-offset <ref name="offset"/>
| 0..7
; 0..255 {{ottd|15.0}}
| [[#Tile_types|Tile type]] of the given tile. The orientation bit is adjusted to be relative to the current tile's orientation:
* 0, 2, 4, 6: Tracks are parallel.
* 1, 3, 5, 7: Tracks are perpendicular.
|-
| 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 [[#Station_sections|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.
|-
| has_badge
| Label from the [[NML:Badgetable|badgetable]].
| [0 <nowiki>|</nowiki> 1]
| {{ottd|15.0}} Check if the rail station has that specific badge attached.
|}
<references/>

==Station callbacks==

The following table contains a list of available station 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 cargo is waiting at the station. If multiple cargo types are waiting at the station, OpenTTD will pick one of the options the station provides.
If none of the listed cargo types is waiting at the station, the <code style="color:darkgreen">default</code> callback will be used.

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="wikitable sortable"
! callback
! return value
! comment
|-
| default
| spritegroup
| See [[#Graphics|below]].
|-
| purchase
| spritegroup or spriteset
| See [[#Graphics|below]]. If a spritegroup is linked instead of a spriteset, the "zero cargo amount" spriteset is used.
|-
| custom_spritesets
| Array of spritesets
| See [[#Graphics|below]].
|-
| sprite_layouts
| Array of spritelayouts
| See [[#Graphics|below]]. The number of sprite_layouts must be even, alternating X (⤢) and Y (⤡) orientations.
|-
| select_sprite_layout
| index into sprite_layouts[]
| See [[#Graphics|below]]. The result's even-/oddness is ignored. The orientation is always adjusted by OpenTTD.
|-
| purchase_select_sprite_layout
| index into sprite_layouts[]
| See [[#Graphics|below]]. The result's even-/oddness is ignored. The orientation is always adjusted by OpenTTD.
|-
| prepare_layout
| expression list
| See [[#Graphics|below]].
|-
| purchase_prepare_layout
| expression list
| See [[#Graphics|below]].
|-
| foundations
| sprite set
| See [[#foundations|below]].
|-
| availability
| [0 <nowiki>|</nowiki> 1]
| Return 1 to make the station show up in the build window
|-
| tile_check
| Same as for the [[NML:IndustryTiles#Location check results|location_check]] industry callback
| Decide whether station may be built on this tile. This is an additional check to all built-in checks (like slope checks), you can only further restrict construction, not lessen conditions.

Called before constructing the station section, so nothing exists on the map yet. Since the station isn't built yet, so you can't access station variables.
Only these variables are available: company-information, and the class, height, slope, terrain type and water status of nearby tiles.
* <code style="color:darkgreen">getbits(extra_callback_info1, 4, 4)</code>: The [[NML:List_of_tile_slopes|tile slope]] of the tile.
* <code style="color:darkgreen">getbits(extra_callback_info1, 0, 4)</code>: The [[NML:List_of_tile_slopes|tile slope]] of the tile, adjusted by station orientation:
** unmodified in X direction (⤢)
** mirrored in Y direction (⤡)
* <code style="color:darkgreen">getbits(extra_callback_info2, 0, 8)</code>: Tile position along the new-built platform. (0 = north tile)
* <code style="color:darkgreen">getbits(extra_callback_info2, 8, 8)</code>: Platform number within the new-built section. (0 = north platform)
* <code style="color:darkgreen">getbits(extra_callback_info2, 16, 8)</code>: Length of the new section being built.
* <code style="color:darkgreen">getbits(extra_callback_info2, 24, 8)</code>: Number of platforms in the new section being built.

|-
| select_tile_type
| [0 <nowiki>|</nowiki> 2 <nowiki>|</nowiki> 4 <nowiki>|</nowiki> 6]

Since {{ottdp|15}}, even values up to FE can be returned as long as the tile is defined.
| Decides which tile type to store for each tile during construction. The lowest bit is always defined by the station orientation, no matter the callback result. See also [[#Tile_types|tile type above]].

Called before constructing the station section, so nothing exists on the map yet. Since the station isn't built yet, so you can't access station variables.
Only these variables are available: company-information, and the class, height, slope, terrain type and water status of nearby tiles.
* <code style="color:darkgreen">getbits(extra_callback_info1, 0, 4)</code>: Tile position along the new-built platform. (0 = north tile)
* <code style="color:darkgreen">getbits(extra_callback_info1, 4, 4)</code>: Tile position along the new-built platform. (0 = south tile)
* <code style="color:darkgreen">getbits(extra_callback_info1, 8, 4)</code>: Platform number within the new-built section. (0 = north platform)
* <code style="color:darkgreen">getbits(extra_callback_info1, 12, 4)</code>: Platform number within the new-built section. (0 = south platform)
* <code style="color:darkgreen">getbits(extra_callback_info1, 16, 4)</code>: Length of the new section being built.
* <code style="color:darkgreen">getbits(extra_callback_info1, 20, 4)</code>: Number of platforms in the new section being built.
* <code style="color:darkgreen">getbits(extra_callback_info1, 24, 8)</code>: Original tile type in static layout.

|-
| 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>: 32 random bits, if enabled in the <code style="color:darkgreen">general_flags</code> property.
Returning a sound effect in the high byte will cause that sound effect to be played.

Note: Every time the animation frame is changed the map tile will be refreshed, even if the selected graphics stay the same. Therefore using the animation frame as a timer should be avoided, and animation triggers should be preferred instead.
|-
| anim_control
| Next animation frame or CB_RESULT_XXX
|
Called whenever an animation trigger happens. Return the animation frame to show, or CB_RESULT_XXX with XXX = [CB_RESULT_START_ANIMATION <nowiki>|</nowiki> STOP_ANIMATION <nowiki>|</nowiki> DO_NOTHING] to respectively start the animation in its current frame, stop the animation or do nothing. Returning a sound effect in the high byte will cause that sound effect to be played.
* <code style="color:darkgreen">extra_callback_info1</code>: 32 random bits. The low 16 bits are always different for each station tile, but the high 16 bits are the same for all triggered tiles.
* <code style="color:darkgreen">getbits(extra_callback_info2, 0, 8)</code>: Reason for the callback trigger (STAT_ANIM_xxx). Note that you need to enable the wanted triggers in the <code style="color:darkgreen">animation_triggers</code> property.
* <code style="color:darkgreen">getbits(extra_callback_info2, 8, 8)</code>: Cargo-type involved in the trigger. Only applies to STAT_ANIM_CARGO_ARRIVES, STAT_ANIM_CARGO_REMOVED, STAT_ANIM_TRAIN_LOAD_UNLOAD.
Note: Every time the animation frame is changed the map tile will be refreshed, even if the selected graphics stay the same. Therefore using the animation frame as a timer should be avoided, and animation triggers should be preferred instead.
|-
| anim_speed
| 0 .. 16
| Decide the time an animation frame should last. Return value is interpreted as (num_ticks = 2^anim_speed), which each tick lasting 30 ms. Avoid using this callback if possible, since it has to be called each tick for every animated tile. This can be used to create animation frames that last between 30 ms and 33 minutes.
|}

=== Graphics ===

[[File:Nml_station_graphics.dot.png|1000px]]

=== foundations ===

If <code style="color:darkgreen">STAT_FLAG_CUSTOM_FOUNDATIONS</code> is enabled in <code style="color:darkgreen">general_flags</code> you can draw custom foundation for station tiles on sloped terrain.

There are two options for providing foundation sprites:

==== STAT_FLAG_EXTENDED_FOUNDATIONS not set ====
The callback should return a spriteset looking like this:

[[File:simple_foundations.png]]

The foundations will be drawn by combining multiple sprites, as needed for the slope.

==== STAT_FLAG_EXTENDED_FOUNDATIONS ====
The callback should return a spritset looking like this:

[[File:extended_foundations.png]]

In addition you will have to check
* <code style="color:darkgreen">getbits(extra_callback_info2, 16, 2)</code>:
** 0: sprites as in template above.
** 1: sprites like before, but with no wall on NW edge.
** 2: sprites like before, but with no wall on NE edge.
** 3: sprites like before, but with no walls on either north edge.

Badge labels

2026-03-16T08:09:01Z

Rito12: /* Introduction */ Add reference to BaNaNaS-get_badge_labels.

{{NMLNavBlocksyntax}}

== Introduction ==
This page is dedicated for tracking registered badge labels.
If you write or publish a NewGRF which introduces a new badge label, please also add comment about it here.
However, before you introduces a new label reconsider if any of available labels fulfills the same purpose. Do not introduces two or more labels for same purpose.
If you introduce a new class, please also provide a table for badges that belong to it.
For ease of maintenance keep alphabetical order.

'''Note:''' This page is maintained manually and some grf developers oppose to that despicable labor. Therefore you might also want to visit https://github.com/Rito13/BaNaNaS-get_badge_labels/blob/main/gen_docs%2Fpublic_labels.md, which is updated automatically with content uploaded to BaNaNaS.

== Classes ==

{| class="wikitable sortable"
! Label !! Introduced by !! Comment
|-
| flag || OpenTTD default badges || Country/Region
|-
| livery || OpenTTD default badges || Livery
|-
| power || OpenTTD default badges || Propulsion
|-
| region || OpenTTD default badges || Region
|-
| role || OpenTTD default badges || Role
|-
| zone || OpenTTD default badges || Zone
|}

== Badges ==

=== Flag ===
{| class="wikitable sortable"
! Label !! Introduced by !! Comment
|-
| flag/AD || OpenTTD default badges || Andorra
|}

=== Livery ===
{| class="wikitable sortable"
! Label !! Introduced by !! Comment
|-
| livery/2cc || OpenTTD default badges || Dual company colour (2CC)
|-
| livery/random/1cc || OpenTTD default badges || Random based on first company colour
|-
| livery/random/2cc || OpenTTD default badges || Random based on second company colour
|}

=== Power ===
{| class="wikitable sortable"
! Label !! Introduced by !! Comment
|-
| power/battery || OpenTTD default badges || Battery
|-
| power/diesel || OpenTTD default badges || Diesel
|-
| power/electric || OpenTTD default badges || Electric
|-
| power/electric/ac || OpenTTD default badges || Electric (AC)
|-
| power/electric/dc || OpenTTD default badges || Electric (DC)
|-
| power/steam || OpenTTD default badges || Steam
|-
| power/turbine || OpenTTD default badges || Gas Turbine
|}

=== Region ===
{| class="wikitable sortable"
! Label !! Introduced by !! Comment
|-
| region/africa || OpenTTD default badges || Africa
|-
| region/africa/eastern || OpenTTD default badges || Eastern Africa
|-
| region/africa/middle || OpenTTD default badges || Middle Africa
|-
| region/africa/northern || OpenTTD default badges || Northern Africa
|-
| region/africa/southern || OpenTTD default badges || Southern Africa
|-
| region/africa/western || OpenTTD default badges || Western Africa
|-
| region/america || OpenTTD default badges || Americas
|-
| region/america/caribbean || OpenTTD default badges || Caribbean
|-
| region/america/central || OpenTTD default badges || Central America
|-
| region/america/northern || OpenTTD default badges || Northern America
|-
| region/america/south || OpenTTD default badges || South America
|-
| region/asia || OpenTTD default badges || Asia
|-
| region/asia/central || OpenTTD default badges || Central Asia
|-
| region/asia/eastern || OpenTTD default badges || Eastern Asia
|-
| region/asia/southeastern || OpenTTD default badges || South-eastern Asia
|-
| region/asia/southern || OpenTTD default badges || Southern Asia
|-
| region/asia/western || OpenTTD default badges || Western Asia
|-
| region/europe || OpenTTD default badges || Europe
|-
| region/europe/eastern || OpenTTD default badges || Eastern Europe
|-
| region/europe/northern || OpenTTD default badges || Northern Europe
|-
| region/europe/southern || OpenTTD default badges || Southern Europe
|-
| region/europe/western || OpenTTD default badges || Western Europe
|-
| region/oceania || OpenTTD default badges || Oceania
|-
| region/oceania/australia_and_new_zealand || OpenTTD default badges || Australia and New Zealand
|-
| region/oceania/melanesia || OpenTTD default badges || Melanesia
|-
| region/oceania/micronesia || OpenTTD default badges || Micronesia
|-
| region/oceania/polynesia || OpenTTD default badges || Polynesia
|}

=== Role ===
{| class="wikitable sortable"
! Label !! Introduced by !! Comment
|-
| role/banking || OpenTTD default badges || Banking
|-
| role/express_freight || OpenTTD default badges || Express freight
|-
| role/express_passenger || OpenTTD default badges || Express passenger
|-
| role/freight || OpenTTD default badges || Freight
|-
| role/heavy_freight || OpenTTD default badges || Heavy freight
|-
| role/light_freight || OpenTTD default badges || Light freight
|-
| role/mail || OpenTTD default badges || Mail
|-
| role/mixed || OpenTTD default badges || Mixed
|-
| role/passenger || OpenTTD default badges || Passenger
|-
| role/prototype || OpenTTD default badges || Prototype
|-
| role/restaurant_car || OpenTTD default badges || Restaurant car
|-
| role/shunting || OpenTTD default badges || Shunting
|-
| role/snowplough || OpenTTD default badges || Snowplough
|-
| role/utility || OpenTTD default badges || Utility
|}

=== Zone ===
{| class="wikitable sortable"
! Label !! Introduced by !! Comment
|-
| zone/agricultural || OpenTTD default badges || Agricultural
|-
| zone/com || OpenTTD default badges || Commercial
|-
| zone/com/high || OpenTTD default badges || High density commercial
|-
| zone/com/low || OpenTTD default badges || Low density commercial
|-
| zone/com/medium || OpenTTD default badges || Medium density commercial
|-
| zone/forestry || OpenTTD default badges || Forestry
|-
| zone/general || OpenTTD default badges || General
|-
| zone/ind || OpenTTD default badges || Industrial
|-
| zone/ind/high || OpenTTD default badges || High density industrial
|-
| zone/ind/low || OpenTTD default badges || Low density industrial
|-
| zone/ind/medium || OpenTTD default badges || Medium density industrial
|-
| zone/leisure || OpenTTD default badges || Leisure
|-
| zone/mixed || OpenTTD default badges || Commercial & residential
|-
| zone/mixed/high || OpenTTD default badges || High density commercial & residential
|-
| zone/mixed/low || OpenTTD default badges || Low density commercial & residential
|-
| zone/mixed/medium || OpenTTD default badges || Medium density commercial & residential
|-
| zone/other || OpenTTD default badges || Other
|-
| zone/public || OpenTTD default badges || Public
|-
| zone/res || OpenTTD default badges || Residential
|-
| zone/res/high || OpenTTD default badges || High density residential
|-
| zone/res/low || OpenTTD default badges || Low density residential
|-
| zone/res/medium || OpenTTD default badges || Medium density residential
|-
| zone/transport || OpenTTD default badges || Transport
|}

Action0/Stations

2026-02-15T16:22:54Z

Rito12: /* General Flags (13) */

==Introduction==

Defining properties of new stations.

Unlike vehicles, the new stations have no equivalent in TTD. The IDs are therefore free to be chosen and will in fact be allocated automatically. In action 0, you only specify IDs relative to the set, i.e. the ID of the first station type is 00, the second station type is 01 and so on.

{{ttdp|}} In TTDPatch each game can only have 255 station IDs for all active grf files.

The only property you '''must''' set for each station ID is 08 (in addition to defining an [[Action3|action 3]] for it), anything else can be left at the default. It must be the first property you set for each station ID, because the station ID is actually undefined until it has been assigned a class through property 08. Also, all station IDs must get their classes in the right order, starting from ID 00 onwards.

== Properties ==

{| |-
!Number!![[GRFActionsDetailed|Size]]!!Version!!Description
|-
|08||D||{{ottdp|0.6|2.5|ttdprev=alpha 19}}||Class ID, see below
|-
|09||V||{{ottdp|0.6|2.5|ttdprev=alpha 20}}||Sprite layout, see below
|-
|0A||B/B*||{{ottdp|0.6|2.5|ttdprev=alpha 20}}/{{ottdp|14.0}}||Copy sprite layout
|-
|0B||B||{{ottdp|0.6|2.5|ttdprev=alpha 22}}||Callback flags
|-
|0C||B||{{ottdp|0.6|2.5|ttdprev=alpha 22}}||Bit mask of disabled numbers of platforms
|-
|0D||B||{{ottdp|0.6|2.5|ttdprev=alpha 22}}||Bit mask of disabled platform lengths
|-
|0E||V||{{ottdp|0.6|2.5|ttdprev=alpha 22}}||Define custom layout, see below
|-
|0F||B/B*||{{ottdp|0.6|2.5|ttdprev=alpha 22}}/{{ottdp|14.0}}||Copy custom layout from stationid given by argument
|-
|10||W||{{ottdp|0.6|2.5|ttdprev=alpha 25}}||Little/lots threshold
|-
|11||B||{{ottdp|0.6|2.5|ttdprev=alpha 27}}||Pylon placement
|-
|12||D||{{ottdp|0.6|2.5|ttdprev=alpha 30}}||Bit mask of cargo type triggers for random sprites
|-
|13||B||{{ottdp|0.6|2.5|ttdprev=alpha 30}}||General flags
|-
|14||B||{{ottdp|0.6|2.5|ttdprev=alpha 47}}||Overhead wire placement
|-
|15||B||{{ottdp|0.6|2.5|ttdprev=alpha 51}}||Can train enter tile
|-
|16||W||{{ottdp|0.7|2.5|ttdprev=beta 9}}||Animation information
|-
|17||B||{{ottdp|0.7|2.5|ttdprev=beta 9}}||Animation speed
|-
|18||W||{{ottdp|0.7|2.5|ttdprev=beta 9}}||Animation triggers
|-
|1A||V||{{ottdp|1.2|no|ottdrev=r22518}}||Advanced sprite layout with register modifiers
|-
|1B|| || ||Reserved
|-
|1C||W||{{ottdp|14}}||Station name
|-
|1D||W||{{ottdp|14}}||Station class name
|-
|1E||V||{{ottdp|15}}||Station sprite layout flags
|-
|1F||W n*W||{{ottdp|15}}||List of badges
|-
|20||B* n*B||{{ottdp|15}}||Minimum height list.
|-
|21||B* n*B||{{ottdp|15}}||Blocked bridge pillars list.
|}

Unofficial additions and changes. Don't rely on them to ever work this way in OpenTTD or TTDPatch:
{| |-
!Number!![[GRFActionsDetailed|Size]]!!Version!!Description
|-
|1B||8*B||whatever-PP||Minimum bridge height for bridges over stations
|}

== Description ==

=== Station class (08) ===
TTDPatch groups sets of new station graphics into various classes.  The classes can be selected by the top dropdown list in the construction window, and the individual stations within the class from the bottom dropdown list.  In addition, each station can alter its appearance using [[VariationalAction2|variational]] and/or [[RandomAction2|random]] action 2 entries.

Only two classes are pre-defined:

{| |-
!Name!!Class ID!!Intended use for station
|-
|DFLT||44 46 4C 54||Default, no special station type
|-
|WAYP||57 41 59 50||Non-cargo stations, waypoints, signal boxes etc.
|}

You may simply use other classes than the above, as long as no more than (at the moment) 16 classes are used among all active .grf files at any time.

{{ottdp|15}} Station classes which start with the byte FF are considered waypoint classes, and will appear in the waypoint construction window instead of the station construction window.

When a waypoint station is built, it will not accept cargo nor will any cargo appear from nearby industries or towns.  Trains will not stop at waypoint stations, regardless of the non-stop order and/or the nonstop switch.

=== Sprite layout (09) ===
This controls what sprites are displayed, where they are displayed, and in what order.  The property is variable sized, and contains the data for all 8 possible station tile types.  If this property is set, the num-ent in the corresponding [[Action1|action 1]] need not be equal to 12 (hex), it can in fact be any number, and any number of sprites can be displayed in any order.

The data is specified as data for all eight tiles in this way:

<pre><num> <data1> <data2> ... <datan></pre>

{| |-
!Size!!Name!!Meaning
|-
|B*||num||Number of different tiles supported (see below)
|-
|V||data1...||The variable size data for each of the <num> tiles, as specified below
|}

===== Number of tiles supported =====
* Normally this is 8, but you can specify fewer as well
* Using callback flags bit 1, specifying more makes sense too
* This value must be the same for all stations set by this action 0, even though it must be repeated for the prop. 09 definition of each station ID as well

(Note that num is an extended byte, see [[GRFActionsDetailed]].)

The content of each of the (usually eight) data sets is either a new sprite layout:

{| |-
!Size!!Name!!Meaning
|-
|D||groundsprite||the sprite to draw for the rails; this is by default a TTD sprite, but with bit 31 set an [[Action1|action 1]] sprite (42D+X) may be specified
|-
|V||spritedata||the data for station sprites, see below; each has a size of 10 bytes, and there may be several
|-
|B||80||a literal 80 ends the list of sprites for this tile
|}
or, alternatively, the instruction to use TTD's layout by using four zero bytes 00 00 00 00 instead of the groundsprite bytes. You can use [http://www.bytetransfer.de/projects/ttdpatch/docs/spriteidmapping.php the online sprite ID converter] to look up the sprite IDs you can use for all the climates.

One can draw two types of sprites.  One type is one that establishes a new 3D bounding box for use by the sprite sorter.  The other type shares the 3D bounding box of the previous sprite(s).  It must not be larger than the sprite which established the bounding box, nor must any part of it be outside this box.  For simplicity, it should have the exact same dimensions as the sprite it shares the bounding box with.  The latter type is supported in the station construction window display only since TTDPatch 2.6 r1684.

The spritedata of sprites with their own bounding box has this format:

{| |-
!Size!!Name!!Meaning
|-
|B||xofs||x-offset from northern tile corner
|-
|B||yofs||y-offset from northern tile corner
|-
|B||zofs||z-offset from northern tile corner
|-
|B||xextent||size of sprite in x direction
|-
|B||yextent||size of sprite in y direction
|-
|B||zextent||size of sprite in z direction
|-
|D||sprite||sprite number to draw
|}

The spritedata of sprites sharing the bounding box has this format:

{| |-
!Size!!Name!!Meaning
|-
|B||xofs||x-offset relative to previous sprite
|-
|B||yofs||y-offset relative to previous sprite
|-
|B||80||a literal 80
|-
|B||00||(ignored)
|-
|B||00||(ignored)
|-
|B||00||(ignored)
|-
|D||sprite||sprite number to draw
|}

Since OpenTTD r18959 you can draw multiple ground sprites for a tile, which is useful if you want to use the usual rail/grass/concrete groundtile, but still need to add features to it without using a new bounding box. To do so use the syntax of sprites sharing the previous bounding box, but use it before the first bounding box definition. xpixeloffset and ypixeloffset refer to the usual spot of groundtiles. The same feature is also partially supported in TTDPatch since TTDPatch 2.6 r2312: TTDPatch ignores the xofs and yofs fields and always uses (0,0) for the offset. If you are developing a GRF that needs to be compatible with both OpenTTD and TTDPatch, you should always keep xofs and yofs zero to get the same effect in both games.
Note however that both implementations do not consider the [[Action0/Stations#General_Flags_.2813.29|setting of prop13 bit 0]], hence these "multiple ground sprites" have to be always part of the building sprites set and cannot be part of the different sprite set for ground sprites.

The sprite number can have the following values (remember to use little endian, i.e. reversed byte order):

{| |-
!Number!!Sprite
|-
|0000042D+X||use sprite X from the corresponding [[Action1|action 1]] block (i.e. 0000042D for the first, 0000042E for the second, etc.)
|-
|0000842D+X||same, but draw it using company colour translation
|-
|0322442D+X||same, but draw in transparent mode (actual colours of the sprite are disregarded entirely); supported in station construction window display since TTDPatch 2.6 r1683
|-
|RRRR842D+X||draw sprite with colour translation defined in sprite RRRR; available since TTDPatch 2.6 r1683
|}

With bit 31 set, this sprite will refer to a TTD sprite, not the action 1 sprite. For the first ground sprite the reverse meaning applies.

Depending on the railtype the sprites may get additional offsets:

{| |-
! !! Normal/electrified rail !! Monorail !! Maglev
|-
|TTD sprites || 0 || 82 || 164
|-
|Action 1 sprite (first ground sprite) || 0 || 1 || 2
|-
|Action 1 sprite (other sprites in the layout) || 0 || 0 || 0
|}

So, TTD sprites and the first ground sprite are affected by the railtype, while other action 1 sprites in the layout are not. The offset "82" refers to the offset between the default TTD track sprites; if you are using non-track ground sprites which are not from an action 1, you need to supply fake spritenumbers which preemptively reverse the offsets (that is, you need different sprite layouts for every railtype your station is available for).

Setting bit 30 forces this sprite to be displayed normally even in "transparent buildings" mode (supported only in TTDPatch 2.6 r1695 and later).

See below for an example of linked sprites as well as transparent sprites (e.g. for a station roof).

Note that the coordinates here are 3D coordinates with x running from top-right to bottom-left and y running from top-left to bottom-right, with the tile dimensions being 16x16 (and 8 for one height level). This means the x and y values should always be within 0-15 (decimal).

This is different to and independent from the x/y offsets used in the actual .NFO file.  The 3D bounding box is used by TTD's sprite sorter to figure out the order in which to draw the sprites, as well as telling it which sprites to draw, because those whose bounding box falls outside the currently updated screen rectangle will not be drawn.  Make sure the 3D bounding box is large enough to contain the entire sprite, but not so large that the sprite sorter can't determine which sprites should be in front.

This means that the order in which you specify sprites is irrelevant.  Sprites will get drawn from back to front, in the order which the sprite sorter determines as correct, from their bounding boxes.  There are two exceptions, however:
* Sprites sharing the same bounding box will always be drawn in the given order.
* The station construction window display doesn't use the sprite sorter. Tiles that may be displayed in that window need to be specified in the correct drawing order, back to front.

=== Copy sprite layout (0A) ===

This is not a property as such, but an action.  It takes as argument a byte which is interpreted as station-ID to copy the custom sprite layout from.

Since {{ottdp|14.0}} this property is now an extended byte.

=== Callback flags (0B) ===
For stations, the following [[callbacks]] can be defined by setting the corresponding bit in property 0B:

{| |-
!Bit!!Value!!Variable 0C value!!Callback
|-
|0||1||13||Whether to make station available in construction window (non-zero callback return) or not (callback returns zero)
|-
|1||2||14||Use callback to select sprite layout
|-
|2||4||141||Decide next animation frame
|-
|3||8||142||Decide animation speed
|-
|4||10||149||Custom slope check
|}
Bit is the bit you have to set, you do this by adding all the values for all the bits. Variable 0C value is what variable 0C will be set to, for checking it in the [[VariationalAction2|VarAction2]] for callbacks.

=== Selection of numbers of platforms and length (0C, 0D) ===

By default all platform lengths and any number of platforms is available for the new stations.  Using these properties, you can choose which ones should be unavailable by setting the corresponding bit in the property.

The values are a byte, used as a bit mask.  Bits 0 to 6 control the availability of number or length 1 to 7, and bit 7 controls the availability of the "+7" button.  Each bit that is set disables the corresponding length or number of platforms.

For compatibility with "largestations off", at least one length between 1 and 5 (bits 0 to 4) and one number of platforms between 1 and 4 (bits 0 to 3) must be available, i.e. at least one of these bits must be unset.

=== Define custom layout (0E) ===

This allows choosing which tile type is built at which tile of a newly built station.  There are four different types, which TTD normally defines as

{| |-
!Tile type!!Appearance
|-
|00||plain platform
|-
|02||platform with building
|-
|04||platform with roof, left side
|-
|06||platform with roof, right side
|}

Since {{ottdp|15}}, all even values up to FE are supported if the sprite layout is defined via property 09/0A.

These numbers are used for stations in NE-SW direction, or these numbers plus one for stations in the NW-SE direction.  To define a custom layout, use this format:

{| |-
!Size!!Name!!Meaning
|-
|B||length||length of platforms for this layout
|-
|B||number||number of platforms for this layout
|-
|V||tiles||length*number bytes of tile types, one platform after another, only 00, 02, 04 or 06 are allowed as values
|}

Repeat this as often as necessary to define the layouts for all supported combinations of length and number.  End the definitions with a 00 00 (zero length and zero number).  Any combinations that are not defined will be built using TTD's default layout.
Note that it may be easier to draw different sprite sets using a [[VariationalAction2|VarAction2]] based on [[VarAction2Stations#Platform info 40 41 46 47 49|station variable 40]], rather than redefining the layout.  In addition, [[Callbacks#Custom station layout 24|callback 24]] will be used to further customize the layout as defined by this property (or by TTD if no prop 0E layout is available). This may also be easier than defining a prop 0E layout for every combination of length and number of platforms.

=== Copy custom layout (0F) ===

Similar to property 0A, this copies the custom layout from the station-ID given by the argument.

Since {{ottdp|14.0}} this property is now an extended byte.

=== Little/lots threshold (10) ===
Amount of cargo for switching from "little" to "lots" of cargo.  TTDPatch separates the full range of cargo amounts (0 to 4095) into two separate subranges, "little" and "lots" of cargo.  This allows better control of cargo amount based graphics (if needed).  Property 10 specifies at what amount of cargo the patch is to switch from one to the other subrange.  See [[Action2Stations|Action 2 for stations]] for more information.

=== Pylon placement (11) and wire placement (14) ===
Prop. 11 sets which tile types should have pylons when used with electrified tracks. By default, tiles 0-3 (default stations without roof) have pylons, and tiles 4-7 (default stations with roof) don't. This is a bit mask of tile types, with a bit set meaning that a pylon should be drawn. The tile types here do not consider [[Callbacks#Station sprite layout 14|callback 14]], but rather the type as it was built, i.e. from prop. 0E.

Prop. 14 works in a similar way, except that it sets the tile types on which there should be ''no'' wires displayed. With the default value of "00", wires are displayed everywhere, and for each bit set, the wire is omitted on that tile type.

This property should only be used when the wires cause problems with the sprite sorter, because even when the wire is obscured by a station hall or similar, it should still show up in transparent mode so that each tile can easily be verified as being electrified.

{{ottdp|15}} Note: This property only allows setting the flags of the first 8 sprite layouts. Use Property 1E instead to set flags when more sprite layouts are used via prop. 0E or [[Callbacks#Custom_station_layout_.2824.29|callback 24]].

=== Cargo types for random triggers (12) ===

This sets which cargo types should trigger re-randomizing. The cargo types are given as a bitmask of the bits from column 3 (type B) in CargoTypes.  If nothing is set (the default), the no random triggers will happen, to conserve CPU time.

With GRF version 7 and above, the interpretation of bits changes. Instead of climate-dependent cargo slot numbers (type B), you have to set the bits of climate-independent cargo ID (type A).

{{ottd|15.0}} Since 15.0, a default cargo translation table corresponding to the climate is used if one is not provided.

=== General Flags (13) ===

{| |-
!Bit!!Value!!Version!!Meaning
|-
|0||1||{{ottdp|0.7|2.5}}||use different sprite set for ground sprites ([[GlobalVariables#Extra_callback_info_.2810_.2F_-.29_and_.2818_.2F_-.29|var. 10]] is 1 for ground sprites, 0 otherwise)
|-
|1||2||{{ottdp|0.6|2.5}}||When calculating the cargo amount to display, divide the amount by half of the station perimeter (to simulate cargo distributed over the station)
'''Depricated''' since {{ottd|16.0}}, use bit 5 instead.
|-
|2||4||{{ottdp|0.7|2.5}}||[[Callbacks#Next animation frame (1A/26/141/153/158)|callback 141]] needs random bits in var. 10
|-
|3||8||{{ottdp|1.0|2.6}}||Use custom foundations on sloped tiles (the lowest byte of [[GlobalVariables#Extra_callback_info_.2810_.2F_-.29_and_.2818_.2F_-.29|var. 10]] is 2 for foundation sprites)
|-
|4||10||{{ottdp|1.0|2.6}}||When bit 3 is set, use extended foundation block instead of the simple one
|-
|5||20||{{ottdp|16.0}}||When calculating the cargo amount to display, divide the amount by the station area (to simulate cargo distributed over the area of the station)
|}

Bit 3 works somewhat similarly to bit 0: your sprite selection will be called again, with 2 in the lowest byte of [[GlobalVariables#Extra_callback_info_.2810_.2F_-.29_and_.2818_.2F_-.29|variable 10]]. If the chain ends on a callback result, the program will assume the foundation selection has failed and will use the default foundaton sprites. The low word of [[GlobalVariables#Extra_callback_info_.2810_.2F_-.29_and_.2818_.2F_-.29|variable 18]] will contain the tile type of the current tile; if you have [[Callbacks#Station sprite layout (14)|callback 14]] enabled, this will be the its return value - otherwise, the default TTD types (platform with building, platform with left roof etc.) are used. In either case, one is added for the NW-SE orientation, in case your station needs different foundations depending on its orientation. Bits 16 and 17 are set if the NW and and NE foundations are to merged with the corresponding neighbour tile, so you shouldn't draw the corresponding edge in the foundation sprite. Other bits of variable 10 and variable 18 are reserved for future use.

Your sprite selection code should select a foundation sprite block. The contents of this block depends on whether bit 4 is set or not.
* Bit 4 clear (simple foundations):
[[File:simple_foundations.png]]

The programme will combine the needed foundation from these 8 sprites depending on the current slope. You don't need to care about the merge data in bits 16..17 of [[GlobalVariables#Extra_callback_info_.2810_.2F_-.29_and_.2818_.2F_-.29|variable 18]]; it will be taken care of that automatically by adding the 7th and 8th sprite only when necessary.
* Bit 4 set (extended foundations):
[[File:extended_foundations.png]]

You need to have one sprite for every slope that's possible below a rail station. The correct one will be automatically selected depending on the current slope. It can't handle the merging itself, however, so you need four foundation blocks: one with no edges removed, one with the NW edge removed, one with the NE edge removed and one with both north edges removed. Your sprite selection code is responsible for selecting the correct of those blocks according to the merge info in [[GlobalVariables#Extra_callback_info_.2810_.2F_-.29_and_.2818_.2F_-.29|variable 18]].

In both cases, you can put an additional value into register 100h, which will serve as an offset into the selected block. If you don't modify register 100h during the chain, it will default to 0. It is important that the dimensions of these sprites remain the same - thus bit 6 in the real sprites must be set to prevent GRFCodec from trimming the empty blue areas. The offset of these foundations must be -31 to the X direction and -9 to the Y direction.

=== Can train enter tile (15) ===

Like props. 11 and 14, this value contains eight bits relating to the eight possible tile types. If a bit is set, trains are prevented from routing through or entering any tile of this type.

{{ottdp|15}} Note: This property only allows setting the flags of the first 8 sprite layouts. Use Property 1E instead to set flags when more sprite layouts are used via prop. 0E or [[Callbacks#Custom_station_layout_.2824.29|callback 24]].

=== Animation information (16) ===

The low byte specifies the number of animation frames minus one, so 00 means 1 frame, 01 means 2 frames etc. The maximum number of frames is 256, although you can have some problems if your animation exceeds FD (253) frames. The high byte must be 0 for non-looping animations and 01 for looping animations. Every other value is reserved for future use. In addition, if the whole word contains FFFF, animation is turned off for this station (this is the default value).
Since you can't have properties for individual station tiles, this property applies for every tile of the station. If you don't want to animate some tiles, you should check the current position during [[Callbacks#Animation control (1B/25/140/152/159)|callback 140]] and return FD if the current tile doesn't need to be animated. If you also need animations of different length per tile, you'll have to use [[Callbacks#Next animation frame (1A/26/141/153/158)|callback 141]] for that.

=== Animation speed (17) ===
The meaning is the same as for [[Action0Houses#Animation Speed 1B|house property 1B]], but the lower limit is 0 instead of 2, so the fastest possible animation changes frames every game tick (27ms). The default value is 2.

=== Animation triggers (18) ===
This is a bit mask of events that should trigger [[Callbacks#Animation control (1B/25/140/152/159)|callback 140]], allowing to change the animation state

{| |-
!Property bit, var18 byte 0!!Property value!!Version!!Meaning!!Happens on!!Var 18 byte 1
|-
|0||1||{{ottdp|0.7|2.5}}||Station part is built||the newly built tiles||
|-
|1||2||{{ottdp|0.7|2.5}}||New cargo arrives to station||whole station||Cargo type <ref name="cargotype">Bits 8..15 of var 18 contain the triggering cargo type. If your GRF has a cargo translation table, the cargo type will be an index in that table, or FFh if the cargo isn't in the table. If you don't have a cargo translation table, the cargo type will simply be the climate-dependent cargo type number.</ref>
|-
|2||4||{{ottdp|0.7|2.5}}||A cargo type gets removed from station||whole station||Cargo type <ref name="cargotype"/>
|-
|3||8||{{ottdp|0.7|2.5}}||Train enters station (starts loading/unloading)||platform where the train is||
|-
|4||10||{{ottdp|0.7|2.5}}||Train leaves station (done loading/unloading)||platform where the train is||
|-
|5||20||{{ottdp|1.2|2.5|ottdrev=r22746}}||Train loads/unloads cargo||platform where the train is||
|-
|6||40||{{ottdp|0.7|2.5}}||Every 250 ticks||whole station||
|-
|7||80||{{ottdp|15|no}}||Tile is processed in the periodic processing loop||single tile||
|-
|8||100||{{ottdp|15|no}}||Train reserves platform (using PBS)||platform where the train reserved||
|}

The remaining bits are reserved for future triggers, they must be zero for now.

The "happens on" column tells which tiles will [[Callbacks#Animation control (1B/25/140/152/159) |callback 140]] be called on.

<references/>

=== Advanced sprite layout with register modifiers (1A) ===

{{ottdp|1.2|no|ottdrev=r22518}}
Format:
1A <num-layouts> <0x40 + num-sprites>
<groundsprite> <flags> [<register/value>]...
[ <buildingsprite> <flags>
( <xoffset> <yoffset> <zoffset> <xextent> <yextent> <zextent>
| <xpixeloffset> <ypixeloffset> 80)
[<register/value>]...
]...

For further details see [https://wiki.openttd.org/en/Archive/Development/Advanced%20Sprite%20Layout#stations here] for now.

=== Minimum bridge height (1B) ===

This property allows building bridges over stations.

The bridge height property defines minimum clearances required for a bridge for each of the four [[Action0/Stations#Define_custom_layout_.280E.29|tile types]] of this station (or zero to not allow any bridge). Values are given in "height level" units (1 level == 8px).

{| class="wikitable" |-
!Height (1)!!Appearance
|-
| style="text-align:center;" |x1 y1 ||plain platform
|-
| style="text-align:center;" |x2 y2 ||platform with building
|-
| style="text-align:center;" |x3 y3 ||platform with roof, left side
|-
| style="text-align:center;" |x4 y4 ||platform with roof, right side
|}
(1) where the values are one byte pairs (x-direction, y-direction) expressed in hexadecimal notation.

Syntax:

1B <1st pair> <2nd pair> <3rd pair> <4th pair> 
1B x1 y1 x2 y2 x3 y3 x4 y4 
1B 01 01 02 02 03 03 03 03 // 8px 16px 24px 24px

This property is currently only available for JGR's Patch Pack (v0.26.0 and later) and the developmental "New Map Features" (NMF) fork of OpenTTD.

=== Station name (1C) ===

=== Station class name (1D) ===

=== Station sprite layout flags (1E) ===

{{ottdp|15}} Since OpenTTD supports more than 8 sprite layouts to be used, props. 11, 14 and 15 are not sufficient to set the flags for all usable sprite layouts. This property is variable length and allows these flags to be set for each tile beyond the original limit of 8.

The data is specified as flags for all sprite layouts in this way:

<pre><num> <flags1> <flags2> ... <flagsn></pre>

{| |-
!Size!!Name!!Meaning
|-
|B*||num||Number of different tiles supported (see below)
|-
|B||flags1...||The flags for each of the <num> tiles, as specified below
|}

The flag values are as follows:

{| |-
|Bit||Value||Meaning
|-
|0||01||Tile should contain catenary pylons.
|-
|1||02||Tile should NOT contain catenary wires.
|-
|2||04||Tile is blocked to vehicles.
|}

These should be combined as needed.

===Minimum Bridge Height (20)===

{{ottdp|15}} This property allows building bridges over stations.

The bridge height property defines minimum clearances required for a bridge for the sprite layouts of this station (or zero to not allow any bridge). Values are given in "height level" units (1 level == 8px).

The data is specified as minimum height for all sprite layouts in this way:

<pre><num> <height1> <height2> ... <heightn></pre>

{| |-
!Size!!Name!!Meaning
|-
|B*||num||Number of different tiles supported (see below)
|-
|B||height...||The minimum heights for each of the <num> tiles.
|}

===Blocked Pillar Information (21)===

{{ottdp|15}} Allows information to provided about blocked bridge pillars to assist the game in hiding pillars if necessary depending on what is above the station tile. Blocking a pillar prevents the pillar from being drawn. It does not prevent the station being bridgeable.

The data is specified as blocked pillar flags for all sprite layouts in this way:

<pre><num> <flags1> <flags2> ... <flagsn></pre>

{| |-
!Size!!Name!!Meaning
|-
|B*||num||Number of different tiles supported (see below)
|-
|B||flags...||The blocked pillar flags for each of the <num> tiles.
|}

The flag bits are as follows:

{| |-
|Bit||Value||Meaning
|-
|0||01||Tile layout blocks a pillar on the west corner of the tile.
|-
|1||02||Tile layout blocks a pillar on the south corner of the tile.
|-
|2||04||Tile layout blocks a pillar on the east corner of the tile.
|-
|3||08||Tile layout blocks a pillar on the north corner of the tile.
|-
|4||10||Tile layout blocks a wall on the north east side of the tile.
|-
|5||20||Tile layout blocks a wall on the south east side of the tile.
|-
|6||40||Tile layout blocks a wall on the south west side of the tile.
|-
|7||80||Tile layout blocks a wall on the north west side of the tile.
|}

These should be combined as needed.

== Examples ==

=== Using TTD's sprite layouts for certain tiles ===

To use TTD's layout, you use <code>00 00 00 00</code> for the ground sprite number and leave off everything else.

So instead of for example

F4 03 00 00
00 00 00 10 05 02 2E 84 00 00
00 0B 00 10 05 02 30 84 00 00
80

you just put

00 00 00 00

=== Using transparent sprites ===

You can use transparent sprites to make for example the roof translucent like in TTD's stations. The roof of TTD's stations is made like this:

00 00 10 10 10 0A 37 84 00 00
00 00 80 00 00 00 3B 44 22 03

The first sprite here is the non-transparent frame of the roof, drawn in company colours (it has bit 15 set). The second part is a special "linked" sprite without its own bounding box, it shares that of the previous sprite. That's done by setting the z offset to 80.

To make that second sprite transparent, bit 14 is set in the sprite number, and the upper word is set to 322 (*), so 0322443B means to take sprite 43B and draw it in transparent mode. The colours of that sprite are ignored entirely, every pixel in colour 0 is fully transparent, and all other pixels are semi-transparent (essentially just causing what they are drawn over to become darker).

(*) This is the [[RecolorSprites#Default_recolour_sprites | recolour sprite]] for the glass effect.

Action0/Stations

2026-02-15T16:21:41Z

Rito12: /* General Flags (13) */ DivByStationArea flag.

==Introduction==

Defining properties of new stations.

Unlike vehicles, the new stations have no equivalent in TTD. The IDs are therefore free to be chosen and will in fact be allocated automatically. In action 0, you only specify IDs relative to the set, i.e. the ID of the first station type is 00, the second station type is 01 and so on.

{{ttdp|}} In TTDPatch each game can only have 255 station IDs for all active grf files.

The only property you '''must''' set for each station ID is 08 (in addition to defining an [[Action3|action 3]] for it), anything else can be left at the default. It must be the first property you set for each station ID, because the station ID is actually undefined until it has been assigned a class through property 08. Also, all station IDs must get their classes in the right order, starting from ID 00 onwards.

== Properties ==

{| |-
!Number!![[GRFActionsDetailed|Size]]!!Version!!Description
|-
|08||D||{{ottdp|0.6|2.5|ttdprev=alpha 19}}||Class ID, see below
|-
|09||V||{{ottdp|0.6|2.5|ttdprev=alpha 20}}||Sprite layout, see below
|-
|0A||B/B*||{{ottdp|0.6|2.5|ttdprev=alpha 20}}/{{ottdp|14.0}}||Copy sprite layout
|-
|0B||B||{{ottdp|0.6|2.5|ttdprev=alpha 22}}||Callback flags
|-
|0C||B||{{ottdp|0.6|2.5|ttdprev=alpha 22}}||Bit mask of disabled numbers of platforms
|-
|0D||B||{{ottdp|0.6|2.5|ttdprev=alpha 22}}||Bit mask of disabled platform lengths
|-
|0E||V||{{ottdp|0.6|2.5|ttdprev=alpha 22}}||Define custom layout, see below
|-
|0F||B/B*||{{ottdp|0.6|2.5|ttdprev=alpha 22}}/{{ottdp|14.0}}||Copy custom layout from stationid given by argument
|-
|10||W||{{ottdp|0.6|2.5|ttdprev=alpha 25}}||Little/lots threshold
|-
|11||B||{{ottdp|0.6|2.5|ttdprev=alpha 27}}||Pylon placement
|-
|12||D||{{ottdp|0.6|2.5|ttdprev=alpha 30}}||Bit mask of cargo type triggers for random sprites
|-
|13||B||{{ottdp|0.6|2.5|ttdprev=alpha 30}}||General flags
|-
|14||B||{{ottdp|0.6|2.5|ttdprev=alpha 47}}||Overhead wire placement
|-
|15||B||{{ottdp|0.6|2.5|ttdprev=alpha 51}}||Can train enter tile
|-
|16||W||{{ottdp|0.7|2.5|ttdprev=beta 9}}||Animation information
|-
|17||B||{{ottdp|0.7|2.5|ttdprev=beta 9}}||Animation speed
|-
|18||W||{{ottdp|0.7|2.5|ttdprev=beta 9}}||Animation triggers
|-
|1A||V||{{ottdp|1.2|no|ottdrev=r22518}}||Advanced sprite layout with register modifiers
|-
|1B|| || ||Reserved
|-
|1C||W||{{ottdp|14}}||Station name
|-
|1D||W||{{ottdp|14}}||Station class name
|-
|1E||V||{{ottdp|15}}||Station sprite layout flags
|-
|1F||W n*W||{{ottdp|15}}||List of badges
|-
|20||B* n*B||{{ottdp|15}}||Minimum height list.
|-
|21||B* n*B||{{ottdp|15}}||Blocked bridge pillars list.
|}

Unofficial additions and changes. Don't rely on them to ever work this way in OpenTTD or TTDPatch:
{| |-
!Number!![[GRFActionsDetailed|Size]]!!Version!!Description
|-
|1B||8*B||whatever-PP||Minimum bridge height for bridges over stations
|}

== Description ==

=== Station class (08) ===
TTDPatch groups sets of new station graphics into various classes.  The classes can be selected by the top dropdown list in the construction window, and the individual stations within the class from the bottom dropdown list.  In addition, each station can alter its appearance using [[VariationalAction2|variational]] and/or [[RandomAction2|random]] action 2 entries.

Only two classes are pre-defined:

{| |-
!Name!!Class ID!!Intended use for station
|-
|DFLT||44 46 4C 54||Default, no special station type
|-
|WAYP||57 41 59 50||Non-cargo stations, waypoints, signal boxes etc.
|}

You may simply use other classes than the above, as long as no more than (at the moment) 16 classes are used among all active .grf files at any time.

{{ottdp|15}} Station classes which start with the byte FF are considered waypoint classes, and will appear in the waypoint construction window instead of the station construction window.

When a waypoint station is built, it will not accept cargo nor will any cargo appear from nearby industries or towns.  Trains will not stop at waypoint stations, regardless of the non-stop order and/or the nonstop switch.

=== Sprite layout (09) ===
This controls what sprites are displayed, where they are displayed, and in what order.  The property is variable sized, and contains the data for all 8 possible station tile types.  If this property is set, the num-ent in the corresponding [[Action1|action 1]] need not be equal to 12 (hex), it can in fact be any number, and any number of sprites can be displayed in any order.

The data is specified as data for all eight tiles in this way:

<pre><num> <data1> <data2> ... <datan></pre>

{| |-
!Size!!Name!!Meaning
|-
|B*||num||Number of different tiles supported (see below)
|-
|V||data1...||The variable size data for each of the <num> tiles, as specified below
|}

===== Number of tiles supported =====
* Normally this is 8, but you can specify fewer as well
* Using callback flags bit 1, specifying more makes sense too
* This value must be the same for all stations set by this action 0, even though it must be repeated for the prop. 09 definition of each station ID as well

(Note that num is an extended byte, see [[GRFActionsDetailed]].)

The content of each of the (usually eight) data sets is either a new sprite layout:

{| |-
!Size!!Name!!Meaning
|-
|D||groundsprite||the sprite to draw for the rails; this is by default a TTD sprite, but with bit 31 set an [[Action1|action 1]] sprite (42D+X) may be specified
|-
|V||spritedata||the data for station sprites, see below; each has a size of 10 bytes, and there may be several
|-
|B||80||a literal 80 ends the list of sprites for this tile
|}
or, alternatively, the instruction to use TTD's layout by using four zero bytes 00 00 00 00 instead of the groundsprite bytes. You can use [http://www.bytetransfer.de/projects/ttdpatch/docs/spriteidmapping.php the online sprite ID converter] to look up the sprite IDs you can use for all the climates.

One can draw two types of sprites.  One type is one that establishes a new 3D bounding box for use by the sprite sorter.  The other type shares the 3D bounding box of the previous sprite(s).  It must not be larger than the sprite which established the bounding box, nor must any part of it be outside this box.  For simplicity, it should have the exact same dimensions as the sprite it shares the bounding box with.  The latter type is supported in the station construction window display only since TTDPatch 2.6 r1684.

The spritedata of sprites with their own bounding box has this format:

{| |-
!Size!!Name!!Meaning
|-
|B||xofs||x-offset from northern tile corner
|-
|B||yofs||y-offset from northern tile corner
|-
|B||zofs||z-offset from northern tile corner
|-
|B||xextent||size of sprite in x direction
|-
|B||yextent||size of sprite in y direction
|-
|B||zextent||size of sprite in z direction
|-
|D||sprite||sprite number to draw
|}

The spritedata of sprites sharing the bounding box has this format:

{| |-
!Size!!Name!!Meaning
|-
|B||xofs||x-offset relative to previous sprite
|-
|B||yofs||y-offset relative to previous sprite
|-
|B||80||a literal 80
|-
|B||00||(ignored)
|-
|B||00||(ignored)
|-
|B||00||(ignored)
|-
|D||sprite||sprite number to draw
|}

Since OpenTTD r18959 you can draw multiple ground sprites for a tile, which is useful if you want to use the usual rail/grass/concrete groundtile, but still need to add features to it without using a new bounding box. To do so use the syntax of sprites sharing the previous bounding box, but use it before the first bounding box definition. xpixeloffset and ypixeloffset refer to the usual spot of groundtiles. The same feature is also partially supported in TTDPatch since TTDPatch 2.6 r2312: TTDPatch ignores the xofs and yofs fields and always uses (0,0) for the offset. If you are developing a GRF that needs to be compatible with both OpenTTD and TTDPatch, you should always keep xofs and yofs zero to get the same effect in both games.
Note however that both implementations do not consider the [[Action0/Stations#General_Flags_.2813.29|setting of prop13 bit 0]], hence these "multiple ground sprites" have to be always part of the building sprites set and cannot be part of the different sprite set for ground sprites.

The sprite number can have the following values (remember to use little endian, i.e. reversed byte order):

{| |-
!Number!!Sprite
|-
|0000042D+X||use sprite X from the corresponding [[Action1|action 1]] block (i.e. 0000042D for the first, 0000042E for the second, etc.)
|-
|0000842D+X||same, but draw it using company colour translation
|-
|0322442D+X||same, but draw in transparent mode (actual colours of the sprite are disregarded entirely); supported in station construction window display since TTDPatch 2.6 r1683
|-
|RRRR842D+X||draw sprite with colour translation defined in sprite RRRR; available since TTDPatch 2.6 r1683
|}

With bit 31 set, this sprite will refer to a TTD sprite, not the action 1 sprite. For the first ground sprite the reverse meaning applies.

Depending on the railtype the sprites may get additional offsets:

{| |-
! !! Normal/electrified rail !! Monorail !! Maglev
|-
|TTD sprites || 0 || 82 || 164
|-
|Action 1 sprite (first ground sprite) || 0 || 1 || 2
|-
|Action 1 sprite (other sprites in the layout) || 0 || 0 || 0
|}

So, TTD sprites and the first ground sprite are affected by the railtype, while other action 1 sprites in the layout are not. The offset "82" refers to the offset between the default TTD track sprites; if you are using non-track ground sprites which are not from an action 1, you need to supply fake spritenumbers which preemptively reverse the offsets (that is, you need different sprite layouts for every railtype your station is available for).

Setting bit 30 forces this sprite to be displayed normally even in "transparent buildings" mode (supported only in TTDPatch 2.6 r1695 and later).

See below for an example of linked sprites as well as transparent sprites (e.g. for a station roof).

Note that the coordinates here are 3D coordinates with x running from top-right to bottom-left and y running from top-left to bottom-right, with the tile dimensions being 16x16 (and 8 for one height level). This means the x and y values should always be within 0-15 (decimal).

This is different to and independent from the x/y offsets used in the actual .NFO file.  The 3D bounding box is used by TTD's sprite sorter to figure out the order in which to draw the sprites, as well as telling it which sprites to draw, because those whose bounding box falls outside the currently updated screen rectangle will not be drawn.  Make sure the 3D bounding box is large enough to contain the entire sprite, but not so large that the sprite sorter can't determine which sprites should be in front.

This means that the order in which you specify sprites is irrelevant.  Sprites will get drawn from back to front, in the order which the sprite sorter determines as correct, from their bounding boxes.  There are two exceptions, however:
* Sprites sharing the same bounding box will always be drawn in the given order.
* The station construction window display doesn't use the sprite sorter. Tiles that may be displayed in that window need to be specified in the correct drawing order, back to front.

=== Copy sprite layout (0A) ===

This is not a property as such, but an action.  It takes as argument a byte which is interpreted as station-ID to copy the custom sprite layout from.

Since {{ottdp|14.0}} this property is now an extended byte.

=== Callback flags (0B) ===
For stations, the following [[callbacks]] can be defined by setting the corresponding bit in property 0B:

{| |-
!Bit!!Value!!Variable 0C value!!Callback
|-
|0||1||13||Whether to make station available in construction window (non-zero callback return) or not (callback returns zero)
|-
|1||2||14||Use callback to select sprite layout
|-
|2||4||141||Decide next animation frame
|-
|3||8||142||Decide animation speed
|-
|4||10||149||Custom slope check
|}
Bit is the bit you have to set, you do this by adding all the values for all the bits. Variable 0C value is what variable 0C will be set to, for checking it in the [[VariationalAction2|VarAction2]] for callbacks.

=== Selection of numbers of platforms and length (0C, 0D) ===

By default all platform lengths and any number of platforms is available for the new stations.  Using these properties, you can choose which ones should be unavailable by setting the corresponding bit in the property.

The values are a byte, used as a bit mask.  Bits 0 to 6 control the availability of number or length 1 to 7, and bit 7 controls the availability of the "+7" button.  Each bit that is set disables the corresponding length or number of platforms.

For compatibility with "largestations off", at least one length between 1 and 5 (bits 0 to 4) and one number of platforms between 1 and 4 (bits 0 to 3) must be available, i.e. at least one of these bits must be unset.

=== Define custom layout (0E) ===

This allows choosing which tile type is built at which tile of a newly built station.  There are four different types, which TTD normally defines as

{| |-
!Tile type!!Appearance
|-
|00||plain platform
|-
|02||platform with building
|-
|04||platform with roof, left side
|-
|06||platform with roof, right side
|}

Since {{ottdp|15}}, all even values up to FE are supported if the sprite layout is defined via property 09/0A.

These numbers are used for stations in NE-SW direction, or these numbers plus one for stations in the NW-SE direction.  To define a custom layout, use this format:

{| |-
!Size!!Name!!Meaning
|-
|B||length||length of platforms for this layout
|-
|B||number||number of platforms for this layout
|-
|V||tiles||length*number bytes of tile types, one platform after another, only 00, 02, 04 or 06 are allowed as values
|}

Repeat this as often as necessary to define the layouts for all supported combinations of length and number.  End the definitions with a 00 00 (zero length and zero number).  Any combinations that are not defined will be built using TTD's default layout.
Note that it may be easier to draw different sprite sets using a [[VariationalAction2|VarAction2]] based on [[VarAction2Stations#Platform info 40 41 46 47 49|station variable 40]], rather than redefining the layout.  In addition, [[Callbacks#Custom station layout 24|callback 24]] will be used to further customize the layout as defined by this property (or by TTD if no prop 0E layout is available). This may also be easier than defining a prop 0E layout for every combination of length and number of platforms.

=== Copy custom layout (0F) ===

Similar to property 0A, this copies the custom layout from the station-ID given by the argument.

Since {{ottdp|14.0}} this property is now an extended byte.

=== Little/lots threshold (10) ===
Amount of cargo for switching from "little" to "lots" of cargo.  TTDPatch separates the full range of cargo amounts (0 to 4095) into two separate subranges, "little" and "lots" of cargo.  This allows better control of cargo amount based graphics (if needed).  Property 10 specifies at what amount of cargo the patch is to switch from one to the other subrange.  See [[Action2Stations|Action 2 for stations]] for more information.

=== Pylon placement (11) and wire placement (14) ===
Prop. 11 sets which tile types should have pylons when used with electrified tracks. By default, tiles 0-3 (default stations without roof) have pylons, and tiles 4-7 (default stations with roof) don't. This is a bit mask of tile types, with a bit set meaning that a pylon should be drawn. The tile types here do not consider [[Callbacks#Station sprite layout 14|callback 14]], but rather the type as it was built, i.e. from prop. 0E.

Prop. 14 works in a similar way, except that it sets the tile types on which there should be ''no'' wires displayed. With the default value of "00", wires are displayed everywhere, and for each bit set, the wire is omitted on that tile type.

This property should only be used when the wires cause problems with the sprite sorter, because even when the wire is obscured by a station hall or similar, it should still show up in transparent mode so that each tile can easily be verified as being electrified.

{{ottdp|15}} Note: This property only allows setting the flags of the first 8 sprite layouts. Use Property 1E instead to set flags when more sprite layouts are used via prop. 0E or [[Callbacks#Custom_station_layout_.2824.29|callback 24]].

=== Cargo types for random triggers (12) ===

This sets which cargo types should trigger re-randomizing. The cargo types are given as a bitmask of the bits from column 3 (type B) in CargoTypes.  If nothing is set (the default), the no random triggers will happen, to conserve CPU time.

With GRF version 7 and above, the interpretation of bits changes. Instead of climate-dependent cargo slot numbers (type B), you have to set the bits of climate-independent cargo ID (type A).

{{ottd|15.0}} Since 15.0, a default cargo translation table corresponding to the climate is used if one is not provided.

=== General Flags (13) ===

{| |-
!Bit!!Value!!Version!!Meaning
|-
|0||1||{{ottdp|0.7|2.5}}||use different sprite set for ground sprites ([[GlobalVariables#Extra_callback_info_.2810_.2F_-.29_and_.2818_.2F_-.29|var. 10]] is 1 for ground sprites, 0 otherwise)
|-
|1||2||{{ottdp|0.6|2.5}}||When calculating the cargo amount to display, divide the amount by half of the station perimeter (to simulate cargo distributed over the station)
'''Depricated''' since {{ottd|16.0}}, use bit 5 instead.
|-
|2||4||{{ottdp|0.7|2.5}}||[[Callbacks#Next animation frame (1A/26/141/153/158)|callback 141]] needs random bits in var. 10
|-
|3||8||{{ottdp|1.0|2.6}}||Use custom foundations on sloped tiles (the lowest byte of [[GlobalVariables#Extra_callback_info_.2810_.2F_-.29_and_.2818_.2F_-.29|var. 10]] is 2 for foundation sprites)
|-
|4||10||{{ottdp|1.0|2.6}}||When bit 3 is set, use extended foundation block instead of the simple one
|-
|5||20||{{ottdp|16.0|-}}||When calculating the cargo amount to display, divide the amount by the station area (to simulate cargo distributed over the area of the station)
|}

Bit 3 works somewhat similarly to bit 0: your sprite selection will be called again, with 2 in the lowest byte of [[GlobalVariables#Extra_callback_info_.2810_.2F_-.29_and_.2818_.2F_-.29|variable 10]]. If the chain ends on a callback result, the program will assume the foundation selection has failed and will use the default foundaton sprites. The low word of [[GlobalVariables#Extra_callback_info_.2810_.2F_-.29_and_.2818_.2F_-.29|variable 18]] will contain the tile type of the current tile; if you have [[Callbacks#Station sprite layout (14)|callback 14]] enabled, this will be the its return value - otherwise, the default TTD types (platform with building, platform with left roof etc.) are used. In either case, one is added for the NW-SE orientation, in case your station needs different foundations depending on its orientation. Bits 16 and 17 are set if the NW and and NE foundations are to merged with the corresponding neighbour tile, so you shouldn't draw the corresponding edge in the foundation sprite. Other bits of variable 10 and variable 18 are reserved for future use.

Your sprite selection code should select a foundation sprite block. The contents of this block depends on whether bit 4 is set or not.
* Bit 4 clear (simple foundations):
[[File:simple_foundations.png]]

The programme will combine the needed foundation from these 8 sprites depending on the current slope. You don't need to care about the merge data in bits 16..17 of [[GlobalVariables#Extra_callback_info_.2810_.2F_-.29_and_.2818_.2F_-.29|variable 18]]; it will be taken care of that automatically by adding the 7th and 8th sprite only when necessary.
* Bit 4 set (extended foundations):
[[File:extended_foundations.png]]

You need to have one sprite for every slope that's possible below a rail station. The correct one will be automatically selected depending on the current slope. It can't handle the merging itself, however, so you need four foundation blocks: one with no edges removed, one with the NW edge removed, one with the NE edge removed and one with both north edges removed. Your sprite selection code is responsible for selecting the correct of those blocks according to the merge info in [[GlobalVariables#Extra_callback_info_.2810_.2F_-.29_and_.2818_.2F_-.29|variable 18]].

In both cases, you can put an additional value into register 100h, which will serve as an offset into the selected block. If you don't modify register 100h during the chain, it will default to 0. It is important that the dimensions of these sprites remain the same - thus bit 6 in the real sprites must be set to prevent GRFCodec from trimming the empty blue areas. The offset of these foundations must be -31 to the X direction and -9 to the Y direction.

=== Can train enter tile (15) ===

Like props. 11 and 14, this value contains eight bits relating to the eight possible tile types. If a bit is set, trains are prevented from routing through or entering any tile of this type.

{{ottdp|15}} Note: This property only allows setting the flags of the first 8 sprite layouts. Use Property 1E instead to set flags when more sprite layouts are used via prop. 0E or [[Callbacks#Custom_station_layout_.2824.29|callback 24]].

=== Animation information (16) ===

The low byte specifies the number of animation frames minus one, so 00 means 1 frame, 01 means 2 frames etc. The maximum number of frames is 256, although you can have some problems if your animation exceeds FD (253) frames. The high byte must be 0 for non-looping animations and 01 for looping animations. Every other value is reserved for future use. In addition, if the whole word contains FFFF, animation is turned off for this station (this is the default value).
Since you can't have properties for individual station tiles, this property applies for every tile of the station. If you don't want to animate some tiles, you should check the current position during [[Callbacks#Animation control (1B/25/140/152/159)|callback 140]] and return FD if the current tile doesn't need to be animated. If you also need animations of different length per tile, you'll have to use [[Callbacks#Next animation frame (1A/26/141/153/158)|callback 141]] for that.

=== Animation speed (17) ===
The meaning is the same as for [[Action0Houses#Animation Speed 1B|house property 1B]], but the lower limit is 0 instead of 2, so the fastest possible animation changes frames every game tick (27ms). The default value is 2.

=== Animation triggers (18) ===
This is a bit mask of events that should trigger [[Callbacks#Animation control (1B/25/140/152/159)|callback 140]], allowing to change the animation state

{| |-
!Property bit, var18 byte 0!!Property value!!Version!!Meaning!!Happens on!!Var 18 byte 1
|-
|0||1||{{ottdp|0.7|2.5}}||Station part is built||the newly built tiles||
|-
|1||2||{{ottdp|0.7|2.5}}||New cargo arrives to station||whole station||Cargo type <ref name="cargotype">Bits 8..15 of var 18 contain the triggering cargo type. If your GRF has a cargo translation table, the cargo type will be an index in that table, or FFh if the cargo isn't in the table. If you don't have a cargo translation table, the cargo type will simply be the climate-dependent cargo type number.</ref>
|-
|2||4||{{ottdp|0.7|2.5}}||A cargo type gets removed from station||whole station||Cargo type <ref name="cargotype"/>
|-
|3||8||{{ottdp|0.7|2.5}}||Train enters station (starts loading/unloading)||platform where the train is||
|-
|4||10||{{ottdp|0.7|2.5}}||Train leaves station (done loading/unloading)||platform where the train is||
|-
|5||20||{{ottdp|1.2|2.5|ottdrev=r22746}}||Train loads/unloads cargo||platform where the train is||
|-
|6||40||{{ottdp|0.7|2.5}}||Every 250 ticks||whole station||
|-
|7||80||{{ottdp|15|no}}||Tile is processed in the periodic processing loop||single tile||
|-
|8||100||{{ottdp|15|no}}||Train reserves platform (using PBS)||platform where the train reserved||
|}

The remaining bits are reserved for future triggers, they must be zero for now.

The "happens on" column tells which tiles will [[Callbacks#Animation control (1B/25/140/152/159) |callback 140]] be called on.

<references/>

=== Advanced sprite layout with register modifiers (1A) ===

{{ottdp|1.2|no|ottdrev=r22518}}
Format:
1A <num-layouts> <0x40 + num-sprites>
<groundsprite> <flags> [<register/value>]...
[ <buildingsprite> <flags>
( <xoffset> <yoffset> <zoffset> <xextent> <yextent> <zextent>
| <xpixeloffset> <ypixeloffset> 80)
[<register/value>]...
]...

For further details see [https://wiki.openttd.org/en/Archive/Development/Advanced%20Sprite%20Layout#stations here] for now.

=== Minimum bridge height (1B) ===

This property allows building bridges over stations.

The bridge height property defines minimum clearances required for a bridge for each of the four [[Action0/Stations#Define_custom_layout_.280E.29|tile types]] of this station (or zero to not allow any bridge). Values are given in "height level" units (1 level == 8px).

{| class="wikitable" |-
!Height (1)!!Appearance
|-
| style="text-align:center;" |x1 y1 ||plain platform
|-
| style="text-align:center;" |x2 y2 ||platform with building
|-
| style="text-align:center;" |x3 y3 ||platform with roof, left side
|-
| style="text-align:center;" |x4 y4 ||platform with roof, right side
|}
(1) where the values are one byte pairs (x-direction, y-direction) expressed in hexadecimal notation.

Syntax:

1B <1st pair> <2nd pair> <3rd pair> <4th pair> 
1B x1 y1 x2 y2 x3 y3 x4 y4 
1B 01 01 02 02 03 03 03 03 // 8px 16px 24px 24px

This property is currently only available for JGR's Patch Pack (v0.26.0 and later) and the developmental "New Map Features" (NMF) fork of OpenTTD.

=== Station name (1C) ===

=== Station class name (1D) ===

=== Station sprite layout flags (1E) ===

{{ottdp|15}} Since OpenTTD supports more than 8 sprite layouts to be used, props. 11, 14 and 15 are not sufficient to set the flags for all usable sprite layouts. This property is variable length and allows these flags to be set for each tile beyond the original limit of 8.

The data is specified as flags for all sprite layouts in this way:

<pre><num> <flags1> <flags2> ... <flagsn></pre>

{| |-
!Size!!Name!!Meaning
|-
|B*||num||Number of different tiles supported (see below)
|-
|B||flags1...||The flags for each of the <num> tiles, as specified below
|}

The flag values are as follows:

{| |-
|Bit||Value||Meaning
|-
|0||01||Tile should contain catenary pylons.
|-
|1||02||Tile should NOT contain catenary wires.
|-
|2||04||Tile is blocked to vehicles.
|}

These should be combined as needed.

===Minimum Bridge Height (20)===

{{ottdp|15}} This property allows building bridges over stations.

The bridge height property defines minimum clearances required for a bridge for the sprite layouts of this station (or zero to not allow any bridge). Values are given in "height level" units (1 level == 8px).

The data is specified as minimum height for all sprite layouts in this way:

<pre><num> <height1> <height2> ... <heightn></pre>

{| |-
!Size!!Name!!Meaning
|-
|B*||num||Number of different tiles supported (see below)
|-
|B||height...||The minimum heights for each of the <num> tiles.
|}

===Blocked Pillar Information (21)===

{{ottdp|15}} Allows information to provided about blocked bridge pillars to assist the game in hiding pillars if necessary depending on what is above the station tile. Blocking a pillar prevents the pillar from being drawn. It does not prevent the station being bridgeable.

The data is specified as blocked pillar flags for all sprite layouts in this way:

<pre><num> <flags1> <flags2> ... <flagsn></pre>

{| |-
!Size!!Name!!Meaning
|-
|B*||num||Number of different tiles supported (see below)
|-
|B||flags...||The blocked pillar flags for each of the <num> tiles.
|}

The flag bits are as follows:

{| |-
|Bit||Value||Meaning
|-
|0||01||Tile layout blocks a pillar on the west corner of the tile.
|-
|1||02||Tile layout blocks a pillar on the south corner of the tile.
|-
|2||04||Tile layout blocks a pillar on the east corner of the tile.
|-
|3||08||Tile layout blocks a pillar on the north corner of the tile.
|-
|4||10||Tile layout blocks a wall on the north east side of the tile.
|-
|5||20||Tile layout blocks a wall on the south east side of the tile.
|-
|6||40||Tile layout blocks a wall on the south west side of the tile.
|-
|7||80||Tile layout blocks a wall on the north west side of the tile.
|}

These should be combined as needed.

== Examples ==

=== Using TTD's sprite layouts for certain tiles ===

To use TTD's layout, you use <code>00 00 00 00</code> for the ground sprite number and leave off everything else.

So instead of for example

F4 03 00 00
00 00 00 10 05 02 2E 84 00 00
00 0B 00 10 05 02 30 84 00 00
80

you just put

00 00 00 00

=== Using transparent sprites ===

You can use transparent sprites to make for example the roof translucent like in TTD's stations. The roof of TTD's stations is made like this:

00 00 10 10 10 0A 37 84 00 00
00 00 80 00 00 00 3B 44 22 03

The first sprite here is the non-transparent frame of the roof, drawn in company colours (it has bit 15 set). The second part is a special "linked" sprite without its own bounding box, it shares that of the previous sprite. That's done by setting the z offset to 80.

To make that second sprite transparent, bit 14 is set in the sprite number, and the upper word is set to 322 (*), so 0322443B means to take sprite 43B and draw it in transparent mode. The colours of that sprite are ignored entirely, every pixel in colour 0 is fully transparent, and all other pixels are semi-transparent (essentially just causing what they are drawn over to become darker).

(*) This is the [[RecolorSprites#Default_recolour_sprites | recolour sprite]] for the glass effect.

NML:Badges

2026-02-12T13:58:59Z

Rito12: /* Badge callbacks */ By the way, by design badges are meant to only be up to 12 pixels tall. That's why these look bad in lists. (Probably didn't mention it in the specs.)

{{NMLNavPropVarCB}}

'''Since''' {{ottd|15.0}}

item (FEAT_BADGES, item_name) { ... }

==Badge properties==

{| class="wikitable sortable"
! property
! value range
! comment
|-
| label
| string with <code style="color:green">/</code> as delimiter
| ''' For sake of compatibility and user experience, consider using [[NML:Badge labels|labels already introduced]] by other NewGRFs.'''
Badges with label without <code style="color:green">/</code> are considered to be classes.
Labels for other badges should match following syntax:
<code style="color:green">"label_of_class_they_belong_to/label_for_the_badge"</code>
|-
| name
| string
| Name of this badge or badge class.
|-
| flags
| bitmask(BADGE_FLAG_XXX, ...);
|
; COPY_TO_RELATED_ENTITY
: Badge can be copied to related entity (e.g. badge on a railtype can be copied to rail vehicles of that railtype.)
; NAME_LIST_STOP
: Stops adding more names to the visible name list.
; NAME_LIST_FIRST_ONLY
: Add this name to the visible name list only if this is the first name.
; USE_COMPANY_COLOUR
: Recolour badge depending on company that player currently controls.
; NAME_SKIP
: Allow the badge to be excluded from the badge name list.
|}

== Badge variables ==

{| class="wikitable sortable"
! name
! value range
! comment
|-
| intro_date
| date(yyyy, mm, dd)
| Introduction date of entity (or current date if entity type does not have an introduction date). See <code style="color: green">introduction_date</code> in [[NML:Vehicles#Properties common to all vehicle types|vehicle properties]].
|}

== Badge callbacks ==

'''Note: By design badges are meant to only be up to 12 pixels tall.'''

{| class="wikitable sortable"
! callback
! return value
! comment
|-
| default
| spriteset
| Graphics for the badge or badge class.
|-
|
aircraft 
airports 
airporttiles 
houses 
industries 
industrytiles 
objects 
railtypes 
roadstops 
roadtypes 
roadvehs 
ships 
stations 
trains 
tramtypes 
| spriteset
| Override default graphics when used by other specific feature.
|}

== Prerequisites ==

Badges require a [[NML:Badgetable|badgetable]] to be defined for most common usage scenarios (eg to refer to a badge from an item block). This is not a hard requirement and can be omitted if you are, for example, creating badges that other newGRFs can later refer to

Eg for <code style="color:green">power/diesel</code> to be used in the badges property for a vehicle, the badge table must contain entries for both <code style="color:green">power</code> and <code style="color:green">power/diesel</code>

== Example code ==

<pre style="color:blue">

badgetable {
"power",
"power/diesel",
"power/steam"
}

item (FEAT_BADGES, power) {
property {
label: "power";
name: string(STR_POWER);
}
}

# This badge will not show a sprite in the purchase menu
item (FEAT_BADGES, diesel) {
property {
label: "power/diesel";
name: string(STR_POWER_DIESEL);
}
}

# This badge will show a sprite in the purchase menu
item (FEAT_BADGES, steam) {
property {
label: "power/steam";
name: string(STR_POWER_STEAM);
}
graphics {
default: sprite_steam;
}
}
</pre>

Action0/Badges

2026-02-12T13:37:20Z

Rito12: /* Badge label (08) */ Use <code>

''''''Action 0 properties for badges''''''

= Action 0 - Properties for badges =

Defining properties of badges.

== Properties ==

{| class="wikitable"
|-
!'''Number'''
!'''[[GRFActionsDetailed|Size]]'''
!'''Version'''
!'''Description'''
|-
|08
|S
|{{ottdp|15}}
|Badge label. A zero-terminated string.
|-
|09
|D
|{{ottdp|15}}
|Flags.
|}

<references />

== Badge label (08) ==

These are globally unique strings.

Badge labels comprise a badge class, for grouping similar badges, and badge name, separated by a <code>/</code>.

Classes and names are arbitrary, but to be useful must follow a standard scheme. For instance, the badge label power/steam will define a badge for steam powered vehicles within the power class.

Proposed initial classes are:

* flag
* role
* manufacturer
* operator
* power
* livery

It is also possible to assign a badge to everything within a NewGRF by defining the badge label <code>newgrf/<GRFID></code>, with the GRFID in full hexadecimal form. This will work even if the badge is defined outside of the NewGRF it is for.

=== Naming Proposal ===

To work consistently, a naming standard needs to be agreed on, e.g.:

/role/passenger
/role/freight

/livery/<country>/<operator>/<name>
/livery/uk/british_rail/blue
/livery/uk/british_rail/swallow
/livery/fr/sncf/tgv

The game could then present these as a filterable list, e.g.:

Role
Passenger
Freight

Livery
UK
British Rail - Blue
British Rail - Swallow
France
SNCF - TGV

== Flags (09) ==

{| class="wikitable"
|-
!'''Bit'''
!'''Value'''
!'''Meaning'''
|-
|0
|1
|Copy. Badge can be copied to related entity (e.g. badge on a railtype can be copied to rail vehicles of that railtype.)
|-
|1
|2
|NameListStop. Stops adding more names to the visible name list.
|-
|2
|4
|NameListFirstOnly. Add this name to the visible name list only if this is the first name.
|-
|3
|8
|UseCompanyColour. Apply appropriate company colour palette to the icon. If the icon is applied to a vehicle with 2CC support, then the 2CC palette will be used.
|-
|4
|16
|NameListSkip. Allow the badge to be excluded from the badge name list.
|}

Action0/Badges

2026-02-12T13:36:10Z

Rito12: /* Badge label (08) */ Use <code> instead of '

''''''Action 0 properties for badges''''''

= Action 0 - Properties for badges =

Defining properties of badges.

== Properties ==

{| class="wikitable"
|-
!'''Number'''
!'''[[GRFActionsDetailed|Size]]'''
!'''Version'''
!'''Description'''
|-
|08
|S
|{{ottdp|15}}
|Badge label. A zero-terminated string.
|-
|09
|D
|{{ottdp|15}}
|Flags.
|}

<references />

== Badge label (08) ==

These are globally unique strings.

Badge labels comprise a badge class, for grouping similar badges, and badge name, separated by a <code>/</code>.

Classes and names are arbitrary, but to be useful must follow a standard scheme. For instance, the badge label power/steam will define a badge for steam powered vehicles within the power class.

Proposed initial classes are:

* flag
* role
* manufacturer
* operator
* power
* livery

It is also possible to assign a badge to everything within a NewGRF by defining the badge label `newgrf/<GRFID>`, with the GRFID in full hexadecimal form. This will work even if the badge is defined outside of the NewGRF it is for.

=== Naming Proposal ===

To work consistently, a naming standard needs to be agreed on, e.g.:

/role/passenger
/role/freight

/livery/<country>/<operator>/<name>
/livery/uk/british_rail/blue
/livery/uk/british_rail/swallow
/livery/fr/sncf/tgv

The game could then present these as a filterable list, e.g.:

Role
Passenger
Freight

Livery
UK
British Rail - Blue
British Rail - Swallow
France
SNCF - TGV

== Flags (09) ==

{| class="wikitable"
|-
!'''Bit'''
!'''Value'''
!'''Meaning'''
|-
|0
|1
|Copy. Badge can be copied to related entity (e.g. badge on a railtype can be copied to rail vehicles of that railtype.)
|-
|1
|2
|NameListStop. Stops adding more names to the visible name list.
|-
|2
|4
|NameListFirstOnly. Add this name to the visible name list only if this is the first name.
|-
|3
|8
|UseCompanyColour. Apply appropriate company colour palette to the icon. If the icon is applied to a vehicle with 2CC support, then the 2CC palette will be used.
|-
|4
|16
|NameListSkip. Allow the badge to be excluded from the badge name list.
|}

NML:Badges

2026-01-14T15:26:32Z

Rito12: /* Prerequisites */ Use <code style="color:green">

{{NMLNavPropVarCB}}

'''Since''' {{ottd|15.0}}

item (FEAT_BADGES, item_name) { ... }

==Badge properties==

{| class="wikitable sortable"
! property
! value range
! comment
|-
| label
| string with <code style="color:green">/</code> as delimiter
| ''' For sake of compatibility and user experience, consider using [[NML:Badge labels|labels already introduced]] by other NewGRFs.'''
Badges with label without <code style="color:green">/</code> are considered to be classes.
Labels for other badges should match following syntax:
<code style="color:green">"label_of_class_they_belong_to/label_for_the_badge"</code>
|-
| name
| string
| Name of this badge or badge class.
|-
| flags
| bitmask(BADGE_FLAG_XXX, ...);
|
; COPY_TO_RELATED_ENTITY
: Badge can be copied to related entity (e.g. badge on a railtype can be copied to rail vehicles of that railtype.)
; NAME_LIST_STOP
: Stops adding more names to the visible name list.
; NAME_LIST_FIRST_ONLY
: Add this name to the visible name list only if this is the first name.
; USE_COMPANY_COLOUR
: Recolour badge depending on company that player currently controls.
; NAME_SKIP
: Allow the badge to be excluded from the badge name list.
|}

== Badge variables ==

{| class="wikitable sortable"
! name
! value range
! comment
|-
| intro_date
| date(yyyy, mm, dd)
| Introduction date of entity (or current date if entity type does not have an introduction date). See <code style="color: green">introduction_date</code> in [[NML:Vehicles#Properties common to all vehicle types|vehicle properties]].
|}

== Badge callbacks ==

{| class="wikitable sortable"
! callback
! return value
! comment
|-
| default
| spriteset
| Graphics for the badge or badge class.
|-
|
aircraft 
airports 
airporttiles 
houses 
industries 
industrytiles 
objects 
railtypes 
roadstops 
roadtypes 
roadvehs 
ships 
stations 
trains 
tramtypes 
| spriteset
| Override default graphics when used by other specific feature.
|}

== Prerequisites ==

Badges require a [[NML:Badgetable|badgetable]] to be defined for most common usage scenarios (eg to refer to a badge from an item block). This is not a hard requirement and can be omitted if you are, for example, creating badges that other newGRFs can later refer to

Eg for <code style="color:green">power/diesel</code> to be used in the badges property for a vehicle, the badge table must contain entries for both <code style="color:green">power</code> and <code style="color:green">power/diesel</code>

== Example code ==

<pre style="color:blue">

badgetable {
"power",
"power/diesel",
"power/steam"
}

item (FEAT_BADGES, power) {
property {
label: "power";
name: string(STR_POWER);
}
}

# This badge will not show a sprite in the purchase menu
item (FEAT_BADGES, diesel) {
property {
label: "power/diesel";
name: string(STR_POWER_DIESEL);
}
}

# This badge will show a sprite in the purchase menu
item (FEAT_BADGES, steam) {
property {
label: "power/steam";
name: string(STR_POWER_STEAM);
}
graphics {
default: sprite_steam;
}
}
</pre>

NML:Badge labels

2026-01-05T22:03:40Z

Rito12: Rito12 moved page NML:Badge labels to Badge labels: "but page should be in general grf spec, not nml"

#REDIRECT [[Badge labels]]

Badge labels

2026-01-05T22:03:40Z

Rito12: Rito12 moved page NML:Badge labels to Badge labels: "but page should be in general grf spec, not nml"

{{NMLNavBlocksyntax}}

== Introduction ==
This page is dedicated for tracking registered badge labels.
If you write or publish a NewGRF which introduces a new badge label, please also add comment about it here.
However, before you introduces a new label reconsider if any of available labels fulfills the same purpose. Do not introduces two or more labels for same purpose.
If you introduce a new class, please also provide a table for badges that belong to it.
For ease of maintenance keep alphabetical order.

== Classes ==

{| class="wikitable sortable"
! Label !! Introduced by !! Comment
|-
| flag || OpenTTD default badges || Country/Region
|-
| livery || OpenTTD default badges || Livery
|-
| power || OpenTTD default badges || Propulsion
|-
| region || OpenTTD default badges || Region
|-
| role || OpenTTD default badges || Role
|-
| zone || OpenTTD default badges || Zone
|}

== Badges ==

=== Flag ===
{| class="wikitable sortable"
! Label !! Introduced by !! Comment
|-
| flag/AD || OpenTTD default badges || Andorra
|}

=== Livery ===
{| class="wikitable sortable"
! Label !! Introduced by !! Comment
|-
| livery/2cc || OpenTTD default badges || Dual company colour (2CC)
|-
| livery/random/1cc || OpenTTD default badges || Random based on first company colour
|-
| livery/random/2cc || OpenTTD default badges || Random based on second company colour
|}

=== Power ===
{| class="wikitable sortable"
! Label !! Introduced by !! Comment
|-
| power/battery || OpenTTD default badges || Battery
|-
| power/diesel || OpenTTD default badges || Diesel
|-
| power/electric || OpenTTD default badges || Electric
|-
| power/electric/ac || OpenTTD default badges || Electric (AC)
|-
| power/electric/dc || OpenTTD default badges || Electric (DC)
|-
| power/steam || OpenTTD default badges || Steam
|-
| power/turbine || OpenTTD default badges || Gas Turbine
|}

=== Region ===
{| class="wikitable sortable"
! Label !! Introduced by !! Comment
|-
| region/africa || OpenTTD default badges || Africa
|-
| region/africa/eastern || OpenTTD default badges || Eastern Africa
|-
| region/africa/middle || OpenTTD default badges || Middle Africa
|-
| region/africa/northern || OpenTTD default badges || Northern Africa
|-
| region/africa/southern || OpenTTD default badges || Southern Africa
|-
| region/africa/western || OpenTTD default badges || Western Africa
|-
| region/america || OpenTTD default badges || Americas
|-
| region/america/caribbean || OpenTTD default badges || Caribbean
|-
| region/america/central || OpenTTD default badges || Central America
|-
| region/america/northern || OpenTTD default badges || Northern America
|-
| region/america/south || OpenTTD default badges || South America
|-
| region/asia || OpenTTD default badges || Asia
|-
| region/asia/central || OpenTTD default badges || Central Asia
|-
| region/asia/eastern || OpenTTD default badges || Eastern Asia
|-
| region/asia/southeastern || OpenTTD default badges || South-eastern Asia
|-
| region/asia/southern || OpenTTD default badges || Southern Asia
|-
| region/asia/western || OpenTTD default badges || Western Asia
|-
| region/europe || OpenTTD default badges || Europe
|-
| region/europe/eastern || OpenTTD default badges || Eastern Europe
|-
| region/europe/northern || OpenTTD default badges || Northern Europe
|-
| region/europe/southern || OpenTTD default badges || Southern Europe
|-
| region/europe/western || OpenTTD default badges || Western Europe
|-
| region/oceania || OpenTTD default badges || Oceania
|-
| region/oceania/australia_and_new_zealand || OpenTTD default badges || Australia and New Zealand
|-
| region/oceania/melanesia || OpenTTD default badges || Melanesia
|-
| region/oceania/micronesia || OpenTTD default badges || Micronesia
|-
| region/oceania/polynesia || OpenTTD default badges || Polynesia
|}

=== Role ===
{| class="wikitable sortable"
! Label !! Introduced by !! Comment
|-
| role/banking || OpenTTD default badges || Banking
|-
| role/express_freight || OpenTTD default badges || Express freight
|-
| role/express_passenger || OpenTTD default badges || Express passenger
|-
| role/freight || OpenTTD default badges || Freight
|-
| role/heavy_freight || OpenTTD default badges || Heavy freight
|-
| role/light_freight || OpenTTD default badges || Light freight
|-
| role/mail || OpenTTD default badges || Mail
|-
| role/mixed || OpenTTD default badges || Mixed
|-
| role/passenger || OpenTTD default badges || Passenger
|-
| role/prototype || OpenTTD default badges || Prototype
|-
| role/restaurant_car || OpenTTD default badges || Restaurant car
|-
| role/shunting || OpenTTD default badges || Shunting
|-
| role/snowplough || OpenTTD default badges || Snowplough
|-
| role/utility || OpenTTD default badges || Utility
|}

=== Zone ===
{| class="wikitable sortable"
! Label !! Introduced by !! Comment
|-
| zone/agricultural || OpenTTD default badges || Agricultural
|-
| zone/com || OpenTTD default badges || Commercial
|-
| zone/com/high || OpenTTD default badges || High density commercial
|-
| zone/com/low || OpenTTD default badges || Low density commercial
|-
| zone/com/medium || OpenTTD default badges || Medium density commercial
|-
| zone/forestry || OpenTTD default badges || Forestry
|-
| zone/general || OpenTTD default badges || General
|-
| zone/ind || OpenTTD default badges || Industrial
|-
| zone/ind/high || OpenTTD default badges || High density industrial
|-
| zone/ind/low || OpenTTD default badges || Low density industrial
|-
| zone/ind/medium || OpenTTD default badges || Medium density industrial
|-
| zone/leisure || OpenTTD default badges || Leisure
|-
| zone/mixed || OpenTTD default badges || Commercial & residential
|-
| zone/mixed/high || OpenTTD default badges || High density commercial & residential
|-
| zone/mixed/low || OpenTTD default badges || Low density commercial & residential
|-
| zone/mixed/medium || OpenTTD default badges || Medium density commercial & residential
|-
| zone/other || OpenTTD default badges || Other
|-
| zone/public || OpenTTD default badges || Public
|-
| zone/res || OpenTTD default badges || Residential
|-
| zone/res/high || OpenTTD default badges || High density residential
|-
| zone/res/low || OpenTTD default badges || Low density residential
|-
| zone/res/medium || OpenTTD default badges || Medium density residential
|-
| zone/transport || OpenTTD default badges || Transport
|}

Template:NMLNavMain

2026-01-04T19:43:48Z

Rito12: Undo revision 5208 by Rito12 (talk)

<noinclude>This is the main NML navigation template, it is designed to be included in subnavigation templates. These subnavigation templates in turn are included on each documentation page.</noinclude>
<div style="width:200px; border:1px solid #2f6fab; background:#b1cff8; padding:5px; -moz-border-radius-topleft:5px; -moz-border-radius-topright:5px; font-size: 12pt;">
<center>[[NML:Main|NewGRF Meta Language]]</center>
</div>
<div style="width:200px; border:1px solid #2f6fab; border-top-width: 0px; background:#eaf6f8; padding:5px; font-size: 8pt; line-height: 12pt;">

;[[NML:Preface |Preface]]
;[[NML:Getting started|Getting started]]
;[[NML:Graphic files|Graphics files]]

;[[NML:Block syntax|Blocks]]
;[[NML:Units|Units]]
;[[NML:Expressions|Expressions]]
:[[NML:Elementary values|Elementary values]]
:[[NML:Builtin functions|Builtin functions]]
;[[NML:Language files|Language files]]
;[[NML:Properties and variables and callbacks|Lists of props, vars and CBs]]
;[[NML:Warnings|Warnings]]
;[[NML:Additional references|Additional references]]
;[[NML:NewGRF compatibility|NewGRF compatibility]]
;[[NML:Deprecated syntax|Deprecated syntax]]
;[[NML:changes 0.3|Changes from NML 0.2 to 0.3]]
;[[NML:changes 0.4|Changes from NML 0.3 to 0.4]]
;[[NML:changes 0.5|Changes from NML 0.4 to 0.5]]
</div>
<div style="width:200px; border:1px solid #2f6fab; border-top-width: 0px; background:#eaf6f8; padding:5px; font-size: 8pt; line-height: 12pt;">
[[NML:Vehicles|Vehicles]],
[[NML:Stations|Stations]],
[[NML:Roadstops|Roadstops]],
[[NML:Canals|Canals]],
[[NML:Towns|Towns]],
[[NML:Houses|Houses]],
[[NML:Industries|Industries]] ([[NML:IndustryTiles|Tiles]]),
[[NML:Cargos|Cargos]],
[[NML:Airports|Airports+Tiles]],
[[NML:Objects|Objects]],
[[NML:Railtypes|Railtypes]],
[[NML:Roadtypes|Roadtypes]],
[[NML:Tramtypes|Tramtypes]],
[[NML:Bridges|Bridges]],
[[NML:Badges|Badges]],
[[NML:Base_Graphics|Terrain]]
</div>
<div style="width:200px; border:1px solid #2f6fab; border-top-width: 0px; background:#eaf6f8; padding:5px; font-size: 8pt; line-height: 12pt;">

;[[ttwiki:NMLTutorial|NML Tutorial]]

</div>

Badge labels

2026-01-04T18:28:48Z

Rito12: /* Power */ remove unwanted labels

{{NMLNavBlocksyntax}}

== Introduction ==
This page is dedicated for tracking registered badge labels.
If you write or publish a NewGRF which introduces a new badge label, please also add comment about it here.
However, before you introduces a new label reconsider if any of available labels fulfills the same purpose. Do not introduces two or more labels for same purpose.
If you introduce a new class, please also provide a table for badges that belong to it.
For ease of maintenance keep alphabetical order.

== Classes ==

{| class="wikitable sortable"
! Label !! Introduced by !! Comment
|-
| flag || OpenTTD default badges || Country/Region
|-
| livery || OpenTTD default badges || Livery
|-
| power || OpenTTD default badges || Propulsion
|-
| region || OpenTTD default badges || Region
|-
| role || OpenTTD default badges || Role
|-
| zone || OpenTTD default badges || Zone
|}

== Badges ==

=== Flag ===
{| class="wikitable sortable"
! Label !! Introduced by !! Comment
|-
| flag/AD || OpenTTD default badges || Andorra
|}

=== Livery ===
{| class="wikitable sortable"
! Label !! Introduced by !! Comment
|-
| livery/2cc || OpenTTD default badges || Dual company colour (2CC)
|-
| livery/random/1cc || OpenTTD default badges || Random based on first company colour
|-
| livery/random/2cc || OpenTTD default badges || Random based on second company colour
|}

=== Power ===
{| class="wikitable sortable"
! Label !! Introduced by !! Comment
|-
| power/battery || OpenTTD default badges || Battery
|-
| power/diesel || OpenTTD default badges || Diesel
|-
| power/electric || OpenTTD default badges || Electric
|-
| power/electric/ac || OpenTTD default badges || Electric (AC)
|-
| power/electric/dc || OpenTTD default badges || Electric (DC)
|-
| power/steam || OpenTTD default badges || Steam
|-
| power/turbine || OpenTTD default badges || Gas Turbine
|}

=== Region ===
{| class="wikitable sortable"
! Label !! Introduced by !! Comment
|-
| region/africa || OpenTTD default badges || Africa
|-
| region/africa/eastern || OpenTTD default badges || Eastern Africa
|-
| region/africa/middle || OpenTTD default badges || Middle Africa
|-
| region/africa/northern || OpenTTD default badges || Northern Africa
|-
| region/africa/southern || OpenTTD default badges || Southern Africa
|-
| region/africa/western || OpenTTD default badges || Western Africa
|-
| region/america || OpenTTD default badges || Americas
|-
| region/america/caribbean || OpenTTD default badges || Caribbean
|-
| region/america/central || OpenTTD default badges || Central America
|-
| region/america/northern || OpenTTD default badges || Northern America
|-
| region/america/south || OpenTTD default badges || South America
|-
| region/asia || OpenTTD default badges || Asia
|-
| region/asia/central || OpenTTD default badges || Central Asia
|-
| region/asia/eastern || OpenTTD default badges || Eastern Asia
|-
| region/asia/southeastern || OpenTTD default badges || South-eastern Asia
|-
| region/asia/southern || OpenTTD default badges || Southern Asia
|-
| region/asia/western || OpenTTD default badges || Western Asia
|-
| region/europe || OpenTTD default badges || Europe
|-
| region/europe/eastern || OpenTTD default badges || Eastern Europe
|-
| region/europe/northern || OpenTTD default badges || Northern Europe
|-
| region/europe/southern || OpenTTD default badges || Southern Europe
|-
| region/europe/western || OpenTTD default badges || Western Europe
|-
| region/oceania || OpenTTD default badges || Oceania
|-
| region/oceania/australia_and_new_zealand || OpenTTD default badges || Australia and New Zealand
|-
| region/oceania/melanesia || OpenTTD default badges || Melanesia
|-
| region/oceania/micronesia || OpenTTD default badges || Micronesia
|-
| region/oceania/polynesia || OpenTTD default badges || Polynesia
|}

=== Role ===
{| class="wikitable sortable"
! Label !! Introduced by !! Comment
|-
| role/banking || OpenTTD default badges || Banking
|-
| role/express_freight || OpenTTD default badges || Express freight
|-
| role/express_passenger || OpenTTD default badges || Express passenger
|-
| role/freight || OpenTTD default badges || Freight
|-
| role/heavy_freight || OpenTTD default badges || Heavy freight
|-
| role/light_freight || OpenTTD default badges || Light freight
|-
| role/mail || OpenTTD default badges || Mail
|-
| role/mixed || OpenTTD default badges || Mixed
|-
| role/passenger || OpenTTD default badges || Passenger
|-
| role/prototype || OpenTTD default badges || Prototype
|-
| role/restaurant_car || OpenTTD default badges || Restaurant car
|-
| role/shunting || OpenTTD default badges || Shunting
|-
| role/snowplough || OpenTTD default badges || Snowplough
|-
| role/utility || OpenTTD default badges || Utility
|}

=== Zone ===
{| class="wikitable sortable"
! Label !! Introduced by !! Comment
|-
| zone/agricultural || OpenTTD default badges || Agricultural
|-
| zone/com || OpenTTD default badges || Commercial
|-
| zone/com/high || OpenTTD default badges || High density commercial
|-
| zone/com/low || OpenTTD default badges || Low density commercial
|-
| zone/com/medium || OpenTTD default badges || Medium density commercial
|-
| zone/forestry || OpenTTD default badges || Forestry
|-
| zone/general || OpenTTD default badges || General
|-
| zone/ind || OpenTTD default badges || Industrial
|-
| zone/ind/high || OpenTTD default badges || High density industrial
|-
| zone/ind/low || OpenTTD default badges || Low density industrial
|-
| zone/ind/medium || OpenTTD default badges || Medium density industrial
|-
| zone/leisure || OpenTTD default badges || Leisure
|-
| zone/mixed || OpenTTD default badges || Commercial & residential
|-
| zone/mixed/high || OpenTTD default badges || High density commercial & residential
|-
| zone/mixed/low || OpenTTD default badges || Low density commercial & residential
|-
| zone/mixed/medium || OpenTTD default badges || Medium density commercial & residential
|-
| zone/other || OpenTTD default badges || Other
|-
| zone/public || OpenTTD default badges || Public
|-
| zone/res || OpenTTD default badges || Residential
|-
| zone/res/high || OpenTTD default badges || High density residential
|-
| zone/res/low || OpenTTD default badges || Low density residential
|-
| zone/res/medium || OpenTTD default badges || Medium density residential
|-
| zone/transport || OpenTTD default badges || Transport
|}

Badge labels

2026-01-04T16:50:24Z

Rito12: Add OpenTTD default badges without flags (a lot of work and can be done later on).

{{NMLNavBlocksyntax}}

== Introduction ==
This page is dedicated for tracking registered badge labels.
If you write or publish a NewGRF which introduces a new badge label, please also add comment about it here.
However, before you introduces a new label reconsider if any of available labels fulfills the same purpose. Do not introduces two or more labels for same purpose.
If you introduce a new class, please also provide a table for badges that belong to it.
For ease of maintenance keep alphabetical order.

== Classes ==

{| class="wikitable sortable"
! Label !! Introduced by !! Comment
|-
| flag || OpenTTD default badges || Country/Region
|-
| livery || OpenTTD default badges || Livery
|-
| power || OpenTTD default badges || Propulsion
|-
| region || OpenTTD default badges || Region
|-
| role || OpenTTD default badges || Role
|-
| zone || OpenTTD default badges || Zone
|}

== Badges ==

=== Flag ===
{| class="wikitable sortable"
! Label !! Introduced by !! Comment
|-
| flag/AD || OpenTTD default badges || Andorra
|}

=== Livery ===
{| class="wikitable sortable"
! Label !! Introduced by !! Comment
|-
| livery/2cc || OpenTTD default badges || Dual company colour (2CC)
|-
| livery/random/1cc || OpenTTD default badges || Random based on first company colour
|-
| livery/random/2cc || OpenTTD default badges || Random based on second company colour
|}

=== Power ===
{| class="wikitable sortable"
! Label !! Introduced by !! Comment
|-
| power/battery || OpenTTD default badges || Battery
|-
| power/diesel || OpenTTD default badges || Diesel
|-
| power/diesel/diesel-electric || OpenTTD default badges || Diesel (Diesel-electric)
|-
| power/diesel/diesel-hydraulic || OpenTTD default badges || Diesel (Diesel-hydraulic)
|-
| power/electric || OpenTTD default badges || Electric
|-
| power/electric/ac || OpenTTD default badges || Electric (AC)
|-
| power/electric/ac/15kv || OpenTTD default badges || Electric (AC 15kV)
|-
| power/electric/ac/25kv || OpenTTD default badges || Electric (AC 25kV)
|-
| power/electric/dc || OpenTTD default badges || Electric (DC)
|-
| power/electric/dc/1200v || OpenTTD default badges || Electric (DC 1200V)
|-
| power/electric/dc/1500v || OpenTTD default badges || Electric (DC 1500V)
|-
| power/electric/dc/3kv || OpenTTD default badges || Electric (DC 3kV)
|-
| power/electric/dc/600v || OpenTTD default badges || Electric (DC 600V)
|-
| power/electric/dc/750v || OpenTTD default badges || Electric (DC 750V)
|-
| power/steam || OpenTTD default badges || Steam
|-
| power/turbine || OpenTTD default badges || Gas Turbine
|}

=== Region ===
{| class="wikitable sortable"
! Label !! Introduced by !! Comment
|-
| region/africa || OpenTTD default badges || Africa
|-
| region/africa/eastern || OpenTTD default badges || Eastern Africa
|-
| region/africa/middle || OpenTTD default badges || Middle Africa
|-
| region/africa/northern || OpenTTD default badges || Northern Africa
|-
| region/africa/southern || OpenTTD default badges || Southern Africa
|-
| region/africa/western || OpenTTD default badges || Western Africa
|-
| region/america || OpenTTD default badges || Americas
|-
| region/america/caribbean || OpenTTD default badges || Caribbean
|-
| region/america/central || OpenTTD default badges || Central America
|-
| region/america/northern || OpenTTD default badges || Northern America
|-
| region/america/south || OpenTTD default badges || South America
|-
| region/asia || OpenTTD default badges || Asia
|-
| region/asia/central || OpenTTD default badges || Central Asia
|-
| region/asia/eastern || OpenTTD default badges || Eastern Asia
|-
| region/asia/southeastern || OpenTTD default badges || South-eastern Asia
|-
| region/asia/southern || OpenTTD default badges || Southern Asia
|-
| region/asia/western || OpenTTD default badges || Western Asia
|-
| region/europe || OpenTTD default badges || Europe
|-
| region/europe/eastern || OpenTTD default badges || Eastern Europe
|-
| region/europe/northern || OpenTTD default badges || Northern Europe
|-
| region/europe/southern || OpenTTD default badges || Southern Europe
|-
| region/europe/western || OpenTTD default badges || Western Europe
|-
| region/oceania || OpenTTD default badges || Oceania
|-
| region/oceania/australia_and_new_zealand || OpenTTD default badges || Australia and New Zealand
|-
| region/oceania/melanesia || OpenTTD default badges || Melanesia
|-
| region/oceania/micronesia || OpenTTD default badges || Micronesia
|-
| region/oceania/polynesia || OpenTTD default badges || Polynesia
|}

=== Role ===
{| class="wikitable sortable"
! Label !! Introduced by !! Comment
|-
| role/banking || OpenTTD default badges || Banking
|-
| role/express_freight || OpenTTD default badges || Express freight
|-
| role/express_passenger || OpenTTD default badges || Express passenger
|-
| role/freight || OpenTTD default badges || Freight
|-
| role/heavy_freight || OpenTTD default badges || Heavy freight
|-
| role/light_freight || OpenTTD default badges || Light freight
|-
| role/mail || OpenTTD default badges || Mail
|-
| role/mixed || OpenTTD default badges || Mixed
|-
| role/passenger || OpenTTD default badges || Passenger
|-
| role/prototype || OpenTTD default badges || Prototype
|-
| role/restaurant_car || OpenTTD default badges || Restaurant car
|-
| role/shunting || OpenTTD default badges || Shunting
|-
| role/snowplough || OpenTTD default badges || Snowplough
|-
| role/utility || OpenTTD default badges || Utility
|}

=== Zone ===
{| class="wikitable sortable"
! Label !! Introduced by !! Comment
|-
| zone/agricultural || OpenTTD default badges || Agricultural
|-
| zone/com || OpenTTD default badges || Commercial
|-
| zone/com/high || OpenTTD default badges || High density commercial
|-
| zone/com/low || OpenTTD default badges || Low density commercial
|-
| zone/com/medium || OpenTTD default badges || Medium density commercial
|-
| zone/forestry || OpenTTD default badges || Forestry
|-
| zone/general || OpenTTD default badges || General
|-
| zone/ind || OpenTTD default badges || Industrial
|-
| zone/ind/high || OpenTTD default badges || High density industrial
|-
| zone/ind/low || OpenTTD default badges || Low density industrial
|-
| zone/ind/medium || OpenTTD default badges || Medium density industrial
|-
| zone/leisure || OpenTTD default badges || Leisure
|-
| zone/mixed || OpenTTD default badges || Commercial & residential
|-
| zone/mixed/high || OpenTTD default badges || High density commercial & residential
|-
| zone/mixed/low || OpenTTD default badges || Low density commercial & residential
|-
| zone/mixed/medium || OpenTTD default badges || Medium density commercial & residential
|-
| zone/other || OpenTTD default badges || Other
|-
| zone/public || OpenTTD default badges || Public
|-
| zone/res || OpenTTD default badges || Residential
|-
| zone/res/high || OpenTTD default badges || High density residential
|-
| zone/res/low || OpenTTD default badges || Low density residential
|-
| zone/res/medium || OpenTTD default badges || Medium density residential
|-
| zone/transport || OpenTTD default badges || Transport
|}

Template:NMLNavMain

2026-01-04T15:55:18Z

Rito12: For sake of compatibility and user experience.

NML:Badges

2026-01-04T15:52:15Z

Rito12: /* Badge properties */ For sake of compatibility and user experience.

{{NMLNavPropVarCB}}

'''Since''' {{ottd|15.0}}

item (FEAT_BADGES, item_name) { ... }

==Badge properties==

{| class="wikitable sortable"
! property
! value range
! comment
|-
| label
| string with <code style="color:green">/</code> as delimiter
| ''' For sake of compatibility and user experience, consider using [[NML:Badge labels|labels already introduced]] by other NewGRFs.'''
Badges with label without <code style="color:green">/</code> are considered to be classes.
Labels for other badges should match following syntax:
<code style="color:green">"label_of_class_they_belong_to/label_for_the_badge"</code>
|-
| name
| string
| Name of this badge or badge class.
|-
| flags
| bitmask(BADGE_FLAG_XXX, ...);
|
; COPY_TO_RELATED_ENTITY
: Badge can be copied to related entity (e.g. badge on a railtype can be copied to rail vehicles of that railtype.)
; NAME_LIST_STOP
: Stops adding more names to the visible name list.
; NAME_LIST_FIRST_ONLY
: Add this name to the visible name list only if this is the first name.
; USE_COMPANY_COLOUR
: Recolour badge depending on company that player currently controls.
; NAME_SKIP
: Allow the badge to be excluded from the badge name list.
|}

== Badge variables ==

{| class="wikitable sortable"
! name
! value range
! comment
|-
| intro_date
| date(yyyy, mm, dd)
| Introduction date of entity (or current date if entity type does not have an introduction date). See <code style="color: green">introduction_date</code> in [[NML:Vehicles#Properties common to all vehicle types|vehicle properties]].
|}

== Badge callbacks ==

{| class="wikitable sortable"
! callback
! return value
! comment
|-
| default
| spriteset
| Graphics for the badge or badge class.
|-
|
aircraft 
airports 
airporttiles 
houses 
industries 
industrytiles 
objects 
railtypes 
roadstops 
roadtypes 
roadvehs 
ships 
stations 
trains 
tramtypes 
| spriteset
| Override default graphics when used by other specific feature.
|}

== Example code ==

<pre style="color:blue">
item (FEAT_BADGES, power) {
property {
label: "power";
name: string(STR_POWER);
}
}

item (FEAT_BADGES, diesel) {
property {
label: "power/diesel";
name: string(STR_POWER_DIESEL);
}
}

item (FEAT_BADGES, steam) {
property {
label: "power/steam";
name: string(STR_POWER_STEAM);
}
graphics {
default: sprite_steam;
}
}
</pre>

NML:Badgetable

2026-01-04T15:49:33Z

Rito12: For sake of compatibility and user experience

{{NMLNavBlocksyntax}}

Since {{ottdp|15|no|ottdrev=8f14894}}

Badgetable is a set of string entries separated by comma. It allows to use <code style="color:darkgreen">badges</code> property of common items.

badgetable {
"ENTRY" [, "ENTRY"]*
}

Each <code style="color:darkgreen">ENTRY</code> consist of labels separated with slash. Last label is considered to identify the badge, others refer to classes that the badge belongs to.

''' For sake of compatibility and user experience, consider using [[NML:Badge labels|labels already introduced]] by other NewGRFs.'''

'''Note:''' Currently badge hierarchy in OpenTTD allows only for one level of nesting. <code style="color:darkgreen">colours/blue/skyblue</code> will end up as <code style="color:darkgreen">blue/skyblue</code> in <code style="color:darkgreen">colours</code> class instead of <code style="color:darkgreen">skyblue</code> in <code style="color:darkgreen">blue</code> class witch would be a subclass of <code style="color:darkgreen">colours</code>.

<pre style="color:blue">
badgetable {
"flag",
"flag/GB",
"flag/US",
"power",
"power/steam",
"power/diesel",
"power/electric",
}
</pre>

A badge listed in a badgetable will automatically be created if it is not otherwise provided. However, it will not appear in the UI then (It still can be viewed in the NewGRF debug window).

Badge labels

2026-01-04T15:33:54Z

Rito12: NML:Badge labels

{{NMLNavBlocksyntax}}
Nothing yet

NML:Vehicles

2026-01-04T15:28:48Z

Rito12: /* Variables that require an argument */ No var 0x64 in purchase list.

{{NMLNavPropVarCB}}
==Properties common to all vehicle types==

{| class="wikitable sortable"
! 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. If set to 0, cargo does not age. Repeated tests have shown that the gameplay effects of this property often do not match the expectations of grf authors. Explaining why requires a detailed understanding of the OpenTTD cargo aging algorithm, and how that works with e.g. different map sizes, vehicle speeds, multi-leg feeder systems, etc. TL;DR avoid using this property unless you absolutely understand the effect it will have.
|-
| <code style="color:green">variant_group</code>
| Vehicle ID or alternatively the vehicle numeric ID (0 ... 65535)
| no
|
{{ottd|13}} This property supports grouping vehicles in the purchase menu (also the autoreplace menu). The property value is the ID of another vehicle in the same GRF which will act as the parent for vehicles in the group.

Groups can also be nested (this is experimental as of December 2022 and may change with testing).

See also vehicle extra_flags which can influence the behaviour of vehicles in variant groups.

See also https://github.com/OpenTTD/OpenTTD/pull/10220
|-
| <code style="color:green">extra_flags</code>
| bitmask(VEHICLE_FLAG_XXX, ...)
| no
| {{ottd|13}}
;VEHICLE_FLAG_DISABLE_NEW_VEHICLE_MESSAGE
: Disable "New Vehicle" news message for this engine
;VEHICLE_FLAG_DISABLE_EXCLUSIVE_PREVIEW
: Disable "Exclusive Preview" for this engine
;VEHICLE_FLAG_SYNC_VARIANT_EXCLUSIVE_PREVIEW
: Variants - Include this variant when primary engine has "Exclusive Preview"
;VEHICLE_FLAG_SYNC_VARIANT_RELIABILITY
: Variants - (Attempt to) Synchronize reliability the primary engine.
|-
| <code style="color:green">badges</code>
| Array of badge labels from the [[NML:Badgetable|badgetable]].
| yes
| Since {{ottd|15.0}}
|}

===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. The length of each phase and the starting, peak, and final reliabilities are randomized for each engine when starting a new game. Also note that phase 2 (the vehicle's peak performance) is actually about 8 years shorter than the <code style="color:darkgreen">model_life</code> parameter.

{| 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 + (0 to 15 months)
| stays constant at peak, 75-100%
|-
| 3
| 10 to 20.6 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.

==Train properties==

{| class="wikitable sortable"
! 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). See also curve_speed_mod property.
;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. {{ottdp|13|no|no}} this flag is no longer required, flip is always allowed, except for multi-header or articulated vehicles which cannot be flipped. For vehicles shorter than 8/8, see [[Action0/Vehicles/Trains#cite_note-6|this note about sprite offsets]]
;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
;TRAIN_FLAG_SPRITE_STACK
:{{ottdp|1.7|no|ottdrev=r27668}} Enable [[NML:Vehicles#Composing_vehicles_from_multiple_sprites|composition from multiple sprites]].
|-
| <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>
|{{ottd|15.0.0}} array of items from railtypetable {{ottd|<15.0.0}} 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. It also sets the corresponding sound effect of the engine, and if visual_effect_and_powered is not set, the visual effect as well.
;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) * 9.8 * weight (in tons), with 9.8 being an approximation of the acceleration of gravity (9.81 m/s).
|-
| <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
|
There are two methods to set the visual effect of a vehicle:
* <code style="color:green">visual_effect_and_powered</code>: Easy method for simple effects.
* <code style="color:green">effect_spawn_model_and_powered</code> + callback <code style="color:green">create_effect</code>: {{ottdp|1.5|no|ottdrev=r26747}} Harder to use, but also more powerful.
For each vehicle you have to decide for the method. You cannot use them both for the same vehicle 'item'.

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">effect_spawn_model_and_powered</code>
| <code style="color:green">EFFECT_SPAWN_MODEL_XXX</code> or <code style="color:green">EFFECT_SPAWN_MODEL_XXX <nowiki>|</nowiki> ENABLE_WAGON_POWER</code>
| yes
|
There are two methods to set the visual effect of a vehicle:
* <code style="color:green">visual_effect_and_powered</code>: Easy method for simple effects.
* <code style="color:green">effect_spawn_model_and_powered</code> + callback <code style="color:green">create_effect</code>: {{ottdp|1.5|no|ottdrev=r26747}} Harder to use, but also more powerful.
For each vehicle you have to decide for the method. You cannot use them both for the same vehicle 'item'.

{{ottdp|1.5|no|ottdrev=r26747}} Set the spawning model of visual effects for the vehicle, that is when the vehicle emits visual effects.
The visual appearance itself is defined by the callback 'create_effect'.

;EFFECT_SPAWN_MODEL_NONE
: Do not spawn any effects.
;EFFECT_SPAWN_MODEL_STEAM
: Gradually less effects when approaching max speed.
;EFFECT_SPAWN_MODEL_DIESEL
: Effect proportional to acceleration, no effect when idling at top speed.
;EFFECT_SPAWN_MODEL_ELECTRIC
: Random effect, gradually less likely when approaching max speed.
|-
| <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>]]
|-
| <code style="color:green">curve_speed_mod</code>
| -128 ... 127.996 (float)
| yes
| {{nml|0.7}} {{ottd|12.0}} Maximum curve speed modifier.

The modifier is applied after the normal curve speed calculation is done using the formula max_curve_speed * (1 + curve_speed_mod). This means that the default property value of 0 is equivalent to no change. Negative values are supported, but the resulting vehicle curve speed is clamped at 2 mph-ish to make sure vehicles don't become permanently stuck.

If different vehicles in a train have different curve speed modifiers, the lowest value wins.

See also TRAIN_FLAG_TILT, which is an older and less flexible way of managing vehicle curve speed.
|}

==Road vehicle properties==

{| class="wikitable sortable"
! property
! value range
! available for articulated vehicle
! comment
|-
| sprite_id
| SPRITE_ID_NEW_ROADVEH
| yes
| Set this property to enable new graphics
|-
| speed
| 0 ... 511km/h (float, speed units)
| no
|
|-
| road_type ''or'' tram_type
| item from [[NML:Railtypetable-Roadtypetable-Tramtypetable|roadtypetable]] or [[NML:Railtypetable-Roadtypetable-Tramtypetable|tramtypetable]]
| must be the same as front
| Only ''one'' of these properties may be set.
If <code style="color:green">tram_type</code> is set, <code style="color:green">ROADVEH_FLAG_TRAM</code> must also be set for the vehicle in <code style="color:green">misc_flags</code>.

If not set, road vehicles will default to ROAD and tram vehicles will default to RAIL (this does not overlap with railtype RAIL).
|-
| 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
;ROADVEH_FLAG_SPRITE_STACK
:{{ottdp|1.7|no|ottdrev=r27668}} Enable [[NML:Vehicles#Composing_vehicles_from_multiple_sprites|composition from multiple sprites]].
|-
| 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]].
 {{ottdp|1.6|no|ottdrev=r27507}} Since OpenTTD r27507 also <code style="color:green">sound("sound.wav")</code> and <code style="color:green">import_sound(grfid, number)</code> are valid here.
|-
| visual_effect
| visual_effect( VISUAL_EFFECT_XXX, offset)
| yes
|
There are two methods to set the visual effect of a vehicle:
* <code style="color:green">visual_effect</code>: Easy method for simple effects.
* <code style="color:green">effect_spawn_model</code> + callback <code style="color:green">create_effect</code>: {{ottdp|1.5|no|ottdrev=r26747}} Harder to use, but also more powerful.
For each vehicle you have to decide for the method. You cannot use them both for the same vehicle 'item'.

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">effect_spawn_model</code>
| <code style="color:green">EFFECT_SPAWN_MODEL_XXX</code>
| yes
|
There are two methods to set the visual effect of a vehicle:
* <code style="color:green">visual_effect</code>: Easy method for simple effects.
* <code style="color:green">effect_spawn_model</code> + callback <code style="color:green">create_effect</code>: {{ottdp|1.5|no|ottdrev=r26747}} Harder to use, but also more powerful.
For each vehicle you have to decide for the method. You cannot use them both for the same vehicle 'item'.

{{ottdp|1.5|no|ottdrev=r26747}} Set the spawning model of visual effects for the vehicle, that is when the vehicle emits visual effects.
The visual appearance itself is defined by the callback 'create_effect'.

;EFFECT_SPAWN_MODEL_NONE
: Do not spawn any effects.
;EFFECT_SPAWN_MODEL_STEAM
: Gradually less effects when approaching max speed.
;EFFECT_SPAWN_MODEL_DIESEL
: Effect proportional to acceleration, no effect when idling at top speed.
;EFFECT_SPAWN_MODEL_ELECTRIC
: Random effect, gradually less likely when approaching max speed.
|-
| 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="wikitable sortable"
! 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)
| {{ottd|14}}{{nml|7.5}} 0 .. 32767 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
;SHIP_FLAG_SPRITE_STACK
:{{ottdp|1.7|no|ottdrev=r27668}} Enable [[NML:Vehicles#Composing_vehicles_from_multiple_sprites|composition from multiple sprites]].
|-
| 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]].
 {{ottdp|1.6|no|ottdrev=r27507}} Since OpenTTD r27507 also <code style="color:green">sound("sound.wav")</code> and <code style="color:green">import_sound(grfid, number)</code> are valid here.
|-
| 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)
|
There are two methods to set the visual effect of a vehicle:
* <code style="color:green">visual_effect</code>: Easy method for simple effects.
* <code style="color:green">effect_spawn_model</code> + callback <code style="color:green">create_effect</code>: {{ottdp|1.5|no|ottdrev=r26747}} Harder to use, but also more powerful.
For each vehicle you have to decide for the method. You cannot use them both for the same vehicle 'item'.

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.
|-
| <code style="color:green">effect_spawn_model</code>
| <code style="color:green">EFFECT_SPAWN_MODEL_XXX</code>
|
There are two methods to set the visual effect of a vehicle:
* <code style="color:green">visual_effect</code>: Easy method for simple effects.
* <code style="color:green">effect_spawn_model</code> + callback <code style="color:green">create_effect</code>: {{ottdp|1.5|no|ottdrev=r26747}} Harder to use, but also more powerful.
For each vehicle you have to decide for the method. You cannot use them both for the same vehicle 'item'.

{{ottdp|1.5|no|ottdrev=r26747}} Set the spawning model of visual effects for the vehicle, that is when the vehicle emits visual effects.
The visual appearance itself is defined by the callback 'create_effect'.

;EFFECT_SPAWN_MODEL_NONE
: Do not spawn any effects.
;EFFECT_SPAWN_MODEL_STEAM
: Gradually less effects when approaching max speed.
;EFFECT_SPAWN_MODEL_DIESEL
: Effect proportional to acceleration, no effect when idling at top speed.
;EFFECT_SPAWN_MODEL_ELECTRIC
: Random effect, gradually less likely when approaching max speed.
|-
| acceleration
| 1 ... 255
| {{ottd|14}} Acceleration in units of ~0.5 km/h per tick. 1 is the default and is the acceleration of default ships.
|}

==Aircraft properties==

{| class="wikitable sortable"
! 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
;AIRCRAFT_FLAG_SPRITE_STACK
:{{ottdp|1.7|no|ottdrev=r27668}} Enable [[NML:Vehicles#Composing_vehicles_from_multiple_sprites|composition from multiple sprites]]. This also affects custom rotor sprites.
|-
| 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
| {{ottd|1.3.1}} 0 ... 255 {{ottd|<1.3.1}} 0 ... 19
| {{ottd|1.3.1}} Default aircraft use values in the range 18 to 50 (= 6.75 to 18.75 mph/tick = 499.5 to 1387.5 mph/day), which is generally considered quite fast. 
{{ottd|<1.3.1}} In older OpenTTD, aircraft provided by NewGRF accelerate 166% faster than intended.
|-
| 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]].
 {{ottdp|1.6|no|ottdrev=r27507}} Since OpenTTD r27507 also <code style="color:green">sound("sound.wav")</code> and <code style="color:green">import_sound(grfid, number)</code> are valid here.
|}

==Vehicle variables==

Below an overview of all vehicle-specific variables. Note 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, similarly checking current_roadtype for a tram won't return a useful result.

===Variables without parameter===

{| class="wikitable sortable"
! 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.
|-
| position_in_articulated_veh
| 0 ... 255
| No
| {{nml|0.3}} {{ottdp|1.4|no|ottdrev=r26157}} The position of the current articulated vehicle from the start of the vehicle. The first will get value 0, the second one gets value 1, etc.
|-
| position_in_articulated_veh_from_end
| 0 ... 255
| No
| {{nml|0.3}} {{ottdp|1.4|no|ottdrev=r26157}} The position of the current articulated vehicle from the end of the vehicle. The last will get value 0, the second last one gets value 1, etc.
|-
| cargo_classes_in_consist
| Bitmask of CC_XXX
| No
|
[[NML:Cargos#Cargo classes|cargo classes]]
|-
| most_common_cargo_type
|
[[NML:Cargos#Cargo properties|Cargo label]]
| No
| The most common cargo type in the consist. Prior to nml r2320 this was known as most_common_refit, and didn't work, and was also incorrectly documented :)
|-
| most_common_cargo_subtype
| 0 ... 255
| No
| The most common cargo subtype for most_common_cargo_type
|-
| 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
|-
| flight_state
| 0 ... 28
| No
| {{nml|0.8.1}} Only for aircrafts.
|-
| 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 ... 0xFFFFFF
| Yes, always 0
| Is increased every time the vehicle moves a single step on the map. Useful for driving animations.
For that, make the animation use a number of frames, which is a power of two, i.e. 2, 4, 8, 16, 32, ... frames, and then use the lower n bits of motion_counter.
|-
| 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_flipped
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the sprite is reversed via flip-vehicle-in-depot (trains only), or if it's the rear-most part of a dual-head engine.
|-
| 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
| Entry from railtype translation table or 0xFF
| No
| This variable is useless due to equivalent railtypes, use tile_xxx_railtype instead. If you do use this variable, it will not work as expected 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.
|-
| current_roadtype
| Entry from current_roadtype translation table or 0xFF
| No
| {{nml|0.5}} {{ottdp|1.10|no}} This variable is useless due to equivalent roadtypes, use tile_xxx_roadtype instead. Don't use this variable unless you've defined a roadtype translation table. If the road vehicle is running on a roadtype that is not listed in your roadtype translation table this variable will contain 0xFF. Checking this for a tram is not supported and will not return a useful result.
|-
| current_tramtype
| Entry from tramtype translation table or 0xFF
| No
| {{nml|0.5}} {{ottdp|1.10|no}} This variable is useless due to equivalent tramtypes, use tile_xxx_tramtype instead. Don't use this variable unless you've defined a tramtype translation table. If the road vehicle is running on a tramtype that is not listed in your tramtype translation table this variable will contain 0xFF. Checking this for a road vehicle that is not a tram is not supported and will not return a useful result.
|-
| tile_has_catenary
| [0 <nowiki>|</nowiki> 1]
| No
| {{ottdp|1.11|no}} True if the track_type on the tile has catenary. This is a little simplified as it is intended for sprite changes (e.g. raise/lower pantograph) and only checks for "some catenary". To distinguish different types of electric track, AC and DC voltages etc, ... use tile_xxx_railtype/tile_xxx_roadtype/tile_xxx_tramtype instead.
|-
| 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 or a name defined in item block
| 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
|-
| vehicle_is_unloading
| [0 <nowiki>|</nowiki> 1]
| No
| {{ottdp|1.5|2.5|ottdrev=r26430}} Value is 1 if the vehicle is unloading at a station and has not yet started loading new cargo.
|}

===Variables that require an argument===

{| class="wikitable sortable"
! 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">Argument 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_y_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_z_offset
| 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.
|-
| tile_supports_railtype tile_supports_roadtype tile_supports_tramtype
| Entry from rail/road/tram translation table
| [0 <nowiki>|</nowiki> 1]
| No
| {{ottdp|1.11|no}} Vehicles of the track_type label used as parameter are compatible with the rail/road/tram track_type on the current tile. Example: <code style="color:darkgreen">tile_supports_railtype(ELRL)</code>
|-
| tile_powers_railtype tile_powers_roadtype tile_powers_tramtype
| Entry from rail/road/tram translation table
| [0 <nowiki>|</nowiki> 1]
| No
| {{ottdp|1.11|no}} Vehicles of the track_type label used as parameter are powered on the rail/road/tram track_type on the current tile. Example: <code style="color:darkgreen">tile_powers_railtype(ELRL)</code>
|-
| tile_is_railtype tile_is_roadtype tile_is_tramtype
| Entry from rail/road/tram translation table
| [0 <nowiki>|</nowiki> 1]
| No
| {{ottdp|1.11|no}} The track_type label used as parameter is identical or equivalent (listed as alternate label in rail-/road-/tram-type property 1D) to the rail/road/tram track_type on the current tile. Example: <code style="color:darkgreen">tile_is_railtype(ELRL)</code>
|-
| has_badge
| Label from the [[NML:Badgetable|badgetable]].
| [0 <nowiki>|</nowiki> 1]
| yes
| {{ottd|15.0}} Check if the vehicle has that specific badge attached.
|-
| count_has_badge
| Label from the [[NML:Badgetable|badgetable]].
| 0..255
| no
| {{ottd|15.0}} The number of vehicles in the current consist that have that specific badge attached.
|}
<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="wikitable sortable"
! 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
| NOTE: As of OpenTTD 13, this feature is considered deprecated for most uses. Use variants instead. 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 to select specific sprites for the vehicle's current cargo subtype.
|-
| 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">getbits(extra_callback_info1, 0, 8)</code> 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">getbits(extra_callback_info1, 0, 8)</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.

The vehicle ID for the articulated part must be in the range 0 .. 16383.

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. If a wagon is inserted in the middle, all wagons are removed and attached one-by-one in the new order. This callback has to be defined at the engine. The scopes behave different than usual though:
* <code style="color:darkgreen">SELF</code> refers to the wagon being attached. (despite the callback being defined at the engine)
* <code style="color:darkgreen">PARENT</code> refers to the consist of the engine up to the wagon before <code style="color:darkgreen">SELF</code>, i.e. not (yet) including the wagon being attached.
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.
* <code style="color:darkgreen">getbits(extra_callback_info1, 0, 8)</code>: The new cargo type.
* <code style="color:darkgreen">getbits(extra_callback_info1, 8, 8)</code>: The new cargo subtype (see <code style="color:darkgreen">cargo_subtype_text</code>-callback).
* <code style="color:darkgreen">getbits(extra_callback_info1, 16, 16)</code>: 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.
|-
| create_effect
| {{ottdp|1.5|no|ottdrev=r26747}} Trains, Road Vehicles, Ships
| No
| 0 .. 3 for number of effects. Optionally add <code style="color:darkgreen">CB_RESULT_CREATE_EFFECT_CENTER</code> and/or <code style="color:darkgreen">CB_RESULT_CREATE_EFFECT_NO_ROTATION</code>
| Called when a effect spawning model is defined via <code style="color:darkgreen">effect_spawn_model</code> resp. <code style="color:darkgreen">effect_spawn_model_and_powered</code>.

The result specifies how many effects shall be created.
The position and appearance of the individual effects is returned via registers 0x100 to 0x103:
<pre style="color:blue">
switch (FEAT_XXX, SELF, switch_name, [
STORE_TEMP(create_effect(EFFECT_SPRITE_XXX, 8, -3, 10), 0x100), // first effect,
STORE_TEMP(create_effect(EFFECT_SPRITE_YYY, 8, 3, 10), 0x101) // second effect, ...
]) {
return 2; // number of effects
}
</pre>
The register values are created using the <code style="color:darkgreen">create_effect(''effect_sprite'', ''l_x_offset'', ''t_y_offset'', ''z_offset'')</code> function:
* ''effect_sprite'': Sprite for the effect. One of <code style="color:darkgreen">EFFECT_SPRITE_</code>[<code style="color:darkgreen">NONE</code>|<code style="color:darkgreen">STEAM</code>|<code style="color:darkgreen">DIESEL</code>|<code style="color:darkgreen">ELECTRIC</code>|<code style="color:darkgreen">AIRCRAFT_BREAKDOWN_SMOKE</code>].
* ''l_x_offset'': Longitudinal or X position of the effect, depending on callback result <code style="color:darkgreen">CB_RESULT_CREATE_EFFECT_NO_ROTATION</code>.
* ''t_y_offset'': Transversal or Y position of the effect, depending on callback result <code style="color:darkgreen">CB_RESULT_CREATE_EFFECT_NO_ROTATION</code>.
* ''z_offset'': Z position of the effect.

Additional to the number of effects, the callback result may specify these flags:
;<code style="color:darkgreen">CB_RESULT_CREATE_EFFECT_CENTER</code>
:(Train and road vehicle only) If set, position effect relative to vehicle center instead of relative to vehicle sprite. (behaves the same for vehicles with length 8/8)
;<code style="color:darkgreen">CB_RESULT_CREATE_EFFECT_NO_ROTATION</code>
*If not set, the parameters to <code style="color:darkgreen">effect_sprite</code> describe longitudinal/transversal positions, which are rotate wrt. vehicle orientation.
*If set, the parameters to <code style="color:darkgreen">effect_sprite</code> describe X and Y positions, which are not automatically rotated.
|-
| reverse_build_probability
| {{nml|0.7.5}} {{ottd|14.0}} Trains
| No
| 0
| Probability of reversing rail vehicle, i.e. facing forward or backward, when purchased.
|-
| refit
| {{ottd|15.0}} All vehicle types
| Callback runs once, in purchase scope only
|
* 0 Don't change refittability (i.e. use whatever the evaluation of the various refittability vehicle props has determined).
* 1 Allow cargo type as a refit.
* 2 Disallow cargo type as a refit.
|

The custom refit callback allows overriding the refittablity of each cargo as defined by the standard vehicle properties. It will be called for each defined cargo type once after the game has loaded all NewGRF files. The callback is run in purchase list scope, i.e. for cargotype FF. No variables of an actual vehicle are available. Information about the cargo type the callback is called for is available in variables 10 and 18:
'''Note:''' As this callback is not re-evaluated after game initialization, using any dynamic variables like e.g. game date will lead to undefined and faulty behaviour.

This callback is available starting with {{ottdp|15|no|ottdrev=gd2496b6ec4}} OpenTTD 15.

See https://newgrf-specs.tt-wiki.net/wiki/Callbacks#Custom_refit_.28163.29
|}

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

{| class="wikitable sortable"
! 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
|
|-
| effect_spawn_model_and_powered
| Trains
| No
|
|-
| effect_spawn_model
| 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
|
|-
| curve_speed_mod
| {{nml|0.7}} {{ottd|12.0}} Trains
| No
|
|-
| name
| {{nml|0.7.2}} {{ottd|14.0}} All
| Yes
| Can be used to display vehicle name differently depending on context (purchase menu, depot, nested variant depth etc). <code style="color:darkgreen">extra_callback_info1</code> contains detailed information about context - please see https://newgrf-specs.tt-wiki.net/wiki/Callbacks#Engine_name_.28161.29
|}

===Sprites in GUI===
{{ottdp|1.2|no|ottdrev=r23080}} Since OpenTTD r23080 you can use variable <code style="color:darkgreen">getbits(extra_callback_info1, 0, 8)</code> to display different sprites in the GUI and on the map. Currently these cases are available:
{| |-
! getbits(extra_callback_info1, 0, 8) !! 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 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.

===Composing vehicles from multiple sprites===
{{ottdp|1.7|no|ottdrev=r27668}} Since OpenTTD r27668 you can draw vehicles by drawing multiple sprites on top of each other.
* The sprites can use different recolouring.
* When using 32bpp sprites, the sprites can use the alpha channel to blend with the other sprites. In particular you can use this to alpha-blend company colours over other sprites.

To enable this, you need to set <code style="color:darkgreen">XXX_FLAG_SPRITE_STACK</code> in the <code style="color:darkgreen">misc_flags</code> property.

When enabled, sprites are resolved multiple times while incrementing an iteration number, that can be read via
<code style="color:darkgreen">getbits(extra_callback_info1, 8, 8)</code>

For OpenTTD 1.7 to 12.0, this is limited to at most 4 sprites per articulated part.

Increased to 8 sprites per articulated part for OpenTTD 13.0 {{ottdp|13.0|no}}

In addition you need to set register 100 as additional result:
* <code style="color:darkgreen">STORE_TEMP(CB_FLAG_MORE_SPRITES | recolouring, 0x100)</code> if there are more sprites to draw.
* <code style="color:darkgreen">STORE_TEMP(recolouring, 0x100)</code> if there are no more sprites to draw.
"recolouring" can be:
* <code>PALETTE_USE_DEFAULT</code> to use the default vehicle recolouring.
* <code>PALETTE_IDENTITY</code> to use no recolouring
* Any other default or custom recolouring sprite.

===Sound events===

{| class="wikitable sortable"
! 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
|}

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

Note that while vehicle ID affects the order in which vehicles appear in the purchase menu, this can be overridden using the [[NML:Sorting vehicles in the purchase list|sort block]].

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