GRFSpecs - User contributions [en-gb]

NML:IndustryTiles

2026-08-15T14:35:00Z

Andythenorth:

{{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.
{{ottdp|16}} OpenTTD 16 increased the tile range, choose any ID in the 0..511-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:IndustryTiles

2026-08-15T14:34:52Z

Andythenorth:

{{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.
{{ottdp|16}}OpenTTD 16 increased the tile range, choose any ID in the 0..511-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:IndustryTiles

2026-08-15T14:32:57Z

Andythenorth:

{{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. {{ottdp|16}}The tile range increased 0..511. 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)
|}

Action0/Industry Tiles

2026-08-15T14:30:47Z

Andythenorth: /* Introduction */

==Introduction==

Industry tiles work similarly to town buildings, except that they are not stand-alone; they are always part of an industry.

Defining industry tiles follows the same schema as houses do: to start using an ID, you first need to define it by setting property 8 for it. If you try to reference an ID (either via action0 or via action3) that isn't defined, your request is ignored, but not reported as an error, either. This means that if you want to conditionally define an ID, all you need to do is skipping the action0 that sets property8, and everything else gets skipped automatically.

Industry tile IDs are unique within each grf file. You should use your industry tile IDs sparingly. [[VariationalAction2/Industry_Tiles#Relative_position_.2843.29| Variational action 2 variable 43]] for industry tiles can help you limiting tile consumption to 2 or 3 per industry. Avoid using tile FFh, so the tileID can be turned into an extended byte (in Action 3) in the distant future without breaking your NewGRF.

{{ttdp|}} In total, TTDPatch can have up to a total of 256 new industry tile IDs (i.e. old tile types don't count).

{{ottd|}} OpenTTD can have 512 IDs for all active grf files, but that includes non-overridden original tiles.

== Properties ==

{| |-
!Property !![[GRFActionsDetailed|Size]] !!Version !! Description
|-
|08||B||{{ottdp|0.6|2.5|ttdprev=alpha 43}}||Substitute building type
|-
|09||B||{{ottdp|0.6|2.5|ttdprev=alpha 43}}||Industry tile override
|-
|0A,0B,0C||W||{{ottdp|0.6|2.5}}||Tile acceptance
|-
|0D||B||{{ottdp|0.6|2.5|ttdprev=alpha 49}}||Land shape flags
|-
|0E||B||{{ottdp|0.6|2.5|ttdprev=alpha 54}}||Callback flags
|-
|0F||W||{{ottdp|0.6|2.5|ttdprev=alpha 54}}||Animation information
|-
|10||B||{{ottdp|0.6|2.5|ttdprev=alpha 54}}||Animation speed.
|-
|11||B||{{ottdp|0.6|2.5|ttdprev=alpha 54}}||Triggers for callback 25
|-
|12||B||{{ottdp|0.6|2.5|ttdprev=beta 2}}||Special flags
|-
|13||V||{{ottdp|1.9|no|ottdrev=e66cec8f}}||Tile acceptance list
|-
|14||W n*W||{{ottdp|15}}||List of badges
|}

== Description ==

=== Substitute tile type (08) ===

This tile type will be used instead of your new one if your definition isn't available for any reason. Valid values are [http://marcin.ttdpatch.net/sv1codec/TTD-locations.html#Class8 00h-AEh]. Assigning this property copies the properties of the old type just like it does with houses.

If this tile's action 3 appears before this property is set, the action 3 will have no effect.

=== Industry tile override (09) ===

Works like the house override property for houses.

=== Tile acceptance (0A, 0B, 0C) ===

These three words define what cargoes the tile accepts, and how much of them. The low byte defines the type of the cargo according to the current climate, while the high byte defines the degree of acceptance in 1/8 units. If you don't need all three cargo types, just zero out the high byte of the extra properties.

{{grfFrom|7}} From GRF version 7 and above, the meaning of the low byte changes: instead of a climate-dependent cargo slot number, you have to give a climate-independent cargo ID. If your GRF has a cargo translation table, then this ID is the index in that table; otherwise, it's the cargo bit. Acceptance of cargoes not currently present will automatically be disabled.

{{ottdp|1.9|no|ottdrev=e66cec8f}} These properties only support three cargos. Use property 13 instead to list more cargo types.

=== Land shape flags (0D) ===

This property defines which slopes the tile can be built on.

{| |-
!Bit!!Value!!Version!!Meaning
|-
|0||1||{{ottdp|0.6|2.5}}||NW edge cannot be lowered
|-
|1||2||{{ottdp|0.6|2.5}}||NE edge cannot be lowered
|-
|2||4||{{ottdp|0.6|2.5}}||SW edge cannot be lowered
|-
|3||8||{{ottdp|0.6|2.5}}||SE edge cannot be lowered
|-
|4||10||{{ottdp|0.6|2.5}}||Can only be built on flat land
|-
|5||20||{{ottdp|0.6|2.5|ttdprev=alpha 58}}||The tile is allowed on both land and water
|}

Industry tiles are never built on steep slopes unless [[Callbacks#Custom shape check (2F) |callback 2F]] is enabled, but bits 0..4 are ignored in that case.

Bit 5 can be used to allow tiles of land industries built on water or vice versa. It effectively disables the land/water check code for the tile. If you need to customize the behavior further, you can use [[Callbacks#Custom shape check (2F) |callback 2F]] to decide what kind of water/land is allowed.

;'''PLEASE NOTE''': Be careful when setting this property. If you fail to set it correctly, your industry may end up building on a hillside, which is probably not what you want. The easiest way is to set bit 4 for middle tiles, bit 0 for the tiles along the SE edge, bit 1 for those along the SW edge and so on.

=== Callback flags (0E) ===

{| |-
!Bit!!value!!version!!meaning
|-
|0||1||{{ottdp| | }}||use [[Callbacks#Next animation frame (1A/26/141/153/158) |callback 26]] to decide the next animation frame
|-
|1||2||{{ottdp| | }}||use [[Callbacks#Length of animation frame (20/27/142/154/15A) |callback 27]] to decide animation speed
|-
|2||4||{{ottdp| |2.5|ttdprev=alpha 55 vcs 3}}||use [[Callbacks#Decide cargo acceptance (2B) |callback 2B]] to decide amount of acceptance
|-
|3||8||{{ottdp| |2.5|ttdprev=alpha 55 vcs 3}}||use [[Callbacks#Get accepted cargo types (2A/2C) |callback 2C]] to decide accepted types
|-
|4||10||{{ottdp| | }}||use [[Callbacks#Custom shape check (2F) |callback 2F]] to check if a slope is suitable
|-
|5||20||{{ottdp| | }}||use [[Callbacks#Decide drawing default foundations (30/14E/150) |callback 30]] to decide if default foundations need to be drawn
|-
|6||40||{{ottdp| |2.5|ttdprev=beta 3}}||use [[Callbacks#Disable autosloping (3C/14F/15D) |callback 3C]] to allow or deny autosloping below the tile
|}

Please note that [[Callbacks#Animation control (1B/25/140/152/159) |callback 25]] doesn't have a bit here. To use [[Callbacks#Animation control (1B/25/140/152/159) |callback 25]], simply set the wanted bits in property 11 and it will work as intended.

If bit 4 is set to activate callback 2F, the game will not automatically attempt to level the land around this tile when building a new industry.

=== Animation information (0F) ===

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 tile (this is the default value).

=== Animation speed (10) ===

The meaning is the same as for 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.

=== Triggers for [[Callbacks#Animation control (1B/25/140/152/159) |callback 25]] (11) ===

Call [[Callbacks#Animation control (1B/25/140/152/159) |callback 25]] when:

{| |-
!Property bit, var 18 byte 0!!Property value!!Version!!Meaning||Happens on||Var 18 byte 1
|-
|0||1||{{ottdp|0.6|2.5}}||the construction state changes <ref>During normal gameplay called 4 times per tile. During map generation called 1 time. {{ttdp|}} For the first call to happen, you also have to set [[Action0/Industry_Tiles#Animation_information_.280F.29|property 0F]] to some other value than 0xFFFF.</ref>||single tile||{{ottdp|15|no}} First call <ref>Var 18 bit 8 is set, if the callback is called the first time for a new industry. In-game the construction stage will be zero, at map generation and in scenario editor, it will be 3. Other bits of var 18 are reserved, and must be masked.</ref>
|-
|1||2||{{ottdp|0.6|2.5}}||the tile is processed in the periodic processing loop||single tile||
|-
|2||4||{{ottdp|0.6|2.5}}||the industry of the tile is processed in the periodic processing loop (synchronized animation)||all tiles||
|-
|3||8||{{ottdp|0.6|2.5}}||the industry of the tile receives input cargo from a station||all tiles||
|-
|4||10||{{ottdp|0.6|2.5|ttdprev=beta 2}}||the industry distributes its output cargo to one of the stations nearby||all tiles||
|}
<references />

Currently no trigger provides additional information in var 18 bytes 1 to 3.

=== Special flags (12) ===

{| |-
!Bit!!Value!!Meaning
|-
|0||1||[[Callbacks#Next animation frame (1A/26/141/153/158) |Callback 26]] needs random bits
|-
|1||2||{{ottdp|1.9|no|ottdrev=e66cec8f}} In addition to the cargotypes set by property 0A..0C and 13, the tile accepts all cargotypes which the industry accepts.
* This considers industry properties 11 and 26 and callback 14B.
* This does not consider industry callback 3D.
* 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 2C overrides all acceptances including those added by this flag.
|}

=== Tile acceptance list (13) ===
{{ottdp|1.9|no|ottdrev=e66cec8f}}

Format:
<numinput> (<cargotype> <acceptance>)*

{| |-
!Size!!Variable!!Meaning
|-
|B||numinput||Number of (<cargotype> <acceptance>) pairs to follow,
|-
|B||cargotype||Cargotype (from CTT) to accept.
|-
|B||acceptance||Acceptance in 1/8 units. May be negative to negate property 12 bit 1.
|}

This property defines up to 16 cargotypes, which are accepted by the industry tile.
Use this property instead of property 0A..0C.

==Example==

NML:Vehicles

2026-07-30T22:20:37Z

Andythenorth: Undo revision 5278 by Andythenorth (talk)

{{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
| {{ottd|15.0}} for example <code style="color:darkgreen">["power/electric", "flag/GB"]</code>
|}

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

VariationalAction2/Vehicles

2026-07-30T22:20:09Z

Andythenorth: /* Modflags (FE and FF) */ https://github.com/OpenTTD/OpenTTD/pull/15579 makes bit 11 accurate for all vehicles

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

NML:Vehicles

2026-07-30T21:47:52Z

Andythenorth: /* Variables without parameter */ modflag 0xFE bit 11 only valid for parent scope (according to nfo spec page)

{{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
| {{ottd|15.0}} for example <code style="color:darkgreen">["power/electric", "flag/GB"]</code>
|}

===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). Only valid for <code style="color:darkgreen">PARENT</code> scope.
|-
| 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.

Action0/Cargos

2026-07-02T07:10:29Z

Andythenorth: /* CargoClasses (16) */

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

GRFs including FIRS, AXIS, ITI, Sunshine Trains 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:Cargos

2026-01-17T18:49:40Z

Andythenorth: /* Cargo classes */

{{NMLNavPropVarCB}}

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

==Cargo properties==

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

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

===Cargo classes===

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

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

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

===Cargo effects on town growth===

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

If no cargos in the game are defined as TOWNGROWTH_FOOD, towns above the snowline will not require food to grow. If no cargos in the game are defined as TOWNGROWTH_FOOD or TOWNGROWTH_WATER, 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.

There are some additional effects of these flags on subsidies and town cargo transport statistics. See the nfo docs for details: https://newgrf-specs.tt-wiki.net/wiki/Action0/Cargos#Substitute_type_and_multiplier_for_town_growth_.2818.2C_19.29

===Town production effect===

{| class="wikitable sortable"
! value
! effect
|-
| TOWNPRODUCTION_PASSENGERS
| Town produces cargo as like passengers
|-
| TOWNPRODUCTION_MAIL
| Town produces cargo as like mail
|-
| TOWNPRODUCTION_NONE
| Town does not produce cargo (default)
|}

==Cargo variables==

Cargos have no variables (yet).

==Cargo callbacks==

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

===Station rating callback===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

====Callback parameters====

<ul><li>
<code style="color:darkgreen">getbits(extra_callback_info1, 0, 8)</code>:
{| |-
!value!!meaning
|-
|0x10||the last vehicle entering the station was a train
|-
|0x11||the last vehicle entering the station was a road vehicle
|-
|0x12||the last vehicle entering the station was a ship
|-
|0x13||the last vehicle entering the station was an aircraft
|-
|0||no vehicle entered the station yet, or (TTDPatch) the last one entering was sold
|}
Please note that there's only one "last vehicle type" field per station, so the vehicle this refers to may not have picked up any of your cargo.
</li><li>
<code style="color:darkgreen">getbits(extra_callback_info2, 0, 8)</code>: The time since the cargo was last picked up, in the time units described above (1 unit = 2.5 days independent of vehicle type)
</li><li>
<code style="color:darkgreen">getbits(extra_callback_info2, 8, 16)</code>: The amount of cargo waiting.
</li><li>
<code style="color:darkgreen">getbits(extra_callback_info2, 24, 8)</code>: The speed of the last vehicle picking the cargo up, in the speed units described above (if no vehicle entered the station yet, the value is 0xFF).
</li></ul>

====Effect of callback====

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

Action0/Cargos

2026-01-17T18:49:26Z

Andythenorth: /* CargoClasses (16) */

== 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}}||Color for the station list window
|-
|14||B||{{ottdp|0.6|2.5}}||Color 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:Objects

2026-01-03T19:54:33Z

Andythenorth: /* Object callbacks */ anim trigger var 0x10 Lower 16 bits are random per tile. Upper 16 bits are the same for all tiles, if the trigger applies to multiple tiles.

{{NMLNavPropVarCB}}

==Object IDs==
OpenTTD supports 64000 object types per game, and 255 object IDs per grf file.

{{ottdp|14.0|no}} 64000 object IDs per grf file are supported since OpenTTD 14.0.

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

An object is allocated by setting the 'class'-property, which should therefore be set first.

Overriding the default objects (e.g. transmitter, lighthouse) is not (yet) possible.

==Object properties==

{| class="wikitable sortable"
! property
! value range
! comment
|-
| class
| String literal of length 4
|
Unlike station classes, there is currently no default yet. '''This property ''must'' be set first, before any other properties or graphics.''' Characters allowed in the IDs are A-Z, 0-9. While you are technically free to chose your own class, it's highly recommended you stick to one of the [[#Default object classes|default classes]].
|-
| classname
| string
| You only need to set this for one object in every class.
|-
| name
| string
|
|-
| climates_available
| bitmask(CLIMATE_XXX, CLIMATE_YYY, ...)
| XXX = [TEMPERATE <nowiki>|</nowiki> ARCTIC <nowiki>|</nowiki> TROPICAL <nowiki>|</nowiki> TOYLAND], alternatively NO_CLIMATE or ALL_CLIMATES
|-
| size
| [x, y]
| Size in x and y direction. Both x and y must be compiletime constants
|-
| build_cost_multiplier
|
| multiplicator to the base purchase cost
|-
| remove_cost_multiplier
|
| multiplicator to the base removal cost
|-
| introduction_date
| date
| The date this object becomes available to build.
|-
| end_of_life_date
| date
| The last date this object is buildable. Must be at least 365 days after introduction_date
|-
| object_flags
| bitmask(OBJ_FLAG_XXX, OBJ_FLAG_YYY)
|
See [[#List of object flags|list of object flags]]
|-
| animation_info
| Array [ANIMATION_XXX, frame-count]
| XXX = [LOOPING <nowiki>|</nowiki> NON_LOOPING], 1..253 frames
|-
| animation_speed
| 0..16
|
Speed of animation, see [[NML:Animation speed|animation speed table]] for the meaning of the values.
|-
| animation_triggers
|
|
See [[#Animation_triggers|list of animation triggers]]
|-
| callback_flags
| bitmask(OBJ_CBF_XXX, OBJ_CBF_YYY)
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| height
| 0..255
| Height of the object / 8. For example if your object is 16 pixels height you should set height to 2. In OpenTTD this property is used to determine the height of the build object window; the height for the object preview is set to 32 + "value of property" * 8. The property is also used to determine how high a bridge must be if it is allowed by the bit in object_flags.
|-
| num_views
| 1, 2 or 4
| Objects may have "views", i.e. different graphical representations, e.g. used to show rotated views of an object. Number of views may be 1, 2, or 4. Default value is 1. For non-square objects, x and y sizes are swapped for odd views. Use variable <code style="color:darkgreen">view</code> to determine the view of a built object. Views should be used for rotations or minor variations, not for objects of different types as those should just be different object types which provides a better experience for players. Using separate objects is better for discoverability, naming, filtering, used state, favourite state, and badges.
|-
| count_per_map256
| 0..255
| {{ottd|1.4|r25878}} Measure for the amount of objects placed on a map of 256^2 tiles. (Comparison: there are 15 transmitter)
|}

===Default object classes===

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

===List of object flags===

{| class="wikitable sortable"
! Name
! Meaning
|-
| OBJ_FLAG_ONLY_SE
| Only available in the scenario editor (incompatible with OBJ_FLAG_ONLY_INGAME).
|-
| OBJ_FLAG_IRREMOVABLE
| Object cannot be removed with the normal dynamite tool. In OpenTTD you can only remove the object with the magic bulldozer cheat, in TTDPatch you can remove it by holding ctrl while using the bulldozer tool. The cost of removing this object is multiplied by 25.
|-
| OBJ_FLAG_ANYTHING_REMOVE
| Anything can remove this object (owned land behavior).
|-
| OBJ_FLAG_ON_WATER
| Allow construction of the object on water. Note that if an object is allowed to be built both on land and on water, then it will resist being flooded and will not flood adjacent tiles.
This flag has the same effect as using ''GROUNDSPRITE_WATER'' for the ground sprite in the spritelayout.
|-
| OBJ_FLAG_REMOVE_IS_INCOME
| Removal cost is actually income (owned land behaviour).
|-
| OBJ_FLAG_NO_FOUNDATIONS
| Do not display foundations if on a slope.
|-
| OBJ_FLAG_ANIMATED
| Setting this flag will allow the object's animation counter to be increased, must be set if you plan to make use of animations.
|-
| OBJ_FLAG_ONLY_INGAME
| Only available during game play (incompatible with OBJ_FLAG_ONLY_SE).
|-
| OBJ_FLAG_2CC
| Allows 2cc mapping for objects instead of the default 1cc.
|-
| OBJ_FLAG_NOT_ON_LAND
| Disallows construction on land (implies OBJ_FLAG_ON_WATER).
|-
| OBJ_FLAG_DRAW_WATER
| Draws the water under the object. Only applies when built on top of a water tile, also replaces the ground tile of the object completely. Does not work when object built on sloped water tiles.
|-
| OBJ_FLAG_ALLOW_BRIDGE
| Allow bridge over the object taking the building height into account.
|-
| OBJ_FLAG_RANDOM_ANIMATION
| Random bits in the "next animation frame" callback.
|-
| OBJ_FLAG_SCALE_BY_WATER
| Scale amount of objects placed on map generation not by map area, but roughly by the length of the coastline
|}

==Object variables==

{| class="wikitable sortable"
! name
! value range
! comment
|-
| relative_x
| 0..255
| X-coordinate (top right -> bottom left) of the tile relative to the northernmost tile.
|-
| relative_y
| 0..255
| Y-coordinate (top left -> bottom right) of the tile relative to the northernmost tile.
|-
| relative_pos
| 0xYYXX
|
A combination of relative_x and relative_y in the format 0xYYXX. Useful if you want to check for a single position. The [[NML:Builtin functions|builtin function]] relative_coord(x, y) may be useful when making comparisons.
|-
| terrain_type
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|
|-
| tile_slope
| SLOPE_XXX
|
See [[NML:List of tile slopes|tile slopes]] for an overview of possible values
|-
| build_date
|
| The date this object was build.
|-
| animation_frame
| 0 .. (frame_count - 1)
| Current animation frame, with the maximum defined in the object's <code style="color:darkgreen">animation_info</code> property.
|-
| colour
| COLOUR_XXX
|
Colour used for the company colour mask. Refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for possible values.
|-
| owner
| 0..0x10
| CompanyID of the owner of the object or 0x10 if it was build in the scenario editor
|-
| town_manhattan_dist
|
| Manhattan distance to the nearest town
|-
| town_euclidean_dist
|
| Euclidean distance to the nearest town
|-
| town_zone
|
[[NML:List of town zones|town zone]]
| The town zone of the current tile. The town zone from the closest town (measured in manhattan distance) is used.
|-
| view
| 0 .. (<code style="color:darkgreen">num_views</code> - 1)
|
{{ottd|1.1|r21455}} The view of the particular object. See also the <code style="color:darkgreen">num_views</code> property.
|}

Variables that require one or more parameters:

{| class="wikitable sortable"
! name
! arguments
! value range
! comment
|-
| nearby_tile_object_type
| x, y offset (-8..7)
|
| ID of the object on a nearby tile, if defined by the same grf. OBJECT_TYPE_OTHER_GRF if the object is defined by a different grf (or none at all). OBJECT_TYPE_NO_OBJECT if the tile does not contain an object.
|-
| nearby_tile_object_view
| x, y offset (-8..7)
|
| {{ottdp|1.4|no|ottdrev=r26316}} View of the object on a nearby tile, if defined by the same grf.
|-
| nearby_tile_random_bits
| x, y offset (-8..7)
|
| Random bits of the given tile. Only valid for tiles of the same object.
|-
| nearby_tile_slope
| x, y offset (-8..7)
|
| See tile_slope
|-
| nearby_tile_is_same_object
| x, y offset (-8..7)
| 0 .. 1
| Is the given tile part of the same object?
|-
| nearby_tile_is_water
| x, y offset (-8..7)
| 0 .. 1
| Is the given tile a water tile?
|-
| nearby_tile_terrain_type
| x, y offset (-8..7)
|
| See terrain_type
|-
| nearby_tile_water_class
| x, y offset (-8..7)
| WATER_CLASS_XXX
| XXX = [NONE <nowiki>|</nowiki> SEA <nowiki>|</nowiki> CANAL <nowiki>|</nowiki> RIVER] Note that tiles for which <code style="color:darkgreen">nearby_tile_is_water</code> is 0 may still have a water class, e.g. industry tiles with water beneath them.
|-
| nearby_tile_height
| x, y offset (-8..7)
| 0 .. 120
| The minimum height of the given tile. 8 units correspond to one height level
|-
| nearby_tile_class
| x, y offset (-8..7)
|
[[NML:List of tile classes|Tile class]]
|
|-
| nearby_tile_animation_frame
| x, y offset (-8..7)
|
| See animation_frame. Only valid for tiles of the same object.
|-
| object_count
| object id [, grfid]
| 0..0xFFFF
|
Number of objects with the given object id currently on the map. Grfid is the grfid of the newgrf you want to check the object count of (default is current grf). Use the [[NML:Builtin functions|builtin function]] <code style="color:darkgreen">str2number()</code> to convert a grfid to its numeric representation.
|-
| object_distance
| object id [, grfid]
| 0..0xFFFF
|
Manhattan distance to the closest object of the given type. Grfid is the grfid of the newgrf you want to check the minimum object distance of (default is current grf). Use the [[NML:Builtin functions|builtin function]] <code style="color:darkgreen">str2number()</code> to convert a grfid to its numeric representation. If the given object type is not yet built, this will return 0xFFFF
|}

==Object callbacks==

{| class="wikitable sortable"
! callback
! return value
! comment
|-
| default
| Sprite layout
| Normal graphics for an object placed on the map
|-
| purchase <ref name="notyetbuilt">These callbacks are called when the object is not yet built, so object- specific variables cannot be accessed. Trying to do so will result in undefined behaviour.</ref>
| Sprite layout
| Graphics shown in the build menu
|-
| anim_next_frame
| Next animation frame or CB_RESULT_XXX
| Called for every animation frame, returns the next frame to display. Alternatively, return CB_RESULT_NEXT_FRAME or CB_RESULT_STOP_ANIMATION to show the next frame or stop animation, respectively. 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.
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 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>: if the object flag OBJ_FLAG_RANDOM_ANIMATION is set, 32 random bits. {{ottdp|15|no}} Lower 16 bits are random per tile. Upper 16 bits are the same for all tiles, if the trigger applies to multiple tiles.
* <code style="color:darkgreen">getbits(extra_callback_info2, 0, 8)</code>: Reason for the callback trigger, see the [[#Animation triggers| table]] below.
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.
|-
| colour
| colour2*16 + colour1
|
Called once, just after construction.
* <code style="color:darkgreen">getbits(extra_callback_info1, 0, 8)</code>: Colour scheme of the constructing company in the same format as the return value, or random colours if not available (scenario editor). If OBJ_FLAG_2CC is not set, colour2 is zero.
This callback can be used to alter the colour scheme of an object. Refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for possible colour values.
|-
| autoslope
| CB_RESULT[_NO]_AUTOSLOPE
| Return CB_RESULT_AUTOSLOPE to allow autoslope (altering the ground below a tile) or CB_RESULT_NO_AUTOSLOPE to disallow it.
|-
| tile_check <ref name="notyetbuilt"/>
|
See the [[#Location check results|table]] below
|
* <code style="color:darkgreen">getbits(extra_callback_info1, 0, 5)</code>: Tile slope, see below
* <code style="color:darkgreen">getbits(extra_callback_info2, 0, 8)</code>: The location of the tile within the object as 16*y + x.
If this callback is not implemented or fails, the default behaviour is to allow building the object if it can be placed on a flat surface. This means that steep slopes are not allowed and that the highest corner of each tile of a multi-tile object should have the same height. Additionally, all tiles must be flat if "build on slopes" is disabled.
|-
| additional_text <ref name="notyetbuilt"/>
| String
| Additional text to show in the purchase menu
|}

<references/>

{{NML:LocationCheckResults}}

===Animation triggers===

{| class="wikitable sortable"
! Animation trigger
! Description
|-
| ANIM_TRIGGER_OBJ_BUILT
| Object is built (all tiles at the same time)
|-
| ANIM_TRIGGER_OBJ_TILELOOP
| Object tile is processed in the tileloop (at different times for different tiles)
|-
| ANIM_TRIGGER_OBJ_256_TICKS
| Every 256 ticks (all tiles at the same time)
|}

NML:Airports

2026-01-03T19:52:40Z

Andythenorth: /* Airport tile callbacks */ animation trigger var 0x10 changed: Lower 16 bits are random per tile. Upper 16 bits are the same for all tiles, if the trigger applies to multiple tiles.

{{NMLNavPropVarCB}}

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

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

Furthermore, you can set the 'override'-property, which will cause the existing airport tile to be replaced with your item. For airports, there only is an 'override'-property, which acts as a combined substitute and override.

==Airport properties==

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

==Airport tile properties==

{| class="wikitable sortable"
! name
! value range
! comment
|-
| override
|
|
{{ottd|1.1|r19204}} The id of airport tile to override, see [[AirportTypes]]. '''This property ''must'' be set first, before any other properties or graphics.'''
|-
| substitute
|
|
{{ottd|1.1|r19204}} The id of airport tile to replace
|-
| callback_flags
| bitmask
|
{{ottd|1.1|r19204}} Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| animation_info
| Array [ANIMATION_XXX, frame-count]
|{{ottd|1.1|r19204}} XXX = [LOOPING <nowiki>|</nowiki> NON_LOOPING], 1..253 frames
|-
| animation_speed
|
|
{{ottd|1.1|r19204}} See [[NML:Animation speed|speed settings]]
|-
| animation_triggers
| bitmask(ANIM_TRIGGER_APT_XXX, ... )
|
{{ottd|1.1|r19204}} Bitmask of triggers that will trigger the <code style="color:darkgreen">anim_control</code> callback, see the [[#Animation triggers|table]] below.
|}

==Airport variables==

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

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

==Airport tile variables==

{| class="wikitable sortable"
! name
! value range
! comment
|-
| terrain_type
|
|
|-
| town_radius_group
|
|
|-
| relative_x
| 0..255
| X-coordinate (top right -> bottom left) of the tile relative to the northernmost tile.
|-
| relative_y
| 0..255
| Y-coordinate (top left -> bottom right) of the tile relative to the northernmost tile.
|-
| relative_pos
| 0xYYXX
|
A combination of relative_x and relative_y in the format 0xYYXX. Useful if you want to check for a single position. The [[NML:Builtin functions|builtin function]] relative_coord(x, y) may be useful when making comparisons.
|-
| animation_frame
|
|
|-
| random_bits_station
| 0..65535
| 16 random bits, shared between all station parts (rail station parts, airports tiles, ...)
|-
| random_bits_tile
| 0..15
| 4 random bits, specific to this station tile.
|}

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

{| class="wikitable sortable"
! name
! value range
! comment
|-
| nearby_tile_slope
| SLOPE_XXX
|
See [[NML:List of tile slopes|tile slopes]] for an overview of possible values
|-
| nearby_tile_is_same_airport
| 1 if the tile is part of the same airport, 0 otherwise
|
|-
| nearby_tile_is_water
| 1 if the tile is water, 0 otherwise
|
|-
| nearby_tile_terrain_type
| TILETYPE_XX
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|-
| nearby_tile_water_class
| WATER_CLASS_XXX
| XXX = [NONE <nowiki>|</nowiki> SEA <nowiki>|</nowiki> CANAL <nowiki>|</nowiki> RIVER] Note that tiles for which <code style="color:darkgreen">nearby_tile_is_water</code> is 0 may still have a water class, e.g. industry tiles with water beneath them.
|-
| nearby_tile_height
| 0..120
| The height of the lowest corner of the given tile.
|-
| nearby_tile_class
|
[[NML:List of tile classes|Tile class]]
|
|-
| nearby_tile_animation_frame
| 0..255
| Animation frame of the given tile
|-
| nearby_tile_airporttile_id
| 0x00aa, 0xFFbb, 0xFFFE or 0xFFFF
| 0x00aa: The tile is an airport tile that is part of this GRF, the tile id is aa. 0xFFbb: The tile is an original airport tile with id bb. 0xFFFE: The tile is an airport tile defined in another GRF. 0xFFFF: The tile is not an airport tile or it belongs to another airport.
|}

==Airport callbacks==

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

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

==Airport tile callbacks==

{| class="wikitable sortable"
! callback
! return value
! comment
|-
| default
| Sprite layout
| Graphics for an airport tile
|-
| anim_next_frame
| Next animation frame or CB_RESULT_XXX
| Called for every animation frame, returns the next frame to display. Alternatively, return CB_RESULT_NEXT_FRAME or CB_RESULT_STOP_ANIMATION to show the next frame or stop animation, respectively. 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.
|-
| 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. {{ottdp|15|no}} Lower 16 bits are random per tile. Upper 16 bits are the same for all tiles, if the trigger applies to multiple tiles.
* <code style="color:darkgreen">getbits(extra_callback_info2, 0, 8)</code>: Reason for 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.
|-
| anim_speed
| 0 .. 16
| Decide the time an animation frame should last. Return value is interpreted as (num_ticks = 2^anim_speed), which each tick lasting 30 ms. Avoid using this callback if possible, since it has to be called each tick for every animated tile. This can be used to create animation frames that last between 30 ms and 33 minutes.
|-
| foundations
| CB_RESULT[_NO]_FOUNDATIONS
| Return CB_RESULT_FOUNDATIONS to draw standard foundations (default) or CB_RESULT_NO_FOUNDATIONS to not draw them.
|}

===Animation triggers===

{| class="wikitable sortable"
! Animation trigger
! Description
|-
| ANIM_TRIGGER_APT_BUILT
| Airport is built (all tiles at the same time)
|-
| ANIM_TRIGGER_APT_TILELOOP
| Airport tile is processed in the tileloop (at different times for different tiles)
|-
| ANIM_TRIGGER_APT_NEW_CARGO
| New cargo arrives at the airport (all tiles at the same time)
|-
| ANIM_TRIGGER_APT_CARGO_TAKEN
| All cargo of a cargo type is removed from the airport (all tiles at the same time)
|-
| ANIM_TRIGGER_APT_250_TICKS
| Every 250 ticks (all tiles at the same time)
|-
| ANIM_TRIGGER_APT_AIRPLANE_LANDS
| {{ottd|1.9}} Triggered when an airplane (not a helicopter!) lands at airport (single tile only)
|}

NML:Vehicles

2026-01-03T18:49:49Z

Andythenorth: /* Vehicle callbacks */ bad formatting

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

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

|}
<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-01-03T18:47:03Z

Andythenorth: /* Vehicle callbacks */ add refit cb

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

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

|}
<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:Tramtypes

2026-01-03T17:58:54Z

Andythenorth: /* Tramtype variables */ document railtype, roadtype, tramtype variables

{{NMLNavPropVarCB}}

Tramtypes can only be defined in OpenTTD {{ottd|1.10}} and {{nml|0.5}} or later.

==Tramtype IDs==
Tramtypes and Roadtypes share a pool of 63 IDs. Either feature can use as many IDs as needed (i.e. it is not limited to 32 per type), but both features combined are limited to 63 in total. NewGRF-local IDs may freely be chosen, but must be in the 0..62 range. If other tramtype/roadtype GRFs are loaded, it may be that there are not enough slots available. To prevent your entire NewGRF from being deactivated with the 'Attempt to use invalid ID'-error, you can use the following code:

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

== Vehicle and Tramtype availability ==

Vehicle and tramtype availability and compatibility is influenced by multiple properties.
Generally, the vehicle defines which tramtype it is, and the tramtypes define the compatibility between each other.
* Remember that the road vehicle flag 'ROADVEH_FLAG_TRAM' must be set in order for a road vehicle to be considered a tram.
* A vehicle exists, if its tramtype (road vehicle property <code style="color:green">tram_type</code>) is defined. Otherwise the vehicle is disabled.
* When a vehicle is introduced, it always introduces its tramtype (road vehicle property <code style="color:green">tram_type</code>).
* A tramtype is introduced, if at least one of the following conditions is met:
** A vehicle is introduced, that references the tramtype (road vehicle property <code style="color:green">tram_type</code>).
** Another tramtype is introduced, that references the tramtype via the introduced tramtype list (tramtype property <code style="color:green">introduces_tramtype_list</code>).
** The introduction date (tramtype property <code style="color:green">introduction_date</code>) is passed and all required tramtypes (tramtype property <code style="color:green">requires_tramtype_list </code>) are available.

Via tramtype property <code style="color:green">powered_tramtype_list</code> multiple tramtypes can be defined, which shall be considered equivalent to a tramtype.
This affects the interpretation of road vehicle property <code style="color:green">tram_type</code>. If road vehicle property <code style="color:green">tram_type</code> references an undefined tramtype, then tramtype property <code style="color:green">powered_tramtype_list</code> is checked for all defined tramtypes, whether the vehicle can be reassigned to some other tramtype. Otherwise the vehicle is disabled.

==Tramtype properties==

{| class="wikitable sortable"
! property
! value range
! comment
|-
| label
| 4-byte string
| names of default tram types: "RAIL" and "ELRL". See the [[TramtypeLabels|List of tramtype labels]] in the NewGRF Specs for currently defined custom labels.
|-
| introduction_date
| date(yyyy,mm,dd)
| Valid range for yyyy is 0 ... 5000000.
|-
| name
| string
| Name of this tramtype
|-
| toolbar_caption
| string
| Caption of the build tram toolbar. In earlier versions this is the same as the 'name'
|-
| menu_text
| string
| Shown in the dropdown menu for all tramtypes
|-
| build_window_caption
| string
| Caption of the build vehicle window
|-
| autoreplace_text
| string
| String for the autoreplace window
|-
| new_engine_text
| string
| String for the "We have invented a new <tram type> engine" news message
|-
| powered_tramtype_list
| list of tramtype labels
| Provide a list of tram types that tram vehicles of this type are powered on, e.g. ["RAIL", "ELRL"]. Note that there is no "compatible_tramtype_list" since there is no difference between "powered" and "compatible" for tramtypes
|-
| tramtype_flags
| bitmask(TRAMTYPE_FLAG_XXX, ...)
|
;CATENARY
:Enable catenary
;NO_LEVEL_CROSSING
:Disable level crossings
;NO_HOUSES
:Disallows house construction
;HIDDEN
:Hides the tramtype from players, but remains available to towns...which can't use them
;TOWN_BUILD
:Towns don't build tramtracks...so not sure what the purpose of this is
|-
| construction_cost
| 0 ... 65525
| Per piece of track as multiplier to PR_BUILD_ROAD base cost. Default cost factors are 8 and 16 for RAIL and ELRL, respectively.
|-
| speed_limit
| 0 ... 65525 km/h (speed units)
| A speed limit of 0 means unlimited speed
|-
| map_colour
| 0 ... 255
| Entry in the colour palette.
|-
| requires_tramtype_list
| list of tramtype labels
| List of tram types that need to be available to the company of the player for this tram type to be introduced at (or after) the introduction date. This limit does not apply when the tram type is introduced by the introduction of a vehicle.
|-
| introduces_tramtype_list
| list of tramtype labels
| List of tram types that get introduced when this tram type is introduced. For example, to make sure that when a fast tram type is introduced the slow variant exists.
|-
| sort_order
| 0 ... 255
| Number which defines the sort order among tram types. If this entry is not defined, it gets assigned sort order n*10+7 for the n-th tramtype.
|-
| maintenance_cost
| 0 ... 255
| Maintenance cost factor for each piece of tram of this tramtype. Default cost factors are 16 and 24 for RAIL and ELRL, respectively.
|-
| alternative_tramtype_list
| list of tramtype labels
| List of tram types which this tram type will act as fallback for, if the corresponding tram type is not defined separately
|}

===Sort order===

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

{| class="t"
! Value
! Meaning
|-
| 07
| normal tram
|-
| 17
| electrified tram
|-
| n7
| tramtype #n
|}

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

==Tramtype variables==

{| class="wikitable sortable"
! name
! value range
! comment
|-
| terrain_type
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|
|-
| enhanced_tunnels
| 0
| Reserved for future use, always returns 0 in OpenTTD. Should custom tunnel entrances be implemented, other values than 0 might be returned
|-
| level_crossing_status
| LEVEL_CROSSING_CLOSED, LEVEL_CROSSING_OPEN
|
|-
| build_date
| 0 .. 5000000
| for depots only: build date of the depot in days since 0
|-
| town_zone
| [[NML:List of town zones|town zone]]
| Town zone of the tile
|-
| random_bits
|
| 2 pseudo random bits
|-
| railtype
| Entry from railtype translation table or RAILTYPE_OTHER_GRF or RAILTYPE_NO_ROAD
| railtype present on the tile
|-
| roadtype
| Entry from roadtype translation table or ROADTYPE_OTHER_GRF or ROADTYPE_NO_ROAD
| roadtype present on the tile
|-
| tramtype
| Entry from tramtype translation table or TRAMTYPE_OTHER_GRF or TRAMTYPE_NO_ROAD
| tramtype present on the tile
|}

==Tramtype callbacks==

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

{| class="wikitable sortable"
! callbacks
! number of sprites
! meaning
|-
| gui
| 12
| 6 gui icons, 6 cursors
|-
| track_overlay<ref name=leftout>Either all or none of these sprites should be provided.</ref>
| 19
| 11 track combinations, 4 slopes, and 4 dead ends. These sprites are required
|-
| underlay<ref name=leftout />
| 19
| 11 track combinations, 4 slopes, and 4 dead ends. These sprites are required

|-
| catenary_front
| 29
| 11 track combinations, 4 slopes, 4 dead ends, 4 tunnels, 2 bridge middle, 4 bridge ramps
|-
| catenary_back
| 29
| 11 track combinations, 4 slopes, 4 dead ends, 4 tunnels (unused), 2 bridge middle, 4 bridge ramps
|-
| bridge_surfaces<ref name=leftout />
| 6
| 2 bridge middle, 4 bridge ramps
|-
| depots
| 6
| If not present, the default depot sprites (depending on catenary flag) plus track overlay are drawn.
If present, the depot sprites are expected to include track overlay graphics.

|}

<references />
Note that there is no "default" graphics callback.

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

[[File:Nrt_gui.png]]

==== underlay ====

[[File:Nrt_underlay.png]]

==== overlay ====

[[File:Nrt_overlay.png]]

==== catenary_front ====

[[File:Nrt_catenary_front.png]]

==== catenary_back ====

[[File:Nrt_catenary_back.png]]

==== depots ====

[[File:Nrt_depot.png]]

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

==== bridge_surfaces ====

[[File:Nrt_bridge.png]]


===Example code===

A typical implementation for tramtypes can look like:

<pre style="color:blue">
item(FEAT_TRAMTYPES, dctram, 0x01) {
property {
label: "DCTM";
name: string(STR_DC_TRAM);
menu_text: string(STR_DC_TRAM);
build_window_caption: string(STR_BUILD_CAPTION);
autoreplace_text: string(STR_AUTOREPLACE);
new_engine_text: string(STR_NEW_ENGINE);
powered_tramtype_list: ["DCTM","ELRL"]; // These trams are compatible with other electric trams
tramtype_flags: bitmask(TRAMTYPE_FLAG_CATENARY); // These tramways require catenary
construction_cost: 24; // Electric tramways are pricey
speed_limit: 50 km/h;
}
graphics {
underlay: ground_switch_underlay; // defines the tramtrack underlay
overlay: track_overlay_switch; // defines the tramtrack overlay
tunnels: tunnel_switch; // defines the track drawn on a tunnel tile
depots: depot_switch; // defines the depot sprites
bridge_surfaces: bridge_terrain_switch; // defines the overlay drawn over bridges depending on climate
}
}
</pre>

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

NML:Roadtypes

2026-01-03T17:58:14Z

Andythenorth: /* Roadtype variables */ FML wiki formatting

{{NMLNavPropVarCB}}

Roadtypes can only be defined in OpenTTD {{ottd|1.10}} and {{nml|0.5}} or later.

==Roadtype IDs==
Roadtypes and Tramtypes share a pool of 63 IDs. Either feature can use as many IDs as needed (i.e. it is not limited to 32 per type), but both features combined are limited to 63 in total. NewGRF-local IDs may freely be chosen, but must be in the 0..62 range. If other roadtype/tramtype GRFs are loaded, it may be that there are not enough slots available. To prevent your entire NewGRF from being deactivated with the 'Attempt to use invalid ID'-error, you can use the following code:

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

== Vehicle and Roadtype availability ==

Vehicle and roadtype availability and compatibility is influenced by multiple properties.
Generally, the vehicle defines which roadtype it is, and the roadtypes define the compatibility between each other.
* A vehicle exists, if its roadtype (road vehicle property <code style="color:green">road_type</code>) is defined. Otherwise the vehicle is disabled.
* When a vehicle is introduced, it always introduces its roadtype (road vehicle property <code style="color:green">road_type</code>).
* A roadtype is introduced, if at least one of the following conditions is met:
** A vehicle is introduced, that references the roadtype (road vehicle property <code style="color:green">road_type</code>).
** Another roadtype is introduced, that references the roadtype via the introduced roadtype list (roadtype property <code style="color:green">introduces_roadtype_list</code>).
** The introduction date (roadtype property <code style="color:green">introduction_date</code>) is passed and all required roadtypes (roadtype property <code style="color:green">requires_roadtype_list </code>) are available.

Via roadtype property <code style="color:green">powered_roadtype_list</code> multiple roadtypes can be defined, which shall be considered equivalent to a roadtype.
This affects the interpretation of road vehicle property <code style="color:green">road_type</code>. If road vehicle property <code style="color:green">road_type</code> references an undefined roadtype, then
roadtype property <code style="color:green">powered_roadtype_list</code> is checked for all defined roadtypes, whether the vehicle can be reassigned to some other roadtype.
Otherwise the vehicle is disabled.

==Roadtype properties==

{| class="wikitable sortable"
! property
! value range
! comment
|-
| label
| 4-byte string
| names of default road types: "ROAD" and "ELRD". See the [[RoadtypeLabels|List of roadtype labels]] in the NewGRF Specs for currently defined custom labels.
|-
| introduction_date
| date(yyyy,mm,dd)
| Valid range for yyyy is 0 ... 5000000.
|-
| name
| string
| Name of this roadtype
|-
| toolbar_caption
| string
| Caption of the build road toolbar
|-
| menu_text
| string
| Shown in the dropdown menu for all roadtypes
|-
| build_window_caption
| string
| Caption of the build vehicle window
|-
| autoreplace_text
| string
| String for the autoreplace window
|-
| new_engine_text
| string
| String for the "We have invented a new <road type> engine" news message
|-
| powered_roadtype_list
| list of roadtype labels
| Provide a list of road types that road vehicles of this type are powered on, e.g. ["ROAD", "ELRD"]. Note that there is no "compatible_roadtype_list" since there is no difference between "powered" and "compatible" for roadtypes
|-
| roadtype_flags
| bitmask(ROADTYPE_FLAG_XXX, ...)
|
;CATENARY
:Enable catenary
;NO_LEVEL_CROSSING
:Disable level crossings
;NO_HOUSES
:Disallows house construction
;HIDDEN
:Hides the roadtype from players, but remains available to towns
;TOWN_BUILD
:Enables the roadtype to be built by towns, picked by highest speed (defaults to ROAD if no speed limits?)
|-
| construction_cost
| 0 ... 65525
| Per piece of road as multiplier to PR_BUILD_ROAD base cost. Default cost factors are 8 and 16 for ROAD and ELRD, respectively.
|-
| speed_limit
| 0 ... 65525 km/h (speed units)
| A speed limit of 0 means unlimited speed
|-
| map_colour
| 0 ... 255
| Entry in the colour palette.
|-
| requires_roadtype_list
| list of roadtype labels
| List of road types that need to be available to the company of the player for this road type to be introduced at (or after) the introduction date. This limit does not apply when the road type is introduced by the introduction of a vehicle.
|-
| introduces_roadtype_list
| list of roadtype labels
| List of road types that get introduced when this road type is introduced. For example, to make sure that when a fast road type is introduced the slow variant exists.
|-
| sort_order
| 0 ... 255
| Number which defines the sort order among road types. If this entry is not defined, it gets assigned sort order n*10+7 for the n-th roadtype.
|-
| maintenance_cost
| 0 ... 255
| Maintenance cost factor for each piece of road of this roadtype. Default cost factors are 16 and 24 for ROAD and ELRD, respectively.
|-
| alternative_roadtype_list
| list of roadtype labels
| List of road types which this road type will act as fallback for, if the corresponding road type is not defined separately
|}

===Sort order===

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

{| class="t"
! Value
! Meaning
|-
| 07
| normal road
|-
| 17
| electrified road
|-
| n7
| roadtype #n
|}

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

==Roadtype variables==

{| class="wikitable sortable"
! name
! value range
! comment
|-
| terrain_type
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|
|-
| enhanced_tunnels
| 0
| Reserved for future use, always returns 0 in OpenTTD. Should custom tunnel entrances be implemented, other values than 0 might be returned
|-
| level_crossing_status
| LEVEL_CROSSING_CLOSED, LEVEL_CROSSING_OPEN
|
|-
| build_date
| 0 .. 5000000
| for depots only: build date of the depot in days since 0
|-
| town_zone
| [[NML:List of town zones|town zone]]
| Town zone of the tile
|-
| random_bits
|
| 2 pseudo random bits, based on tile location
|-
| railtype
| Entry from railtype translation table or RAILTYPE_OTHER_GRF or RAILTYPE_NO_ROAD
| railtype present on the tile
|-
| roadtype
| Entry from roadtype translation table or ROADTYPE_OTHER_GRF or ROADTYPE_NO_ROAD
| roadtype present on the tile
|-
| tramtype
| Entry from tramtype translation table or TRAMTYPE_OTHER_GRF or TRAMTYPE_NO_ROAD
| tramtype present on the tile
|-
|}

==Roadtype callbacks==

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

{| class="wikitable sortable"
! callbacks
! number of sprites
! meaning
|-
| gui
| 12
| 6 gui icons, 6 cursors
|-
| track_overlay<ref name=leftout>Either all or none of these sprites should be provided.</ref>
| 19
| 11 roadbit combinations, 4 slopes, and 4 dead ends. These sprites are optional for roadtypes.
|-
| underlay<ref name=leftout />
| 19
| 11 roadbit combinations, 4 slopes, and 4 dead ends. These sprites are required.
|-
| tunnels<ref name=leftout />
| 4
| {{ottd|13}} and {{nml|0.7.2}} 1 sprite for each direction. Sprite is overlay for road in existing tunnel graphics. The original ground sprite is drawn, then the overlay, then possibly a road vehicle and the original tunnel head is drawn over the top. This keeps compatibility with different landscape types. Sprite order: SW, NW, NE, SE.
|-
| catenary_front
| 29
| 11 roadbit combinations, 4 slopes, 4 dead ends, 4 tunnels, 2 bridge middle, 4 bridge ramps
|-
| catenary_back
| 29
| 11 roadbit combinations, 4 slopes, 4 dead ends, 4 tunnels (unused), 2 bridge middle, 4 bridge ramps
|-
| bridge_surfaces<ref name=leftout />
| 6
| 2 bridge middle, 4 bridge ramps
|-
| depots
| 6
| If not present, the default depot sprites (depending on catenary flag) plus track overlay are drawn.
If present, the depot sprites are expected to include track overlay graphics.

|-
| roadstops
| 4
| Overlays for drive-in road stops
|-
| direction_markings
| 18
| {{ottd|13}} and {{nml|0.7.4}} Overlays for one-way roads: repeat (arrow facing SW, arrow NE, impassable NE-SW, arrow NW, arrow SE, impassable NW-SE) for flat, N corner raised, S corner raised.
|}

<references />
Note that there is no "default" graphics callback.

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

[[File:Nrt_gui.png]]

==== underlay ====

[[File:Nrt_underlay.png]]

==== catenary_front ====

[[File:Nrt_catenary_front.png]]

==== catenary_back ====

[[File:Nrt_catenary_back.png]]

==== depots ====

[[File:Nrt_depot.png]]

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

==== bridge_surfaces ====

[[File:Nrt_bridge.png]]

==== roadstops ====

[[File:Nrt_drivein.png]]


==== direction_markings ====

[[File:Nrt_oneway.png]]

===Example code===

A typical implementation for roadtypes can look like:

<pre style="color:blue">
item(FEAT_ROADTYPES, highway, 0x01) {
property {
label: "HWY_";
name: string(STR_HWY);
menu_text: string(STR_HWY);
build_window_caption: string(STR_BUILD_CAPTION);
autoreplace_text: string(STR_AUTOREPLACE);
new_engine_text: string(STR_NEW_ENGINE);
powered_roadtype_list: ["HWY_","ROAD"]; // Highways are compatible with other roads
roadtype_flags: bitmask(ROADTYPE_FLAG_NO_LEVEL_CROSSING, ROADTYPE_FLAG_NO_HOUSES); // Highways should not have level crossings or houses
construction_cost: 32; // Highways are expensive
speed_limit: 100 km/h;
}
graphics {
underlay: ground_switch_underlay; // defines the usual roads
depots: depot_switch; // defines the depot sprites
bridge_surfaces: bridge_terrain_switch; // defines the overlay drawn over bridges depending on climate
roadstops: roadstops_switch; // defines the look of roadstop pavement
}
}
</pre>

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

NML:Roadtypes

2026-01-03T17:57:50Z

Andythenorth: /* Roadtype variables */ fix paste error

{{NMLNavPropVarCB}}

Roadtypes can only be defined in OpenTTD {{ottd|1.10}} and {{nml|0.5}} or later.

==Roadtype IDs==
Roadtypes and Tramtypes share a pool of 63 IDs. Either feature can use as many IDs as needed (i.e. it is not limited to 32 per type), but both features combined are limited to 63 in total. NewGRF-local IDs may freely be chosen, but must be in the 0..62 range. If other roadtype/tramtype GRFs are loaded, it may be that there are not enough slots available. To prevent your entire NewGRF from being deactivated with the 'Attempt to use invalid ID'-error, you can use the following code:

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

== Vehicle and Roadtype availability ==

Vehicle and roadtype availability and compatibility is influenced by multiple properties.
Generally, the vehicle defines which roadtype it is, and the roadtypes define the compatibility between each other.
* A vehicle exists, if its roadtype (road vehicle property <code style="color:green">road_type</code>) is defined. Otherwise the vehicle is disabled.
* When a vehicle is introduced, it always introduces its roadtype (road vehicle property <code style="color:green">road_type</code>).
* A roadtype is introduced, if at least one of the following conditions is met:
** A vehicle is introduced, that references the roadtype (road vehicle property <code style="color:green">road_type</code>).
** Another roadtype is introduced, that references the roadtype via the introduced roadtype list (roadtype property <code style="color:green">introduces_roadtype_list</code>).
** The introduction date (roadtype property <code style="color:green">introduction_date</code>) is passed and all required roadtypes (roadtype property <code style="color:green">requires_roadtype_list </code>) are available.

Via roadtype property <code style="color:green">powered_roadtype_list</code> multiple roadtypes can be defined, which shall be considered equivalent to a roadtype.
This affects the interpretation of road vehicle property <code style="color:green">road_type</code>. If road vehicle property <code style="color:green">road_type</code> references an undefined roadtype, then
roadtype property <code style="color:green">powered_roadtype_list</code> is checked for all defined roadtypes, whether the vehicle can be reassigned to some other roadtype.
Otherwise the vehicle is disabled.

==Roadtype properties==

{| class="wikitable sortable"
! property
! value range
! comment
|-
| label
| 4-byte string
| names of default road types: "ROAD" and "ELRD". See the [[RoadtypeLabels|List of roadtype labels]] in the NewGRF Specs for currently defined custom labels.
|-
| introduction_date
| date(yyyy,mm,dd)
| Valid range for yyyy is 0 ... 5000000.
|-
| name
| string
| Name of this roadtype
|-
| toolbar_caption
| string
| Caption of the build road toolbar
|-
| menu_text
| string
| Shown in the dropdown menu for all roadtypes
|-
| build_window_caption
| string
| Caption of the build vehicle window
|-
| autoreplace_text
| string
| String for the autoreplace window
|-
| new_engine_text
| string
| String for the "We have invented a new <road type> engine" news message
|-
| powered_roadtype_list
| list of roadtype labels
| Provide a list of road types that road vehicles of this type are powered on, e.g. ["ROAD", "ELRD"]. Note that there is no "compatible_roadtype_list" since there is no difference between "powered" and "compatible" for roadtypes
|-
| roadtype_flags
| bitmask(ROADTYPE_FLAG_XXX, ...)
|
;CATENARY
:Enable catenary
;NO_LEVEL_CROSSING
:Disable level crossings
;NO_HOUSES
:Disallows house construction
;HIDDEN
:Hides the roadtype from players, but remains available to towns
;TOWN_BUILD
:Enables the roadtype to be built by towns, picked by highest speed (defaults to ROAD if no speed limits?)
|-
| construction_cost
| 0 ... 65525
| Per piece of road as multiplier to PR_BUILD_ROAD base cost. Default cost factors are 8 and 16 for ROAD and ELRD, respectively.
|-
| speed_limit
| 0 ... 65525 km/h (speed units)
| A speed limit of 0 means unlimited speed
|-
| map_colour
| 0 ... 255
| Entry in the colour palette.
|-
| requires_roadtype_list
| list of roadtype labels
| List of road types that need to be available to the company of the player for this road type to be introduced at (or after) the introduction date. This limit does not apply when the road type is introduced by the introduction of a vehicle.
|-
| introduces_roadtype_list
| list of roadtype labels
| List of road types that get introduced when this road type is introduced. For example, to make sure that when a fast road type is introduced the slow variant exists.
|-
| sort_order
| 0 ... 255
| Number which defines the sort order among road types. If this entry is not defined, it gets assigned sort order n*10+7 for the n-th roadtype.
|-
| maintenance_cost
| 0 ... 255
| Maintenance cost factor for each piece of road of this roadtype. Default cost factors are 16 and 24 for ROAD and ELRD, respectively.
|-
| alternative_roadtype_list
| list of roadtype labels
| List of road types which this road type will act as fallback for, if the corresponding road type is not defined separately
|}

===Sort order===

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

{| class="t"
! Value
! Meaning
|-
| 07
| normal road
|-
| 17
| electrified road
|-
| n7
| roadtype #n
|}

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

==Roadtype variables==

{| class="wikitable sortable"
! name
! value range
! comment
|-
| terrain_type
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|
|-
| enhanced_tunnels
| 0
| Reserved for future use, always returns 0 in OpenTTD. Should custom tunnel entrances be implemented, other values than 0 might be returned
|-
| level_crossing_status
| LEVEL_CROSSING_CLOSED, LEVEL_CROSSING_OPEN
|
|-
| build_date
| 0 .. 5000000
| for depots only: build date of the depot in days since 0
|-
| town_zone
| [[NML:List of town zones|town zone]]
| Town zone of the tile
|-
| random_bits
|
| 2 pseudo random bits, based on tile location
| -
| railtype
| Entry from railtype translation table or RAILTYPE_OTHER_GRF or RAILTYPE_NO_ROAD
| railtype present on the tile
|-
| roadtype
| Entry from roadtype translation table or ROADTYPE_OTHER_GRF or ROADTYPE_NO_ROAD
| roadtype present on the tile
|-
| tramtype
| Entry from tramtype translation table or TRAMTYPE_OTHER_GRF or TRAMTYPE_NO_ROAD
| tramtype present on the tile
|-
|}

==Roadtype callbacks==

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

{| class="wikitable sortable"
! callbacks
! number of sprites
! meaning
|-
| gui
| 12
| 6 gui icons, 6 cursors
|-
| track_overlay<ref name=leftout>Either all or none of these sprites should be provided.</ref>
| 19
| 11 roadbit combinations, 4 slopes, and 4 dead ends. These sprites are optional for roadtypes.
|-
| underlay<ref name=leftout />
| 19
| 11 roadbit combinations, 4 slopes, and 4 dead ends. These sprites are required.
|-
| tunnels<ref name=leftout />
| 4
| {{ottd|13}} and {{nml|0.7.2}} 1 sprite for each direction. Sprite is overlay for road in existing tunnel graphics. The original ground sprite is drawn, then the overlay, then possibly a road vehicle and the original tunnel head is drawn over the top. This keeps compatibility with different landscape types. Sprite order: SW, NW, NE, SE.
|-
| catenary_front
| 29
| 11 roadbit combinations, 4 slopes, 4 dead ends, 4 tunnels, 2 bridge middle, 4 bridge ramps
|-
| catenary_back
| 29
| 11 roadbit combinations, 4 slopes, 4 dead ends, 4 tunnels (unused), 2 bridge middle, 4 bridge ramps
|-
| bridge_surfaces<ref name=leftout />
| 6
| 2 bridge middle, 4 bridge ramps
|-
| depots
| 6
| If not present, the default depot sprites (depending on catenary flag) plus track overlay are drawn.
If present, the depot sprites are expected to include track overlay graphics.

|-
| roadstops
| 4
| Overlays for drive-in road stops
|-
| direction_markings
| 18
| {{ottd|13}} and {{nml|0.7.4}} Overlays for one-way roads: repeat (arrow facing SW, arrow NE, impassable NE-SW, arrow NW, arrow SE, impassable NW-SE) for flat, N corner raised, S corner raised.
|}

<references />
Note that there is no "default" graphics callback.

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

[[File:Nrt_gui.png]]

==== underlay ====

[[File:Nrt_underlay.png]]

==== catenary_front ====

[[File:Nrt_catenary_front.png]]

==== catenary_back ====

[[File:Nrt_catenary_back.png]]

==== depots ====

[[File:Nrt_depot.png]]

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

==== bridge_surfaces ====

[[File:Nrt_bridge.png]]

==== roadstops ====

[[File:Nrt_drivein.png]]


==== direction_markings ====

[[File:Nrt_oneway.png]]

===Example code===

A typical implementation for roadtypes can look like:

<pre style="color:blue">
item(FEAT_ROADTYPES, highway, 0x01) {
property {
label: "HWY_";
name: string(STR_HWY);
menu_text: string(STR_HWY);
build_window_caption: string(STR_BUILD_CAPTION);
autoreplace_text: string(STR_AUTOREPLACE);
new_engine_text: string(STR_NEW_ENGINE);
powered_roadtype_list: ["HWY_","ROAD"]; // Highways are compatible with other roads
roadtype_flags: bitmask(ROADTYPE_FLAG_NO_LEVEL_CROSSING, ROADTYPE_FLAG_NO_HOUSES); // Highways should not have level crossings or houses
construction_cost: 32; // Highways are expensive
speed_limit: 100 km/h;
}
graphics {
underlay: ground_switch_underlay; // defines the usual roads
depots: depot_switch; // defines the depot sprites
bridge_surfaces: bridge_terrain_switch; // defines the overlay drawn over bridges depending on climate
roadstops: roadstops_switch; // defines the look of roadstop pavement
}
}
</pre>

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

NML:Roadtypes

2026-01-03T17:57:28Z

Andythenorth: /* Roadtype variables */ document railtype, roadtype, tramtype variables

{{NMLNavPropVarCB}}

Roadtypes can only be defined in OpenTTD {{ottd|1.10}} and {{nml|0.5}} or later.

==Roadtype IDs==
Roadtypes and Tramtypes share a pool of 63 IDs. Either feature can use as many IDs as needed (i.e. it is not limited to 32 per type), but both features combined are limited to 63 in total. NewGRF-local IDs may freely be chosen, but must be in the 0..62 range. If other roadtype/tramtype GRFs are loaded, it may be that there are not enough slots available. To prevent your entire NewGRF from being deactivated with the 'Attempt to use invalid ID'-error, you can use the following code:

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

== Vehicle and Roadtype availability ==

Vehicle and roadtype availability and compatibility is influenced by multiple properties.
Generally, the vehicle defines which roadtype it is, and the roadtypes define the compatibility between each other.
* A vehicle exists, if its roadtype (road vehicle property <code style="color:green">road_type</code>) is defined. Otherwise the vehicle is disabled.
* When a vehicle is introduced, it always introduces its roadtype (road vehicle property <code style="color:green">road_type</code>).
* A roadtype is introduced, if at least one of the following conditions is met:
** A vehicle is introduced, that references the roadtype (road vehicle property <code style="color:green">road_type</code>).
** Another roadtype is introduced, that references the roadtype via the introduced roadtype list (roadtype property <code style="color:green">introduces_roadtype_list</code>).
** The introduction date (roadtype property <code style="color:green">introduction_date</code>) is passed and all required roadtypes (roadtype property <code style="color:green">requires_roadtype_list </code>) are available.

Via roadtype property <code style="color:green">powered_roadtype_list</code> multiple roadtypes can be defined, which shall be considered equivalent to a roadtype.
This affects the interpretation of road vehicle property <code style="color:green">road_type</code>. If road vehicle property <code style="color:green">road_type</code> references an undefined roadtype, then
roadtype property <code style="color:green">powered_roadtype_list</code> is checked for all defined roadtypes, whether the vehicle can be reassigned to some other roadtype.
Otherwise the vehicle is disabled.

==Roadtype properties==

{| class="wikitable sortable"
! property
! value range
! comment
|-
| label
| 4-byte string
| names of default road types: "ROAD" and "ELRD". See the [[RoadtypeLabels|List of roadtype labels]] in the NewGRF Specs for currently defined custom labels.
|-
| introduction_date
| date(yyyy,mm,dd)
| Valid range for yyyy is 0 ... 5000000.
|-
| name
| string
| Name of this roadtype
|-
| toolbar_caption
| string
| Caption of the build road toolbar
|-
| menu_text
| string
| Shown in the dropdown menu for all roadtypes
|-
| build_window_caption
| string
| Caption of the build vehicle window
|-
| autoreplace_text
| string
| String for the autoreplace window
|-
| new_engine_text
| string
| String for the "We have invented a new <road type> engine" news message
|-
| powered_roadtype_list
| list of roadtype labels
| Provide a list of road types that road vehicles of this type are powered on, e.g. ["ROAD", "ELRD"]. Note that there is no "compatible_roadtype_list" since there is no difference between "powered" and "compatible" for roadtypes
|-
| roadtype_flags
| bitmask(ROADTYPE_FLAG_XXX, ...)
|
;CATENARY
:Enable catenary
;NO_LEVEL_CROSSING
:Disable level crossings
;NO_HOUSES
:Disallows house construction
;HIDDEN
:Hides the roadtype from players, but remains available to towns
;TOWN_BUILD
:Enables the roadtype to be built by towns, picked by highest speed (defaults to ROAD if no speed limits?)
|-
| construction_cost
| 0 ... 65525
| Per piece of road as multiplier to PR_BUILD_ROAD base cost. Default cost factors are 8 and 16 for ROAD and ELRD, respectively.
|-
| speed_limit
| 0 ... 65525 km/h (speed units)
| A speed limit of 0 means unlimited speed
|-
| map_colour
| 0 ... 255
| Entry in the colour palette.
|-
| requires_roadtype_list
| list of roadtype labels
| List of road types that need to be available to the company of the player for this road type to be introduced at (or after) the introduction date. This limit does not apply when the road type is introduced by the introduction of a vehicle.
|-
| introduces_roadtype_list
| list of roadtype labels
| List of road types that get introduced when this road type is introduced. For example, to make sure that when a fast road type is introduced the slow variant exists.
|-
| sort_order
| 0 ... 255
| Number which defines the sort order among road types. If this entry is not defined, it gets assigned sort order n*10+7 for the n-th roadtype.
|-
| maintenance_cost
| 0 ... 255
| Maintenance cost factor for each piece of road of this roadtype. Default cost factors are 16 and 24 for ROAD and ELRD, respectively.
|-
| alternative_roadtype_list
| list of roadtype labels
| List of road types which this road type will act as fallback for, if the corresponding road type is not defined separately
|}

===Sort order===

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

{| class="t"
! Value
! Meaning
|-
| 07
| normal road
|-
| 17
| electrified road
|-
| n7
| roadtype #n
|}

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

==Roadtype variables==

{| class="wikitable sortable"
! name
! value range
! comment
|-
| terrain_type
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|
|-
| enhanced_tunnels
| 0
| Reserved for future use, always returns 0 in OpenTTD. Should custom tunnel entrances be implemented, other values than 0 might be returned
|-
| level_crossing_status
| LEVEL_CROSSING_CLOSED, LEVEL_CROSSING_OPEN
|
|-
| build_date
| 0 .. 5000000
| for depots only: build date of the depot in days since 0
|-
| town_zone
| [[NML:List of town zones|town zone]]
| Town zone of the tile
|-
| random_bits
|
| 2 pseudo random bits, based on tile location
| railtype
| Entry from railtype translation table or RAILTYPE_OTHER_GRF or RAILTYPE_NO_ROAD
| railtype present on the tile
|-
| roadtype
| Entry from roadtype translation table or ROADTYPE_OTHER_GRF or ROADTYPE_NO_ROAD
| roadtype present on the tile
|-
| tramtype
| Entry from tramtype translation table or TRAMTYPE_OTHER_GRF or TRAMTYPE_NO_ROAD
| tramtype present on the tile
|-
|}

==Roadtype callbacks==

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

{| class="wikitable sortable"
! callbacks
! number of sprites
! meaning
|-
| gui
| 12
| 6 gui icons, 6 cursors
|-
| track_overlay<ref name=leftout>Either all or none of these sprites should be provided.</ref>
| 19
| 11 roadbit combinations, 4 slopes, and 4 dead ends. These sprites are optional for roadtypes.
|-
| underlay<ref name=leftout />
| 19
| 11 roadbit combinations, 4 slopes, and 4 dead ends. These sprites are required.
|-
| tunnels<ref name=leftout />
| 4
| {{ottd|13}} and {{nml|0.7.2}} 1 sprite for each direction. Sprite is overlay for road in existing tunnel graphics. The original ground sprite is drawn, then the overlay, then possibly a road vehicle and the original tunnel head is drawn over the top. This keeps compatibility with different landscape types. Sprite order: SW, NW, NE, SE.
|-
| catenary_front
| 29
| 11 roadbit combinations, 4 slopes, 4 dead ends, 4 tunnels, 2 bridge middle, 4 bridge ramps
|-
| catenary_back
| 29
| 11 roadbit combinations, 4 slopes, 4 dead ends, 4 tunnels (unused), 2 bridge middle, 4 bridge ramps
|-
| bridge_surfaces<ref name=leftout />
| 6
| 2 bridge middle, 4 bridge ramps
|-
| depots
| 6
| If not present, the default depot sprites (depending on catenary flag) plus track overlay are drawn.
If present, the depot sprites are expected to include track overlay graphics.

|-
| roadstops
| 4
| Overlays for drive-in road stops
|-
| direction_markings
| 18
| {{ottd|13}} and {{nml|0.7.4}} Overlays for one-way roads: repeat (arrow facing SW, arrow NE, impassable NE-SW, arrow NW, arrow SE, impassable NW-SE) for flat, N corner raised, S corner raised.
|}

<references />
Note that there is no "default" graphics callback.

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

[[File:Nrt_gui.png]]

==== underlay ====

[[File:Nrt_underlay.png]]

==== catenary_front ====

[[File:Nrt_catenary_front.png]]

==== catenary_back ====

[[File:Nrt_catenary_back.png]]

==== depots ====

[[File:Nrt_depot.png]]

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

==== bridge_surfaces ====

[[File:Nrt_bridge.png]]

==== roadstops ====

[[File:Nrt_drivein.png]]


==== direction_markings ====

[[File:Nrt_oneway.png]]

===Example code===

A typical implementation for roadtypes can look like:

<pre style="color:blue">
item(FEAT_ROADTYPES, highway, 0x01) {
property {
label: "HWY_";
name: string(STR_HWY);
menu_text: string(STR_HWY);
build_window_caption: string(STR_BUILD_CAPTION);
autoreplace_text: string(STR_AUTOREPLACE);
new_engine_text: string(STR_NEW_ENGINE);
powered_roadtype_list: ["HWY_","ROAD"]; // Highways are compatible with other roads
roadtype_flags: bitmask(ROADTYPE_FLAG_NO_LEVEL_CROSSING, ROADTYPE_FLAG_NO_HOUSES); // Highways should not have level crossings or houses
construction_cost: 32; // Highways are expensive
speed_limit: 100 km/h;
}
graphics {
underlay: ground_switch_underlay; // defines the usual roads
depots: depot_switch; // defines the depot sprites
bridge_surfaces: bridge_terrain_switch; // defines the overlay drawn over bridges depending on climate
roadstops: roadstops_switch; // defines the look of roadstop pavement
}
}
</pre>

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

NML:Railtypes

2026-01-03T17:56:36Z

Andythenorth: /* Railtype variables */ document railtype, roadtype, tramtype

{{NMLNavPropVarCB}}

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

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

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

== Vehicle and Railtype availability ==

Vehicle and railtype availability and compatibility is influenced by multiple properties.
Generally, the vehicle defines which railtype it is, and the railtypes define the compatibility between each other.
* A vehicle exists, if its railtype (train property <code style="color:green">track_type</code>) is defined. Otherwise the vehicle is disabled.
* When a vehicle is introduced, it always introduces its railtype (train property <code style="color:green">track_type</code>).
* A railtype is introduced, if at least one of the following conditions is met:
** A vehicle is introduced, that references the railtype (train property <code style="color:green">track_type</code>).
** Another railtype is introduced, that references the railtype via the introduced railtype list (railtype propery <code style="color:green">introduces_railtype_list</code>).
** The introduction date (railtype property <code style="color:green">introduction_date</code>) is passed and all required railtypes (railtype property <code style="color:green">requires_railtype_list </code>) are available.

Via railtype property <code style="color:green">compatible_railtype_list</code> multiple railtypes can be defined, which shall be considered equivalent to a railtype.
This affects the interpretation of train property <code style="color:green">track_type</code>. If train property <code style="color:green">track_type</code> references an undefined railtype, then
railtype property <code style="color:green">compatible_railtype_list</code> is checked for all defined railtypes, whether the vehicle can be reassigned to some other railtype.
Otherwise the vehicle is disabled. However note also that <code style="color:green">alternative_railtype_list</code> provides an alternative/complementary approach to handling undefined railtypes.

Note that when routing trains onto railtypes, the compatibility is only evaluated for the lead engine of a consist. This means that trains will run on incompatible rail types if they are in a consist where the lead engine is compatible with the rail type. This applies to both engines and wagons.

==Railtype properties==

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

===Sort order===

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

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

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

===Base speeds for curves===

The base speeds relevant for the curve_speed_multiplier are:

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

==Railtype variables==

{| class="wikitable sortable"
! name
! value range
! comment
|-
| terrain_type
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|
|-
| enhanced_tunnels
| 0
| Reserved for future use, always returns 0 in OpenTTD. Should custom tunnel entrances be implemented, other values than 0 might be returned
|-
| level_crossing_status
| LEVEL_CROSSING_CLOSED, LEVEL_CROSSING_OPEN
|
|-
| build_date
| 0 .. 5000000
| for depots only: build date of the depot in days since 0
|-
| town_zone
| [[NML:List of town zones|town zone]]
| Town zone of the tile. (Only available for level crossings and depots.)
|-
| random_bits
|
| 2 pseudo-random bits, based on tile location
|-
| railtype
| Entry from railtype translation table or RAILTYPE_OTHER_GRF or RAILTYPE_NO_ROAD
| railtype present on the tile
|-
| roadtype
| Entry from roadtype translation table or ROADTYPE_OTHER_GRF or ROADTYPE_NO_ROAD
| roadtype present on the tile
|-
| tramtype
| Entry from tramtype translation table or TRAMTYPE_OTHER_GRF or TRAMTYPE_NO_ROAD
| tramtype present on the tile
|-
|}

==Railtype callbacks==

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

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

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

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

[[File:railtype_gui.png]]

==== track_overlay ====

[[File:railtype_overlay.png]]

==== underlay ====

[[File:railtype_underlay.png]]

==== level_crossings ====

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

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

[[File:railtype_levelcrossing.png]]

==== depots ====

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

==== fences ====

[[File:railtype_fences.png]]

{{ottdp|1.6|no|ottdrev=r27343}} Since OpenTTD r27343 there is also a 16 sprites version, this allows to use different sprites resp. offsets for the fences on either track side.

{| |-
! Sprite number !! Tile slope !! Track bit !! Fence position !! Version
|-
| 0 || flat || X || NW || {{ottdp|1.0|no|ottdrev=r19056}}
|-
| 1 || flat || Y || NE || {{ottdp|1.0|no|ottdrev=r19056}}
|-
| 2 || flat || left || E || {{ottdp|1.0|no|ottdrev=r19056}}
|-
| 3 || flat || upper || S || {{ottdp|1.0|no|ottdrev=r19056}}
|-
| 4 || SW || X || NW || {{ottdp|1.0|no|ottdrev=r19056}}
|-
| 5 || SE || Y || NE || {{ottdp|1.0|no|ottdrev=r19056}}
|-
| 6 || NE || X || NW || {{ottdp|1.0|no|ottdrev=r19056}}
|-
| 7 || NW || Y || NE || {{ottdp|1.0|no|ottdrev=r19056}}
|-
| 8 || flat || X || SE || {{ottdp|1.6|no|ottdrev=r27343}}
|-
| 9 || flat || Y || SW || {{ottdp|1.6|no|ottdrev=r27343}}
|-
| 10 || flat || left || W || {{ottdp|1.6|no|ottdrev=r27343}}
|-
| 11 || flat || upper || N || {{ottdp|1.6|no|ottdrev=r27343}}
|-
| 12 || SW || X || SE || {{ottdp|1.6|no|ottdrev=r27343}}
|-
| 13 || SE || Y || SW || {{ottdp|1.6|no|ottdrev=r27343}}
|-
| 14 || NE || X || SE || {{ottdp|1.6|no|ottdrev=r27343}}
|-
| 15 || NW || Y || SW || {{ottdp|1.6|no|ottdrev=r27343}}
|}

==== tunnel_overlay ====

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

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

Illustration: [[File:RailtypeTunnelExample.png]]

==== signals ====

This callback can be used to supply custom signal graphics.

The resulting sprite set must consist of 8 sprites, corresponding to the following signal directions: SW-facing, NE-facing, NW-facing, SE-facing, E-facing, W-facing, S-facing, N-facing. If resolving fails or results in an empty sprite group, the matching base set sprite will be used instead.

Variable <code style:darkgreen>extra_callback_info2</code> contains the state, variant and type of the signal. Use the builtin function <code style:darkgreen>getbits()</code> in the following fashion to access the information:
<ul><li>
Signal state: <code style:darkgreen>getbits(extra_callback_info2, 0, 8)</code>:
{| |-
! Result !! Meaning
|-
| 00 || Red signal
|-
| 01 || Green signal
|-
| all other values || Reserved
|}
</li><li>
Signal variant: <code style:darkgreen>getbits(extra_callback_info2, 8, 8)</code>:
{| |-
! Result !! Meaning
|-
| 00 || Light (electric) signal
|-
| 01 || Semaphore
|-
| all other values || Reserved
|}
</li><li>
Signal type: <code style:darkgreen>getbits(extra_callback_info2, 16, 8)</code>:
{| |-
! Result !! Meaning
|-
| 00 || Normal block signal
|-
| 01 || Entry pre-signal
|-
| 02 || Exit pre-signal
|-
| 03 || Combo pre-signal
|-
| 04 || Two-way path signal
|-
| 05 || One-way path signal
|-
| all other values || Reserved
|}
</li></ul>
Variable <code style:darkgreen>extra_callback_info1</code> contains the drawing context.
<ul><li>
<code style:darkgreen>getbits(extra_callback_info1, 0, 8)</code>:
{| |-
! Result !! Meaning
|-
| 0 || Signal is drawn in a viewport, i.e. on the map.
|-
| 0x10 || Signal is drawn in the signal GUI. The returned sprite set must still have 8 sprites, but OpenTTD will only use the 7th sprite, so all other sprites can be empty.
|-
| all other values || Reserved
|}
</li></ul>

====Precombined overlay sprites====

[[File:Rails_combined.png]]

===Example code===

A typical implementation for railtypes can look like:

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

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

NML:Builtin functions

2026-01-03T17:38:31Z

Andythenorth: Undo revision 5136 by Andythenorth (talk)

{{NMLNavExpressions}}

Available builtin functions are

{| class="wikitable sortable"
! Function
! Description
|-
| min(''v1'', ''v2'')
| Return the smallest value
|-
| max(''v1'', ''v2'')
| Return the biggest value
|-
| date(''year'', ''month'', ''day'')
| If all values are constants, returns the number of days since year 0. If the year is a variable, the month and day should be 1.
|-
| day_of_year(''month'', ''day'')
| Return the day of the year since January 1st. Both values must be compile-time constants.
|-
| bitmask(''bitpos1'', ...)
| Compose an integer by switching the bits at the given positions on (indexed starting at 1).
|-
| STORE_TEMP(''value'', ''address'')
| Store value in temporary storage. Temporary storage holds data until the final "return" of the current switch-chain of the current callback. Addresses 0..127 are available for the GRF to use. Addresses 0x100 and above have special purposes, which are described where they are used.
|-
| STORE_PERM(''value'', ''address'')
| Store value in permanent storage (industries, airports, towns only). Addresses {{ottd|<1.9}} 0..15, {{ottd|1.9}} 0..255 are available for the GRF to use. Note that accessing permanent town registers thrashes the contents of temporary register 0x100.
|-
| LOAD_TEMP(''address'')
| Get value from temporary storage. Addresses 0..127 are available for the GRF to use.
|-
| LOAD_PERM(''address [, grfid]'')
| Get value from permanent storage (industries, airports, towns only). For towns only, specifying a grfid (4-byte string, optional) allows reading the storage of other grfs. Note that accessing permanent town registers thrashes the contents of temporary register 0x100.
|-
| hasbit(''value'', ''bit_num'')
| Test whether a bit in a value is on
|-
| getbits(''value'', ''first'', ''amount'')
| {{nml|0.4.1}} Extract some bits from a value. Result is (value >> first) & (1 << amount - 1)
|-
| {{ottd|≤1.11}} version_openttd(''major'', ''minor'', ''revision''[, ''build'']) {{ottd|≥12}} version_openttd(''major'', ''minor'')
| Return the constant representing an OpenTTD version, for example
* OpenTTD 1.4.0: "version_openttd(1, 4, 0)"
* OpenTTD 13.0: "version_openttd(13, 0)"
{{ottd|≤1.8}} Old versions before OpenTTD 1.9 also could check for specific SVN revisions. This is no longer available.
|-
| cargotype_available(''cargotype'')
| Check if a certain cargo type is available in this game. ''cargotype'' must be a literal string of length 4.
|-
| railtype_available(''railtype'')
| Check if a railtype is available in this game. ''railtype'' must be a literal string of length 4.
|-
| roadtype_available(''roadtype'')
| Check if a roadtype is available in this game. ''roadtype'' must be a literal string of length 4.
|-
| tramtype_available(''tramtype_available'')
| Check if a tramtype_available is available in this game. ''tramtype_available'' must be a literal string of length 4.
|-
| grf_current_status(''grfid[, mask]'')
| 1 if the given GRF is currently active 0, otherwise. If ''mask'' is set, only the bits set in the mask will be tested. Both parameters must be a literal string of length 4.
|-
| grf_future_status(''grfid[, mask]'')
| Same as above, but tests whether the grf will become active instead of whether it's currently active.
|-
| grf_order_behind(''grfid[, mask]'')
| Same as above, but tests whether current grf will become active in the order behind the referenced grf.
|-
| create_effect(''effect_sprite'', ''l_x_offset'', ''t_y_offset'', ''z_offset'')
| Helper function for the vehicle callback 'create_effect'.
* ''effect_sprite'': Sprite for the effect. One of EFFECT_SPRITE_[NONE|STEAM|DIESEL|ELECTRIC|AIRCRAFT_BREAKDOWN_SMOKE].
* ''l_x_offset'': Longitudinal or X position of the effect, depending on callback result CB_RESULT_CREATE_EFFECT_NO_ROTATION.
* ''t_y_offset'': Transversal or Y position of the effect, depending on callback result CB_RESULT_CREATE_EFFECT_NO_ROTATION.
* ''z_offset'': Z position of the effect.
|-
| visual_effect_and_powered(''effect'', ''offset'', ''powered'')
| Helper function for the train property and callback visual_effect_and_powered.
|-
| visual_effect(''effect'', ''offset'')
| Helper function for the road vehicle and ship property and callback visual_effect.
|-
| str2number(''4-byte long string'')
| Interpret the given string as a dword and return the value as integer.
|-
| cargotype(''4-byte long string'')
| Return the index of the given cargo type in the cargo translation table.
|-
| railtype(''4-byte long string'')
| Return the index of the given railtype in the railtype translation table.
|-
| roadtype(''4-byte long string'')
| Return the index of the given roadtype in the roadtype translation table.
|-
| tramtype(''4-byte long string'')
| Return the index of the given tramtype in the tramtype translation table.
|-
| reserve_sprites(''number of sprites'')
|
Reserve a number of sprites in the TTD sprite range. This is needed if you want to use your own recolour sprites. Example:
<pre style="color:blue">
param[10] = reserve_sprites(1);
replace(param[10]) {
recolour_sprite {
// your colour remap.
}
}
spritelayout xyz {
building {
...
recolour: param[10];
}
}
</pre>
|-
| int(''v1'')
| Converts v1 to an int. This is done by cutting off everything after the decimal point, i.e. rounding toward zero.
|-
| round(''v1'')
| {{nml|0.5.4}} Converts v1 to an int. This is done by rounding towards the closest integer.
|-
| abs(''v1'')
| Return the absolute value of v1.
|-
| acos / asin / atan / cos / sin / tan
| Standard trigonometric functions.
|-
| sqrt
| {{nml|0.5.4}} Square root.
|-
| CMP(''param1, param2'')
| Compares param1 and param2 (considering them as signed values). Returns CMP_LESS if param1 is less than param2, CMP_EQUAL if they are equal and CMP_GREATER if param1 is greater than param2.
|-
| UCMP(''param1, param2'')
| Compares param1 and param2 (considering them as unsigned values). Returns CMP_LESS if param1 is less than param2, CMP_EQUAL if they are equal and CMP_GREATER if param1 is greater than param2.
|-
| rotate(''value, amount'')
| Rotates ''value'' to the right ''amount'' steps. This is always a 32 bits rotation.
|-
| sound(''soundfile[, volume]'')
| Import sound from .wav-file ''soundfile'' into the grf file and return its numeric ID. Including a file multiple times will not cause it to be duplicated. Loaded sound files must be in WAV format, PCM encoding:
* mono
* 8-bit or {{ottdp|1.0|no}} 16-bit
* 11025 Hz, 22050 Hz or 44100 Hz.
''volume'' is in the [0, 100] range, the default value (if not set) is 100.
|-
| import_sound(''grfid, id[, volume]'')
| Import sound from a different grf file. ''grfid'' refers to the grf-file to import the sound from. ''id'' is the zero-based internal ID of the sound within the other grf-file. ''volume'' is in the [0, 100] range, the default value (if not set) is 100.
|-
| relative_coord(''x, y'')
| Returns the coordinates in ''0xYYXX'' format. x and y must be in the [0, 255] range.
|-
| num_corners_raised(''slope'')
|
Returns the number of corners raised in a slope. Return value is 0 .. 3 for normal slopes and 4 for steep ones. See also [[NML:List of tile slopes|here]] for more information about slopes. Using this on values that are not slopes results in undefined behaviour.
|-
| slope_to_sprite_offset(''slope'')
|
Returns the sprite offset corresponding to a given slope. Return value is in range 0 .. 18. See also [[NML:List of tile slopes|here]] for more information about slopes. The section on [[NML:Spritelayout|spritelayouts]] contains some more information one possible uses, as well as an example. Using this on values that are not slopes results in undefined behaviour.
|-
| palette_1cc(''colour'')
|
Returns the 1cc palette for the given company colour, see [[NML:List_of_default_colour_translation_palettes#Company colour helper functions|here]] for more info.
|-
| palette_2cc(''colour1'', ''colour2'')
|
Returns the 2cc palette for the given first and second company colour, see [[NML:List_of_default_colour_translation_palettes#Company colour helper functions|here]] for more info.
|-
| vehicle_curv_info(''prev_cur'', ''cur_next'')
| Returns the curvature state of a vehicle, given the direction differences between the (previous-current) and (current-next) vehicle pairs. For use with the vehicle variable <code style="color:darkgreen">curv_info</code>.
|-
| format_string(''format'', args)
| Use the python string formatting functions to create a literal string. Keep in mind that the output is a literal string which cannot be used by string(). This function can however be used to create filenames.
|-
| industry_type(''ind_type'', ''ID'')
| Defines either an old industry (using the global ID) or a new industry from your grf (using the grf-local ID). Used only by ''conflicting_ind_types'' on [[NML:Industries]].
''ind_type'' must be either <code style="color:darkgreen">IND_TYPE_OLD</code> or <code style="color:darkgreen">IND_TYPE_NEW</code>. ''ID'' must be in the [0, 127] range.
|-
| accept_cargo(''cargotype'', produce_cargo(''cargotype'', ''factor'')...) produce_cargo(''cargotype'', ''amount'')
| Helper functions used to set industry production in the [[NML:Industries#Cargo_types_array|''cargo_types'' property]].
|}

NML:Builtin functions

2026-01-03T17:38:06Z

Andythenorth: Undo revision 5137 by Andythenorth (talk)

{{NMLNavExpressions}}

Available builtin functions are

{| class="wikitable sortable"
! Function
! Description
|-
| min(''v1'', ''v2'')
| Return the smallest value
|-
| max(''v1'', ''v2'')
| Return the biggest value
|-
| date(''year'', ''month'', ''day'')
| If all values are constants, returns the number of days since year 0. If the year is a variable, the month and day should be 1.
|-
| day_of_year(''month'', ''day'')
| Return the day of the year since January 1st. Both values must be compile-time constants.
|-
| bitmask(''bitpos1'', ...)
| Compose an integer by switching the bits at the given positions on (indexed starting at 1).
|-
| STORE_TEMP(''value'', ''address'')
| Store value in temporary storage. Temporary storage holds data until the final "return" of the current switch-chain of the current callback. Addresses 0..127 are available for the GRF to use. Addresses 0x100 and above have special purposes, which are described where they are used.
|-
| STORE_PERM(''value'', ''address'')
| Store value in permanent storage (industries, airports, towns only). Addresses {{ottd|<1.9}} 0..15, {{ottd|1.9}} 0..255 are available for the GRF to use. Note that accessing permanent town registers thrashes the contents of temporary register 0x100.
|-
| LOAD_TEMP(''address'')
| Get value from temporary storage. Addresses 0..127 are available for the GRF to use.
|-
| LOAD_PERM(''address [, grfid]'')
| Get value from permanent storage (industries, airports, towns only). For towns only, specifying a grfid (4-byte string, optional) allows reading the storage of other grfs. Note that accessing permanent town registers thrashes the contents of temporary register 0x100.
|-
| hasbit(''value'', ''bit_num'')
| Test whether a bit in a value is on
|-
| getbits(''value'', ''first'', ''amount'')
| {{nml|0.4.1}} Extract some bits from a value. Result is (value >> first) & (1 << amount - 1)
|-
| {{ottd|≤1.11}} version_openttd(''major'', ''minor'', ''revision''[, ''build'']) {{ottd|≥12}} version_openttd(''major'', ''minor'')
| Return the constant representing an OpenTTD version, for example
* OpenTTD 1.4.0: "version_openttd(1, 4, 0)"
* OpenTTD 13.0: "version_openttd(13, 0)"
{{ottd|≤1.8}} Old versions before OpenTTD 1.9 also could check for specific SVN revisions. This is no longer available.
|-
| cargotype_available(''cargotype'')
| Check if a certain cargo type is available in this game. ''cargotype'' must be a literal string of length 4.
|-
| railtype_available(''railtype'')
| Check if a railtype is available in this game. ''railtype'' must be a literal string of length 4.
|-
| roadtype_available(''roadtype'')
| Check if a roadtype is available in this game. ''roadtype'' must be a literal string of length 4.
|-
| tramtype_available(''tramtype_available'')
| Check if a tramtype_available is available in this game. ''tramtype_available'' must be a literal string of length 4.
|-
| grf_current_status(''grfid[, mask]'')
| 1 if the given GRF is currently active 0, otherwise. If ''mask'' is set, only the bits set in the mask will be tested. Both parameters must be a literal string of length 4.
|-
| grf_future_status(''grfid[, mask]'')
| Same as above, but tests whether the grf will become active instead of whether it's currently active.
|-
| grf_order_behind(''grfid[, mask]'')
| Same as above, but tests whether current grf will become active in the order behind the referenced grf.
|-
| create_effect(''effect_sprite'', ''l_x_offset'', ''t_y_offset'', ''z_offset'')
| Helper function for the vehicle callback 'create_effect'.
* ''effect_sprite'': Sprite for the effect. One of EFFECT_SPRITE_[NONE|STEAM|DIESEL|ELECTRIC|AIRCRAFT_BREAKDOWN_SMOKE].
* ''l_x_offset'': Longitudinal or X position of the effect, depending on callback result CB_RESULT_CREATE_EFFECT_NO_ROTATION.
* ''t_y_offset'': Transversal or Y position of the effect, depending on callback result CB_RESULT_CREATE_EFFECT_NO_ROTATION.
* ''z_offset'': Z position of the effect.
|-
| visual_effect_and_powered(''effect'', ''offset'', ''powered'')
| Helper function for the train property and callback visual_effect_and_powered.
|-
| visual_effect(''effect'', ''offset'')
| Helper function for the road vehicle and ship property and callback visual_effect.
|-
| str2number(''4-byte long string'')
| Interpret the given string as a dword and return the value as integer.
|-
| cargotype(''4-byte long string'')
| Return the index of the given cargo type in the cargo translation table.
|-
| railtype(''4-byte long string'')
| Return the index of the given railtype in the railtype translation table.
|-
| roadtype(''4-byte long string'')
| Return the index of the given roadtype in the roadtype translation table.
|-
| tramtype(''4-byte long string'')
| Return the index of the given tramtype in the tramtype translation table.
|-
| reserve_sprites(''number of sprites'')
|
Reserve a number of sprites in the TTD sprite range. This is needed if you want to use your own recolour sprites. Example:
<pre style="color:blue">
param[10] = reserve_sprites(1);
replace(param[10]) {
recolour_sprite {
// your colour remap.
}
}
spritelayout xyz {
building {
...
recolour: param[10];
}
}
</pre>
|-
| int(''v1'')
| Converts v1 to an int. This is done by cutting off everything after the decimal point, i.e. rounding toward zero.
|-
| round(''v1'')
| {{nml|0.5.4}} Converts v1 to an int. This is done by rounding towards the closest integer.
|-
| abs(''v1'')
| Return the absolute value of v1.
|-
| acos / asin / atan / cos / sin / tan
| Standard trigonometric functions.
|-
| sqrt
| {{nml|0.5.4}} Square root.
|-
| CMP(''param1, param2'')
| Compares param1 and param2 (considering them as signed values). Returns CMP_LESS if param1 is less than param2, CMP_EQUAL if they are equal and CMP_GREATER if param1 is greater than param2.
|-
| UCMP(''param1, param2'')
| Compares param1 and param2 (considering them as unsigned values). Returns CMP_LESS if param1 is less than param2, CMP_EQUAL if they are equal and CMP_GREATER if param1 is greater than param2.
|-
| rotate(''value, amount'')
| Rotates ''value'' to the right ''amount'' steps. This is always a 32 bits rotation.
|-
| sound(''soundfile[, volume]'')
| Import sound from .wav-file ''soundfile'' into the grf file and return its numeric ID. Including a file multiple times will not cause it to be duplicated. Loaded sound files can be in WAV format, PCM encoding:
* mono
* 8-bit or {{ottdp|1.0|no}} 16-bit
* 11025 Hz, 22050 Hz or 44100 Hz.
''volume'' is in the [0, 100] range, the default value (if not set) is 100.
{{ottdp|15}} Since OpenTTD 15, compressed sound effects are supported in Ogg Opus format, with no restriction on quality, bit depth or sample rate.
|-
| import_sound(''grfid, id[, volume]'')
| Import sound from a different grf file. ''grfid'' refers to the grf-file to import the sound from. ''id'' is the zero-based internal ID of the sound within the other grf-file. ''volume'' is in the [0, 100] range, the default value (if not set) is 100.
|-
| relative_coord(''x, y'')
| Returns the coordinates in ''0xYYXX'' format. x and y must be in the [0, 255] range.
|-
| num_corners_raised(''slope'')
|
Returns the number of corners raised in a slope. Return value is 0 .. 3 for normal slopes and 4 for steep ones. See also [[NML:List of tile slopes|here]] for more information about slopes. Using this on values that are not slopes results in undefined behaviour.
|-
| slope_to_sprite_offset(''slope'')
|
Returns the sprite offset corresponding to a given slope. Return value is in range 0 .. 18. See also [[NML:List of tile slopes|here]] for more information about slopes. The section on [[NML:Spritelayout|spritelayouts]] contains some more information one possible uses, as well as an example. Using this on values that are not slopes results in undefined behaviour.
|-
| palette_1cc(''colour'')
|
Returns the 1cc palette for the given company colour, see [[NML:List_of_default_colour_translation_palettes#Company colour helper functions|here]] for more info.
|-
| palette_2cc(''colour1'', ''colour2'')
|
Returns the 2cc palette for the given first and second company colour, see [[NML:List_of_default_colour_translation_palettes#Company colour helper functions|here]] for more info.
|-
| vehicle_curv_info(''prev_cur'', ''cur_next'')
| Returns the curvature state of a vehicle, given the direction differences between the (previous-current) and (current-next) vehicle pairs. For use with the vehicle variable <code style="color:darkgreen">curv_info</code>.
|-
| format_string(''format'', args)
| Use the python string formatting functions to create a literal string. Keep in mind that the output is a literal string which cannot be used by string(). This function can however be used to create filenames.
|-
| industry_type(''ind_type'', ''ID'')
| Defines either an old industry (using the global ID) or a new industry from your grf (using the grf-local ID). Used only by ''conflicting_ind_types'' on [[NML:Industries]].
''ind_type'' must be either <code style="color:darkgreen">IND_TYPE_OLD</code> or <code style="color:darkgreen">IND_TYPE_NEW</code>. ''ID'' must be in the [0, 127] range.
|-
| accept_cargo(''cargotype'', produce_cargo(''cargotype'', ''factor'')...) produce_cargo(''cargotype'', ''amount'')
| Helper functions used to set industry production in the [[NML:Industries#Cargo_types_array|''cargo_types'' property]].
|}

NML:Builtin functions

2026-01-03T17:37:20Z

Andythenorth:

{{NMLNavExpressions}}

Available builtin functions are

{| class="wikitable sortable"
! Function
! Description
|-
| min(''v1'', ''v2'')
| Return the smallest value
|-
| max(''v1'', ''v2'')
| Return the biggest value
|-
| date(''year'', ''month'', ''day'')
| If all values are constants, returns the number of days since year 0. If the year is a variable, the month and day should be 1.
|-
| day_of_year(''month'', ''day'')
| Return the day of the year since January 1st. Both values must be compile-time constants.
|-
| bitmask(''bitpos1'', ...)
| Compose an integer by switching the bits at the given positions on (indexed starting at 1).
|-
| STORE_TEMP(''value'', ''address'')
| Store value in temporary storage. Temporary storage holds data until the final "return" of the current switch-chain of the current callback. Addresses 0..127 are available for the GRF to use. Addresses 0x100 and above have special purposes, which are described where they are used.
|-
| STORE_PERM(''value'', ''address'')
| Store value in permanent storage (industries, airports, towns only). Addresses {{ottd|<1.9}} 0..15, {{ottd|1.9}} 0..255 are available for the GRF to use. Note that accessing permanent town registers thrashes the contents of temporary register 0x100.
|-
| LOAD_TEMP(''address'')
| Get value from temporary storage. Addresses 0..127 are available for the GRF to use.
|-
| LOAD_PERM(''address [, grfid]'')
| Get value from permanent storage (industries, airports, towns only). For towns only, specifying a grfid (4-byte string, optional) allows reading the storage of other grfs. Note that accessing permanent town registers thrashes the contents of temporary register 0x100.
|-
| hasbit(''value'', ''bit_num'')
| Test whether a bit in a value is on
|-
| getbits(''value'', ''first'', ''amount'')
| {{nml|0.4.1}} Extract some bits from a value. Result is (value >> first) & (1 << amount - 1)
|-
| {{ottd|≤1.11}} version_openttd(''major'', ''minor'', ''revision''[, ''build'']) {{ottd|≥12}} version_openttd(''major'', ''minor'')
| Return the constant representing an OpenTTD version, for example
* OpenTTD 1.4.0: "version_openttd(1, 4, 0)"
* OpenTTD 13.0: "version_openttd(13, 0)"
{{ottd|≤1.8}} Old versions before OpenTTD 1.9 also could check for specific SVN revisions. This is no longer available.
|-
| cargotype_available(''cargotype'')
| Check if a certain cargo type is available in this game. ''cargotype'' must be a literal string of length 4.
|-
| railtype_available(''railtype'')
| Check if a railtype is available in this game. ''railtype'' must be a literal string of length 4.
|-
| roadtype_available(''roadtype'')
| Check if a roadtype is available in this game. ''roadtype'' must be a literal string of length 4.
|-
| tramtype_available(''tramtype_available'')
| Check if a tramtype_available is available in this game. ''tramtype_available'' must be a literal string of length 4.
|-
| grf_current_status(''grfid[, mask]'')
| 1 if the given GRF is currently active 0, otherwise. If ''mask'' is set, only the bits set in the mask will be tested. Both parameters must be a literal string of length 4.
|-
| grf_future_status(''grfid[, mask]'')
| Same as above, but tests whether the grf will become active instead of whether it's currently active.
|-
| grf_order_behind(''grfid[, mask]'')
| Same as above, but tests whether current grf will become active in the order behind the referenced grf.
|-
| create_effect(''effect_sprite'', ''l_x_offset'', ''t_y_offset'', ''z_offset'')
| Helper function for the vehicle callback 'create_effect'.
* ''effect_sprite'': Sprite for the effect. One of EFFECT_SPRITE_[NONE|STEAM|DIESEL|ELECTRIC|AIRCRAFT_BREAKDOWN_SMOKE].
* ''l_x_offset'': Longitudinal or X position of the effect, depending on callback result CB_RESULT_CREATE_EFFECT_NO_ROTATION.
* ''t_y_offset'': Transversal or Y position of the effect, depending on callback result CB_RESULT_CREATE_EFFECT_NO_ROTATION.
* ''z_offset'': Z position of the effect.
|-
| visual_effect_and_powered(''effect'', ''offset'', ''powered'')
| Helper function for the train property and callback visual_effect_and_powered.
|-
| visual_effect(''effect'', ''offset'')
| Helper function for the road vehicle and ship property and callback visual_effect.
|-
| str2number(''4-byte long string'')
| Interpret the given string as a dword and return the value as integer.
|-
| cargotype(''4-byte long string'')
| Return the index of the given cargo type in the cargo translation table.
|-
| railtype(''4-byte long string'')
| Return the index of the given railtype in the railtype translation table.
|-
| roadtype(''4-byte long string'')
| Return the index of the given roadtype in the roadtype translation table.
|-
| tramtype(''4-byte long string'')
| Return the index of the given tramtype in the tramtype translation table.
|-
| reserve_sprites(''number of sprites'')
|
Reserve a number of sprites in the TTD sprite range. This is needed if you want to use your own recolour sprites. Example:
<pre style="color:blue">
param[10] = reserve_sprites(1);
replace(param[10]) {
recolour_sprite {
// your colour remap.
}
}
spritelayout xyz {
building {
...
recolour: param[10];
}
}
</pre>
|-
| int(''v1'')
| Converts v1 to an int. This is done by cutting off everything after the decimal point, i.e. rounding toward zero.
|-
| round(''v1'')
| {{nml|0.5.4}} Converts v1 to an int. This is done by rounding towards the closest integer.
|-
| abs(''v1'')
| Return the absolute value of v1.
|-
| acos / asin / atan / cos / sin / tan
| Standard trigonometric functions.
|-
| sqrt
| {{nml|0.5.4}} Square root.
|-
| CMP(''param1, param2'')
| Compares param1 and param2 (considering them as signed values). Returns CMP_LESS if param1 is less than param2, CMP_EQUAL if they are equal and CMP_GREATER if param1 is greater than param2.
|-
| UCMP(''param1, param2'')
| Compares param1 and param2 (considering them as unsigned values). Returns CMP_LESS if param1 is less than param2, CMP_EQUAL if they are equal and CMP_GREATER if param1 is greater than param2.
|-
| rotate(''value, amount'')
| Rotates ''value'' to the right ''amount'' steps. This is always a 32 bits rotation.
|-
| sound(''soundfile[, volume]'')
| Import sound from .wav-file ''soundfile'' into the grf file and return its numeric ID. Including a file multiple times will not cause it to be duplicated. Loaded sound files can be in WAV format, PCM encoding:
* mono
* 8-bit or {{ottdp|1.0|no}} 16-bit
* 11025 Hz, 22050 Hz or 44100 Hz.
''volume'' is in the [0, 100] range, the default value (if not set) is 100.

{{ottdp|15}} Since OpenTTD 15, compressed sound effects are supported in Ogg Opus format, with no restriction on quality, bit depth or sample rate.
|-
| import_sound(''grfid, id[, volume]'')
| Import sound from a different grf file. ''grfid'' refers to the grf-file to import the sound from. ''id'' is the zero-based internal ID of the sound within the other grf-file. ''volume'' is in the [0, 100] range, the default value (if not set) is 100.
|-
| relative_coord(''x, y'')
| Returns the coordinates in ''0xYYXX'' format. x and y must be in the [0, 255] range.
|-
| num_corners_raised(''slope'')
|
Returns the number of corners raised in a slope. Return value is 0 .. 3 for normal slopes and 4 for steep ones. See also [[NML:List of tile slopes|here]] for more information about slopes. Using this on values that are not slopes results in undefined behaviour.
|-
| slope_to_sprite_offset(''slope'')
|
Returns the sprite offset corresponding to a given slope. Return value is in range 0 .. 18. See also [[NML:List of tile slopes|here]] for more information about slopes. The section on [[NML:Spritelayout|spritelayouts]] contains some more information one possible uses, as well as an example. Using this on values that are not slopes results in undefined behaviour.
|-
| palette_1cc(''colour'')
|
Returns the 1cc palette for the given company colour, see [[NML:List_of_default_colour_translation_palettes#Company colour helper functions|here]] for more info.
|-
| palette_2cc(''colour1'', ''colour2'')
|
Returns the 2cc palette for the given first and second company colour, see [[NML:List_of_default_colour_translation_palettes#Company colour helper functions|here]] for more info.
|-
| vehicle_curv_info(''prev_cur'', ''cur_next'')
| Returns the curvature state of a vehicle, given the direction differences between the (previous-current) and (current-next) vehicle pairs. For use with the vehicle variable <code style="color:darkgreen">curv_info</code>.
|-
| format_string(''format'', args)
| Use the python string formatting functions to create a literal string. Keep in mind that the output is a literal string which cannot be used by string(). This function can however be used to create filenames.
|-
| industry_type(''ind_type'', ''ID'')
| Defines either an old industry (using the global ID) or a new industry from your grf (using the grf-local ID). Used only by ''conflicting_ind_types'' on [[NML:Industries]].
''ind_type'' must be either <code style="color:darkgreen">IND_TYPE_OLD</code> or <code style="color:darkgreen">IND_TYPE_NEW</code>. ''ID'' must be in the [0, 127] range.
|-
| accept_cargo(''cargotype'', produce_cargo(''cargotype'', ''factor'')...) produce_cargo(''cargotype'', ''amount'')
| Helper functions used to set industry production in the [[NML:Industries#Cargo_types_array|''cargo_types'' property]].
|}

NML:Builtin functions

2026-01-03T17:36:50Z

Andythenorth: Note Ogg sound file support

{{NMLNavExpressions}}

Available builtin functions are

{| class="wikitable sortable"
! Function
! Description
|-
| min(''v1'', ''v2'')
| Return the smallest value
|-
| max(''v1'', ''v2'')
| Return the biggest value
|-
| date(''year'', ''month'', ''day'')
| If all values are constants, returns the number of days since year 0. If the year is a variable, the month and day should be 1.
|-
| day_of_year(''month'', ''day'')
| Return the day of the year since January 1st. Both values must be compile-time constants.
|-
| bitmask(''bitpos1'', ...)
| Compose an integer by switching the bits at the given positions on (indexed starting at 1).
|-
| STORE_TEMP(''value'', ''address'')
| Store value in temporary storage. Temporary storage holds data until the final "return" of the current switch-chain of the current callback. Addresses 0..127 are available for the GRF to use. Addresses 0x100 and above have special purposes, which are described where they are used.
|-
| STORE_PERM(''value'', ''address'')
| Store value in permanent storage (industries, airports, towns only). Addresses {{ottd|<1.9}} 0..15, {{ottd|1.9}} 0..255 are available for the GRF to use. Note that accessing permanent town registers thrashes the contents of temporary register 0x100.
|-
| LOAD_TEMP(''address'')
| Get value from temporary storage. Addresses 0..127 are available for the GRF to use.
|-
| LOAD_PERM(''address [, grfid]'')
| Get value from permanent storage (industries, airports, towns only). For towns only, specifying a grfid (4-byte string, optional) allows reading the storage of other grfs. Note that accessing permanent town registers thrashes the contents of temporary register 0x100.
|-
| hasbit(''value'', ''bit_num'')
| Test whether a bit in a value is on
|-
| getbits(''value'', ''first'', ''amount'')
| {{nml|0.4.1}} Extract some bits from a value. Result is (value >> first) & (1 << amount - 1)
|-
| {{ottd|≤1.11}} version_openttd(''major'', ''minor'', ''revision''[, ''build'']) {{ottd|≥12}} version_openttd(''major'', ''minor'')
| Return the constant representing an OpenTTD version, for example
* OpenTTD 1.4.0: "version_openttd(1, 4, 0)"
* OpenTTD 13.0: "version_openttd(13, 0)"
{{ottd|≤1.8}} Old versions before OpenTTD 1.9 also could check for specific SVN revisions. This is no longer available.
|-
| cargotype_available(''cargotype'')
| Check if a certain cargo type is available in this game. ''cargotype'' must be a literal string of length 4.
|-
| railtype_available(''railtype'')
| Check if a railtype is available in this game. ''railtype'' must be a literal string of length 4.
|-
| roadtype_available(''roadtype'')
| Check if a roadtype is available in this game. ''roadtype'' must be a literal string of length 4.
|-
| tramtype_available(''tramtype_available'')
| Check if a tramtype_available is available in this game. ''tramtype_available'' must be a literal string of length 4.
|-
| grf_current_status(''grfid[, mask]'')
| 1 if the given GRF is currently active 0, otherwise. If ''mask'' is set, only the bits set in the mask will be tested. Both parameters must be a literal string of length 4.
|-
| grf_future_status(''grfid[, mask]'')
| Same as above, but tests whether the grf will become active instead of whether it's currently active.
|-
| grf_order_behind(''grfid[, mask]'')
| Same as above, but tests whether current grf will become active in the order behind the referenced grf.
|-
| create_effect(''effect_sprite'', ''l_x_offset'', ''t_y_offset'', ''z_offset'')
| Helper function for the vehicle callback 'create_effect'.
* ''effect_sprite'': Sprite for the effect. One of EFFECT_SPRITE_[NONE|STEAM|DIESEL|ELECTRIC|AIRCRAFT_BREAKDOWN_SMOKE].
* ''l_x_offset'': Longitudinal or X position of the effect, depending on callback result CB_RESULT_CREATE_EFFECT_NO_ROTATION.
* ''t_y_offset'': Transversal or Y position of the effect, depending on callback result CB_RESULT_CREATE_EFFECT_NO_ROTATION.
* ''z_offset'': Z position of the effect.
|-
| visual_effect_and_powered(''effect'', ''offset'', ''powered'')
| Helper function for the train property and callback visual_effect_and_powered.
|-
| visual_effect(''effect'', ''offset'')
| Helper function for the road vehicle and ship property and callback visual_effect.
|-
| str2number(''4-byte long string'')
| Interpret the given string as a dword and return the value as integer.
|-
| cargotype(''4-byte long string'')
| Return the index of the given cargo type in the cargo translation table.
|-
| railtype(''4-byte long string'')
| Return the index of the given railtype in the railtype translation table.
|-
| roadtype(''4-byte long string'')
| Return the index of the given roadtype in the roadtype translation table.
|-
| tramtype(''4-byte long string'')
| Return the index of the given tramtype in the tramtype translation table.
|-
| reserve_sprites(''number of sprites'')
|
Reserve a number of sprites in the TTD sprite range. This is needed if you want to use your own recolour sprites. Example:
<pre style="color:blue">
param[10] = reserve_sprites(1);
replace(param[10]) {
recolour_sprite {
// your colour remap.
}
}
spritelayout xyz {
building {
...
recolour: param[10];
}
}
</pre>
|-
| int(''v1'')
| Converts v1 to an int. This is done by cutting off everything after the decimal point, i.e. rounding toward zero.
|-
| round(''v1'')
| {{nml|0.5.4}} Converts v1 to an int. This is done by rounding towards the closest integer.
|-
| abs(''v1'')
| Return the absolute value of v1.
|-
| acos / asin / atan / cos / sin / tan
| Standard trigonometric functions.
|-
| sqrt
| {{nml|0.5.4}} Square root.
|-
| CMP(''param1, param2'')
| Compares param1 and param2 (considering them as signed values). Returns CMP_LESS if param1 is less than param2, CMP_EQUAL if they are equal and CMP_GREATER if param1 is greater than param2.
|-
| UCMP(''param1, param2'')
| Compares param1 and param2 (considering them as unsigned values). Returns CMP_LESS if param1 is less than param2, CMP_EQUAL if they are equal and CMP_GREATER if param1 is greater than param2.
|-
| rotate(''value, amount'')
| Rotates ''value'' to the right ''amount'' steps. This is always a 32 bits rotation.
|-
| sound(''soundfile[, volume]'')
| Import sound from .wav-file ''soundfile'' into the grf file and return its numeric ID. Including a file multiple times will not cause it to be duplicated. Loaded sound files can be in WAV format, PCM encoding:
* mono
* 8-bit or {{ottdp|1.0|no}} 16-bit
* 11025 Hz, 22050 Hz or 44100 Hz.
''volume'' is in the [0, 100] range, the default value (if not set) is 100.
{{ottdp|15}} Since OpenTTD 15, compressed sound effects are supported in Ogg Opus format, with no restriction on quality, bit depth or sample rate.
|-
| import_sound(''grfid, id[, volume]'')
| Import sound from a different grf file. ''grfid'' refers to the grf-file to import the sound from. ''id'' is the zero-based internal ID of the sound within the other grf-file. ''volume'' is in the [0, 100] range, the default value (if not set) is 100.
|-
| relative_coord(''x, y'')
| Returns the coordinates in ''0xYYXX'' format. x and y must be in the [0, 255] range.
|-
| num_corners_raised(''slope'')
|
Returns the number of corners raised in a slope. Return value is 0 .. 3 for normal slopes and 4 for steep ones. See also [[NML:List of tile slopes|here]] for more information about slopes. Using this on values that are not slopes results in undefined behaviour.
|-
| slope_to_sprite_offset(''slope'')
|
Returns the sprite offset corresponding to a given slope. Return value is in range 0 .. 18. See also [[NML:List of tile slopes|here]] for more information about slopes. The section on [[NML:Spritelayout|spritelayouts]] contains some more information one possible uses, as well as an example. Using this on values that are not slopes results in undefined behaviour.
|-
| palette_1cc(''colour'')
|
Returns the 1cc palette for the given company colour, see [[NML:List_of_default_colour_translation_palettes#Company colour helper functions|here]] for more info.
|-
| palette_2cc(''colour1'', ''colour2'')
|
Returns the 2cc palette for the given first and second company colour, see [[NML:List_of_default_colour_translation_palettes#Company colour helper functions|here]] for more info.
|-
| vehicle_curv_info(''prev_cur'', ''cur_next'')
| Returns the curvature state of a vehicle, given the direction differences between the (previous-current) and (current-next) vehicle pairs. For use with the vehicle variable <code style="color:darkgreen">curv_info</code>.
|-
| format_string(''format'', args)
| Use the python string formatting functions to create a literal string. Keep in mind that the output is a literal string which cannot be used by string(). This function can however be used to create filenames.
|-
| industry_type(''ind_type'', ''ID'')
| Defines either an old industry (using the global ID) or a new industry from your grf (using the grf-local ID). Used only by ''conflicting_ind_types'' on [[NML:Industries]].
''ind_type'' must be either <code style="color:darkgreen">IND_TYPE_OLD</code> or <code style="color:darkgreen">IND_TYPE_NEW</code>. ''ID'' must be in the [0, 127] range.
|-
| accept_cargo(''cargotype'', produce_cargo(''cargotype'', ''factor'')...) produce_cargo(''cargotype'', ''amount'')
| Helper functions used to set industry production in the [[NML:Industries#Cargo_types_array|''cargo_types'' property]].
|}

NML:Vehicles

2026-01-03T17:23:03Z

Andythenorth: /* Train properties */ - update track_type to account for train prop 0x34

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

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

|}
<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 .. 100
| Probability of reversing rail vehicle, i.e. facing forward or backward, when purchased.
|}

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:Spritelayout

2025-11-02T13:34:58Z

Andythenorth: Since https://github.com/OpenTTD/nml/pull/309, 'all spritesets used in a layout must have the same number of sprites' no longer applies

{{NMLNavBlocksyntax}}

Stations, houses, industry tiles, objects, and airport tiles use spritelayouts to define layouts how sprites are supposed to be arranged on a tile. A <code style="color:darkgreen">spritelayout</code> can combine multiple sprites into one entity, which represents everything that is to be drawn on a particular tile. A simple example to illustrate how it works:

<pre style="color:blue">
spritelayout airport_building1 {
ground { sprite: GROUNDSPRITE_NORMAL; }
childsprite {
sprite: spr_small_dirt_ne; // custom spriteset
always_draw: 1; // also draw in transparent mode
}
building {
sprite: 0xA67; // reuse this existing base set sprite
xoffset: 0x0F;
xextent: 1;
zextent: 6;
recolour_mode: RECOLOUR_REMAP;
palette: PALETTE_USE_DEFAULT;
}
}
</pre>

The sprite layout is composed of one or more sprites. Each sprite is defined by a <code style="color:darkgreen">ground</code>, <code style="color:darkgreen">building</code> or <code style="color:darkgreen">childsprite</code> block. What block to use depends on how the sprite is to be placed on the tile.

* <code style="color:darkgreen">ground</code> sprites are drawn at the base of the tile, like grass and concrete, rails etc. in normal TTD. With a few exceptions (e.g. when using custom foundations), you should always provide a ground sprite, even when the building above fully covers it. This because in transparent mode, the building becomes invisible. A tile can only have one ground sprite.
* <code style="color:darkgreen">building</code> sprites are drawn on top of the ground sprite. To determine their location and drawing order (what goes in front of what), they have a 3D bounding box.
* With <code style="color:darkgreen">childsprite</code>(s), you can effectively compose sprites from multiple parts. When placing these after a building sprite, they will use the same bounding box as the previous building sprite. When placing them before the first building sprite, they will have no bounding box, as if they would use the 'bounding box' of the ground tile. Multiple childsprites may be used per ground / building sprite.

The sprite order is genrally determined by the sprite sorter, that evaluates the bounding box (see below) of each sprite. Child sprites are always part of the building (or ground) sprite that precedes them. In the GUI, sprites are always drawn in the order specified in the layout, so be sure to get this correct for spritelayouts that are to be displayed there.

Per sprite, a number of parameters may be set. These are listed below. Unless otherwise indicated, each may have a value that is dependant on '''variables, parameters or registers'''. Accessed variables are always in the <code style="color:darkgreen">SELF</code> scope. Accessing variables inside the purchase list is '''not''' supported, make sure that layouts accessed from there do not use them. Using variables and parameters, it's possible to create wildly differing looks with few spritelayouts.

===Sprite===

The most important parameter is <code style="color:darkgreen">sprite</code>, this determines the actual sprite to be drawn. If you set this to a number, a TTD sprite will be drawn, usually from the base set. Pre-defined constants for some base set sprites are:

* <code style="color:darkgreen">GROUNDSPRITE_NORMAL<ref name="spritenames">These constants can be used for sprites on flat ground. There are also equivalent sprites for sloped ground, however. These sprites follow the initial ground sprite, the [[NML:Builtin functions|builtin function]] <code style="color:darkgreen">slope_to_sprite_offset(''slope'')</code> may be used to compute the required offset. Refer to the reference on [[NML:List of tile slopes|slopes]] or the [[#Example_.28advanced.29_Spritelayout|example]] below.</ref></code> default terrain type for that climate (temperate, toyland: normal, arctic: without snow, tropical: rainforest).
* <code style="color:darkgreen">GROUNDSPRITE_DESERT <ref name="spritenames" /></code> desert tile
* <code style="color:darkgreen">GROUNDSPRITE_DESERT_1_2 <ref name="spritenames" /></code> transition tile between desert and grass
* <code style="color:darkgreen">GROUNDSPRITE_SNOW <ref name="spritenames" /></code> snowy ground tile
* <code style="color:darkgreen">GROUNDSPRITE_SNOW_1_4 <ref name="spritenames" /></code> 1/4 snowy ground tile
* <code style="color:darkgreen">GROUNDSPRITE_SNOW_2_4 <ref name="spritenames" /></code> half-snowy ground tile
* <code style="color:darkgreen">GROUNDSPRITE_SNOW_3_4 <ref name="spritenames" /></code> 3/4 snowy ground tile
* <code style="color:darkgreen">GROUNDSPRITE_SNOW_4_4 <ref name="spritenames" /></code> snowy ground tile
* <code style="color:darkgreen">GROUNDSPRITE_CONCRETE</code> concrete ground tile
* <code style="color:darkgreen">GROUNDSPRITE_WATER</code> flat water tile, automatically choosen from sea, river and canal sprites, including river and canal borders.
* <code style="color:darkgreen">GROUNDSPRITE_CLEARED <ref name="spritenames" /></code> ground tile that has just been bulldozed (with brown colour)
* <code style="color:darkgreen">GROUNDSPRITE_RAIL_X <ref name="spritenames" /></code> ground tile with rail and terrain appropriate ground, NE-SW orientation (provided by railtype)
* <code style="color:darkgreen">GROUNDSPRITE_RAIL_Y <ref name="spritenames" /></code> ground tile with rail and terrain appropriate ground, NW-SE orientation (provided by railtype)
* <code style="color:darkgreen">GROUNDSPRITE_ROAD_X <ref name="spritenames" /></code> ground tile with straight road piece on grass, NE-SW orientation
* <code style="color:darkgreen">GROUNDSPRITE_ROAD_Y <ref name="spritenames" /></code> ground tile with straight road piece on grass, NW-SE orientation
<references />

Alternatively, you can set the value to (the name of) a [[NML:Spriteset|spriteset]], to provide a custom sprite. When the value is just a spriteset identifier, a sprite from that set will be selected depending on the construction stage, see below. If you supply an argument (e.g. <code style="color:darkgreen">sprite: some_sprite_set(2);</code>), the corresponding sprite from the sprite set will be used, with an argument of 0 corresponding to the first sprite. Note that the argument may also be variable, so you could e.g. use <code style="color:darkgreen">sprite: some_set(construction_state);</code> to use the construction state to select the sprite (as is the default). If the spriteset has labels defined, you can use these labels in the argument expression.

* For stations, objects and airport tiles, there are no construction stages, so the first sprite from the set is used always.
* For houses and industry tiles, sprite chosen depends on the construction stage and the number of sprites available.
** If there is only one sprite in the set, it is used always.
** If there are two sprites, one is used during construction (stages 0-2) and one for the finished building (stage 3)
** If there are three sprites, one is used for the beginning of construction (stage 0), one for the other construction stages (stages 1-2) and one for the finished building (stage 3).
** If there are four sprites, one is used for each construction stage.
** Sprites after the first four are always ignored.
* For road stops the usage of the ground sprite depends on the [[NML:Roadstops#List of draw mode flags|''draw_mode'' property]].
* For objects the usage of the ground sprite may be skipped depending on the [[NML:Objects#List of object flags|''OBJ_FLAG_DRAW_WATER'' flag]], which has the same effect as ''GROUNDSPRITE_WATER''.

===Recolouring===

Next, you have the option to apply recolouring, i.e. to change the colours of the sprite. This is done via the following attributes:

* <code style="color:darkgreen">recolour_mode</code>: This must be compile-time constant. Available recolour modes are:
** <code style="color:darkgreen">RECOLOUR_NONE</code>: Use no colour translation (default)
** <code style="color:darkgreen">RECOLOUR_REMAP</code>: Use a colour translation table as defined by <code style="color:darkgreen">palette</code>. This tables maps all colours of the sprite to a new colour.
** <code style="color:darkgreen">RECOLOUR_TRANSPARENT</code>: Draw the sprite in transparant mode, using a colour translation table as defined by <code style="color:darkgreen">palette</code>. Normally the palette will be set to PALETTE_TO_TRANSPARANT to draw all underlying colours somewhat darker. Note that the selected palette is applied to the colours of the underlying sprite, whatever that happens to be. The supplied sprite is only used to determine what pixels to recolour.
* <code style="color:darkgreen">palette</code>: This defines the palette which is used for the colour translation. It may only (and must!) be set when <code style="color:darkgreen">recolour_mode</code> is set to <code style="color:darkgreen">RECOLOUR_REMAP</code> or <code style="color:darkgreen">RECOLOUR_TRANSPARENT</code>. The available values are the same as for <code style="color:darkgreen">sprite</code>, i.e. you can use either a default sprite or a sprite from a sprite set. In this case, however, the referenced sprite must not be a real sprite, but a [[NML:Recolour sprites|recolour sprite]]. For available default recolour sprites, see the appendix on [[NML:List of default colour translation palettes|available palettes]].

===Display yes/no===

The following attributes allow configuring whether the sprite will be displayed or not.

* <code style="color:darkgreen">hide_sprite</code>: If set to 1, this sprite will not be drawn at all. Default is 0. If a building sprite is not drawn, all child sprites that share its bounding box are not drawn either. Setting this to a constant value makes little sense, but you can use this to enable/disable drawing certain sprites at runtime depending on certain conditions.
* <code style="color:darkgreen">always_draw</code>: This must be a compile-time-constant. If set to 1, this sprite will also be drawn when the user has enabled transparant mode. The default value is 0. This is not available for ground sprites (those are drawn always), but it is for child sprites that share their bounding box with the ground sprite.

===Positioning===

How to position the sprite depends on the type of sprite:

* <code style="color:darkgreen">ground</code>: Ground sprites cannot be positioned.
* <code style="color:darkgreen">building</code>: A three-dimensional bounding box may be defined. The X-axis runs from top-right to bottom-left and the Y-axis from top-left to bottom-right. Both X and Y are measured in 1/16 length of the the tile border. The Z axis is vertical and measured in pixels. Extending the bounding box over the edges of a tile is possible, but not recommended as it may lead to glitches. '''Unless you know exactly what you are doing, please follow the recommendations below. They are most likely exactly what you need'''. In NewGRF developer mode in OpenTTD, it's possible to view the bounding boxes of all sprites by pressing Ctrl+B. In order to use and define a custom bounding box, the following attributes can be used:
** <code style="color:darkgreen">xoffset</code>: Offset from the northwestern edge to the start of the bounding box (X). Unit is 1/16 of the tile border. Default value is 0.
** <code style="color:darkgreen">yoffset</code>: Offset from the northeastern edge to the start of the bounding box (Y). Unit is 1/16 of the tile border. Default value is 0.
** <code style="color:darkgreen">zoffset</code>: Offset from the lowest tile corner (with foundation added) to the start of the bounding box (Z). Unit is pixels. Default value is 0.
** <code style="color:darkgreen">xextent</code>: Size of the bounding box, in the X-direction. Must be a compile-time constant. Unit is 1/16 of the tile border. Default value is 16.
** <code style="color:darkgreen">yextent</code>: Size of the bounding box, in the Y-direction. Must be a compile-time constant. Unit is 1/16 of the tile border. Default value is 16.
** <code style="color:darkgreen">zextent</code>: Size of the bounding box, in the Z-direction. Must be a compile-time constant. Unit is pixels. Default value is 16.
* <code style="color:darkgreen">childsprite</code>: Child sprites may be positioned relative to their 'parent' sprite that defines the bounding box. <code style="color:darkgreen">xoffset</code> and <code style="color:darkgreen">yoffset</code> may be set to specify an offset in pixels between the origin of the parent and child sprite. When the parent sprite is the ground sprite, TTDPatch does not support offsets other than 0,0. Note that all child sprites should fit inside the bounding box of the parent sprite to avoid visual glitches.

===Strong recommendations for bounding boxes===

For industries, houses, objects, and non-track station tiles:
* Use at most one building sprite; and child sprites for everything else.
** Do not set ''xoffset'', ''yoffset'' or ''zoffset''. The default value 0 applies.
** Do not set ''xextent'' or ''yextent''. The default value 16 applies.
** Set ''zextent'' to "<number of occupied height levels> * 8 - 2". The number of occupied height levels is important for objects allowed under bridges. Otherwise this only needs to be a rough estimate.
* If no sprite visually extends over the ground sprite, you do not need any building sprite: Child sprites can be used for further sprites.

For rail station track tiles:
* Use child sprites of the ground sprite for things "below the train".
* Use exactly two building sprites, possibly with child sprites.
* The first building sprite is used for things "behind the train".
** Set ''xoffset'', ''yoffset'', ''zoffset'' to 0.
** For track in X direction: Set ''xextent'' to 16, ''yextent'' to 5.
** For track in Y direction: Set ''xextent'' to 5, ''yextent'' to 16.
** Set ''zextent'' to "<number of occupied height levels> * 8 - 2". A rough estimate is good enough.
* The second building sprite is used for things "in-front or above the train".
** For track in X direction: Set ''xoffset'' to 0, ''yoffset'' to 11.
** For track in Y direction: Set ''xoffset'' to 11, ''yoffset'' to 0.
** Set ''zoffset'' to 0.
** For track in X direction: Set ''xextent'' to 16, ''yextent'' to 5.
** For track in Y direction: Set ''xextent'' to 5, ''yextent'' to 16.
** Set ''zextent'' to "<number of occupied height levels> * 8 - 2". A rough estimate is good enough.

===Maximum sprite size===

Ground sprites and their child sprites must not extend over the edges of a regular ground sprite of the slope.

Building sprites and their child sprites:
* must not extend below the south tile edges,
* must not extend left/right of the west/east tile corners,
* must not extend above the north corner by more than 200 pixels including the (default) foundation. If foundations are present, this is reduced by up to 16 pixels (steep slope S) to 184 pixels.

The following image shows the limitations for flat tiles, and the extreme cases of steep slopes:

[[File:Max_tile_sprite_size.png]]

These values apply since {{ottd|1.5}}.

===Example (advanced) Spritelayout===

OpenTTD 1.2 (r22723) allows for nice shorthands in defining multiple views, e.g. for different slopes: Spritelayout can have parameters and may use variables and temporary storage inside of a layout. A common usage for such parametrized spritelayout is taking care of the tile slope and ground type as illustrated in this example:

<pre style="color:blue">
spritelayout company_land_layout {
ground {
// normal ground sprite - always draw
sprite: LOAD_TEMP(0) + LOAD_TEMP(1);
}
childsprite {
// company-coloured border - always draw
sprite: cc_frame(LOAD_TEMP(0));
always_draw: 1;
recolour_mode: RECOLOUR_REMAP;
palette: PALETTE_USE_DEFAULT;
}
childsprite {
// again the normal ground sprite. Thus in non-transparent view
// only the normal ground sprite is shown. In transparent view
// this acts as sprite which darkens the other two sprites via
// a translation to transparency.
sprite: LOAD_TEMP(0) + LOAD_TEMP(1);
}
}

// A pseudo-switch which sets the temporary parameters for the sprite layout, storing the sprite number
// which belongs to the terrain type and the corresponding offset due to the tile slope
switch (FEAT_OBJECTS, SELF, company_land_terrain_switch, [
// We store the offset into the spriteset due to the tile slope into the 1st temporary variable
STORE_TEMP(slope_to_sprite_offset(tile_slope), 0),

// We store the offset to the flat groundsprite we use into the 2nd temporary variable
STORE_TEMP(GROUNDSPRITE_NORMAL, 1),
STORE_TEMP(terrain_type == TILETYPE_DESERT ? GROUNDSPRITE_DESERT : LOAD_TEMP(1), 1),
STORE_TEMP(terrain_type == TILETYPE_SNOW ? GROUNDSPRITE_SNOW : LOAD_TEMP(1), 1),

1
]) {
company_land_layout;
}
</pre>

Standardized Railtype Scheme

2025-06-13T17:50:20Z

Andythenorth: "Track type and gauge" rather than "Track gauge and type", to emphasise purpose, as discussed with michi_cc

This railtype label scheme aims to provide a way to allow players to easily mix and match different train and track sets. It does this by grouping the rail types into what matters from a technical perspective. The scheme provides a standardized way of defining railtype labels, based on track type and gauge, speed class, allowable axle weight and electrification type. To limit combinatorial explosions of rail types, the track properties are abstracted away from strict real-life representations.

It is the explicit intent of this scheme to decouple track sets from vehicle sets to facilitate easy mixing. This way the player can select a track set of choice to go with a train set of choice. It allows the player to play with or without axle load classes, or with or without speed limit classes, simply by loading a track set that does or does not provide these features. In some cases it will also be possible to combine niche track sets, for instance a standard gauge track set with a narrow gauge and a metro track set. Additionally, due to the decoupling, depending on the specific train and track sets used, not all defined vehicles and/or track types might be available in a specific set combination. This is fully intended behaviour.

== When to use the scheme and when ''not'' to use the scheme ==

When to use:
* If you only want to develop a track or a train set.
* If you want players to be able to mix-and-match sets.
* If you are okay with abstractions from real life.

When ''not'' to use:
* If you consider it a crime against humanity when one of your vehicles or track types is not available in a specific game.
* If you want your tracks or vehicles to exactly mirror real-life counterparts down to the last mm of gauge width.
* If your train set is specifically designed to work with your track set only.
* If you feel the compulsory need to fill all 64 railtype slots.

== The Label Scheme ==
A railtype label consists of four characters. In this scheme, each position has a different purpose:
# Track type and gauge class (e.g. standard gauge rail, narrow gauge rail, monorail)
# Speed limit class
# Axle load class (maximum allowed axle weight for this track)
# Energy source type class

In the next sections, each of the four positions will be explained.

=== Track type and gauge class [X***] ===
The first position in the railtype label defines track type and/or track gauge class. The following classes are currently defined:

{|
! !!Track type/gauge
|-
|S ||Standard gauge rail
|-
|B ||Broad gauge rail
|-
|N ||Narrow gauge rail
|-
|n ||Secondary narrow gauge rail (e.g. when providing both metre and cape gauge, always use N in case of just one type of narrow gauge)
|-
|D ||Dual gauge rail, standard/broad gauge
|-
|d ||Dual gauge rail, standard/narrow gauge
|-
|M ||Monorail
|-
|L ||Magnetic Levitation
|}

All track types or gauges are abstractions of real-life types and do not correspond to specific examples used in real-life. For example '''N''' is any gauge that is smaller than standard gauge, but not corresponding to any specific gauge that exists in real life, just like '''n''' is smaller than '''N''', but does not corresponds to a specific real-life gauge.

A train set may define vehicles for gauge '''n''' while not defining vehicles for gauge '''N''', but this is likely only useful for sets that are specifically designed to be used along-side other sets, and the used railtype fallbacks should be carefully considered.

=== Speed limit/appearance class [*X**] ===
The second position in the railtype label defines the speed limit/appearance class. This can be used to provide tracks with different speed limits or appearance variations. The speed limit/appearance class is ''not'' used for trains and a train set should always use the class letter '''A''' in this position.

There is no fixed numeric mapping for this class, but speed limits should start at '''A''' for the lowest speed limit and progress with '''B/C/...''' for higher limits. If you do not want to employ speed limits in your track set, always use the class '''A'''.

Additionally this class can also be used to distinguish different track appearances like normal or full width ballast, grass or concrete ground, etc. Train sets must not define vehicles for appearance classes. If you think you have special vehicles that should only run on the appearance class, it is ''not'' appearance but a separate track type/gauge.

=== Axle load class [**X*] ===
The third position defines the axle weight limit. Heavy trains cannot run on tracks with a low axle weight limit; these trains need more expensive tracks with a higher weight limit. There are five axle load classes '''A''' through '''E'''. '''A''' is for the lowest axle load limit, '''E''' for the highest. The exact axle load attached to each class is relative to the track type/gauge and trains in the set.

A train set should set the appropriate axle weight for each train via the railtype label, as to make the set work with track sets that do provide tracks with different weight limits, even if you don't care about it for your trainset. Ideally, all five standard axle load classes should be used, but a train set may use only some weight classes, as the vehicle rooster might not make it feasible to use all five. The group with the lowest axle weights will get class '''A''', the second lowest class '''B''', etc. up to the group with the highest axle weights which will get class '''E'''. If you do not use all classes, try to spread the classes out (don't use '''A''' and '''B''' for two classes, but e.g. '''B''' and '''D''').

A track set does not have to provide a dedicated track type for each axle weight limit. A track set that does not provide a dedicated track for each axle load class, must make sure to map all undefined axle load classes to a real railtype using property [[Action0/Railtypes#Alternate_rail_type_labels_.281D.29|1D (NFO)]] or [[NML:Railtypes#Railtype_properties|alternative_railtype_list (NML)]]. This way a train set can rely on all labels for all axle load classes being available. Example: if you only want to provide 2 axle load classes for standard gauge unelectrified with no speed limits, you can map SA'''A'''N + SA'''B'''N to SA'''C'''N and SA'''D'''N to SA'''E'''N if the cost difference between the two railtypes is high, or SA'''A'''N to SA'''B'''N and SA'''C'''N + SA'''D'''N to SA'''E'''N if the cost difference is low.

If you don't want to provide any axle load classes in your track set, it doesn't really matter what axle load class you choose for the track, as you'll be mapping all other classes to this track anyways. But the lowest or highest class are the obvious choice. Example: if your track set only provides narrow gauge unelectrified track with no speed limits and no axle load limits, you may use NA'''A'''N for the track label, and provide NA'''B'''N, NA'''C'''N, NA'''D'''N, NA'''E'''N in property [[Action0/Railtypes#Alternate_rail_type_labels_.281D.29|1D (NFO)]] or [[NML:Railtypes#Railtype_properties|alternative_railtype_list (NML)]].

If you need more than five axle load class, you may use lowercase letters for very low axle loads and continue the uppercase letters for very high axle loads. Be advised that your train set may not assume the existence of any other class than '''A''' through '''E''', so think about providing appropriate fallbacks in your railtype table. If you make a track set with an extended range, be aware that not all train sets will define trains for these tracks. In general: only do this in case of a train set with a matching track set.

For the lowercase letters, '''b''' is lower than '''a''', so for increasing axle load limits: b < a < A < B < C etc.

Note that the axle load classes never map to a specific weight in tonnes. For that reason it does not make sense to add a numeric value for the axle load to the name of a track type or in the extended purchase info of a train. Instead use the relative expressions 'very low', 'low', 'medium', 'high' and 'very high' or use the class letters directly.

=== Energy source type class [***X] ===
The last position defines the energy source type class. This is split in generic energy source types like overhead wires and third rail and specialized types like alternating and direct current.

A track set that only uses specialized types, should map the generic types to the most suitable specialized type in the set.

A vehicle set that uses specialized types should define a generic type as fallback, via the railtype table. If such a fallback is omitted, please note that certain vehicles may be unavailable depending on track set loaded.

{|
! !!Generic energy type classes
|-
|N ||no electrification
|-
|E ||overhead wires/catenary electrification
|-
|3 ||3rd rail electrification
|}

{|
! !!Specialized energy type classes !!Vehicle set fallback
|-
|Z ||3rd rail and catenary electrification || 3 or E
|-
|4 ||4th rail electrification || 3
|-
|Y ||4th rail and catenary electrification || 4 or E
|-
|T ||[http://en.wikipedia.org/wiki/Three-phase_AC_railway_electrification three phase AC electrification] || E
|-
| colspan="3" |  
|-
|D ||DC catenary electrification || E
|-
|d ||low voltage DC catenary electrification (only when D also used in set) || First A then E
|-
|A ||AC catenary electrification || E
|-
|a ||low voltage AC catenary electrification (only when A also used in set) || First A then E
|}

All energy source types are abstractions of real-life types and do not correspond to specific examples used in real-life. For example '''D''' and '''d''' are treated as two different DC voltage levels, but do not correspond to any specific real-life voltage level used.

A train set may define vehicles for energy source '''d''' while not defining vehicles for energy source '''D''' (as an example, applies to other energy sources, too), but this is likely only useful for sets that are specifically designed to be used along-side other sets, and the used railtype fallbacks should be carefully considered.

If you want multi-voltage/current vehicles in your set (i.e. a train that can run on both AC and DC current), you have to define a dedicated railtype for those vehicles. Without the railtype, it's not possible to define vehicles with this property. If you only have vehicles that can run on either one type of voltage/current or on all types of voltage/current (e.g. a 2-system if you only have '''A''' and '''D''' tracks, or a 4-system in case of all '''A''', '''a''', '''D''' and '''d'''), then use the generic class '''E''' for vehicles that should be able to run on all different voltage/currents. Also the track set needs to have one at least one railtype with class '''E''' defined.

Note that if you want more than one type of multi-voltage/current, you'll quickly get a combinatory explosion of railtype labels, so plan carefully or do not attempt it. For every different multi-voltage/current vehicle type a dedicated railtype is needed. If you want all possible combinations, then you need to define an additional 8 classes. It is not recommended to make your train/track set this complicated.

Example approach for a 4-system set, with trains that can run on either one or all systems:
* '''E''': generic catenary-powered electric engines. "universal" [4-system] if any of '''D'''/'''d'''/'''A'''/'''a''' are defined.
* '''A''': generic AC catenary electric engines. 25kV only if '''a''' also defined. Vehicle sets should use '''E''' as fallback, if defining an engine for '''A''';
* '''a''': 15kV AC catenary electric engines. Only defined if '''A''' also defined. Vehicle sets should use '''A''' and '''E''' as fallback, if defining an engine for '''a''';
* '''D''': generic DC catenary electric engines. 3kV if '''d''' also defined. Vehicle sets should use '''E''' as fallback, if defining an engine for '''D''';
* '''d''': 1.5kV DC catenary electric engines. Only defined if '''D''' also defined. Vehicle sets should use '''D''' and '''E''' as fallback, if defining an engine for '''d'''.
For a 2-system set, you can simply drop '''a''' and '''d'''.

=== Standard labels: RAIL, ELRL, MONO, MGLV ===
It's not possible to undefine the standard railtypes RAIL, ELRL, MONO and MGLV. The game will always add those if there are vehicles defined for these track types. As a result, for a track set it's best not to ignore those standard labels, but rather work with them and define them in the set. If your track set does not have monorail or maglev tracks, there of course is no need to define those. But if your track set defines anything that resembles unelectrified or electrified rail, you should use the RAIL and ELRL labels. Matching labels from the above scheme will then be defined in property [[Action0/Railtypes#Alternate_rail_type_labels_.281D.29|1D (NFO)]] or [[NML:Railtypes#Railtype_properties|alternative_railtype_list (NML)]].

As vehicles from NewGRFs that do not use explicit railtypes will end up on these standard railtypes, you should use RAIL instead of whatever type could be regarded as the most commonly used unelectrified type, ELRL instead of the most commonly used electrified type and so on. The label according to this scheme is then set as an alternate.

== Summary and notes for track sets ==
This section summarizes and comments the above for track sets.

; [X***] Track type and gauge class
* Define at least one track type for every track type/gauge class you want in your set.
* If you only provide tracks for one type/gauge, consider leaving some free railtypes so a player can load an additional set for some other type.
; [*X**] Speed limit class
* Make sure class A is always available, either directly or via an alternate label.
* Use only class A if you don't want speed limits;
* With speed limits, A is the lowest speed limit. Continue with B, C, etc. for increasing speed limits;
* The speed class can also be used to implement additional eye-candy track types, use letters higher in the alphabet for this.
; [**X*] Axle load class
* Always define all classes A through E for every track type class / electrification combination, either:
** Directly via a real railtype definition;
** Indirectly via the alternate rail type label list, property [[Action0/Railtypes#Alternate_rail_type_labels_.281D.29|1D (NFO)]] or [[NML:Railtypes#Railtype_properties|alternative_railtype_list (NML)]].
* Extend the predefined classes only if you also provide a train set that makes use of these.
; [***X] Energy source type class
* If your set only uses specialized classes, always map the generic classes to the closest matching specialized type via property 1D.
* Don't use specialized sub-types (e.g. d, a) unless you also use the main specialized class (e.g. D, A).
; Standard labels [RAIL, ELRL, MONO, MGLV]
* Always re-define the standard labels when possible, instead of what would be the equivalent of the standard label in this scheme.
* Map the equivalent label(s) from this scheme to the standard labels using property [[Action0/Railtypes#Alternate_rail_type_labels_.281D.29|1D (NFO)]] or [[NML:Railtypes#Railtype_properties|alternative_railtype_list (NML)]].
; Powered/compatible rail types
* For the speed limit/appearance class, every type should be powered and compatible with each other.
* Axle load classes implemented as real railtypes should be powered and compatible in ascending order, i.e. a lower axle load is compatible with a higher axle load, but not vice versa.
* Different energy sources should be compatible with each other but not powered on each other, expect for multi-system energy source classes.
* Different track type and gauge classes should be neither powered nor compatible with each other.

Or, put differently, for each type/gauge, select one or more energy source types. For each type/energy combination provide all axle load classes for the speed class "A", either as a real type or as an alternate of another type. Provide more types with a different speed letter if you want to provide several different speeds or other eye-candy tracks.

== Summary and notes for train sets ==
This section summarizes and comments the above for train sets.

; [X***] Track type and gauge class
* Use the track type class that matches the vehicle;
* Define a fallback type via the railtype table in case you want the vehicle to be available on a different track if no matching track set is loaded.
** Specialized subtypes like "n" might not always be available. If you want those vehicles to be still available then, fall back the the generic class (e.g. "N").
** Think about your set design and how for example standard gauge and narrow gauge vehicles differ to decide if a fallback from narrow gauge to standard gauge has gameplay meaning.
; [*X**] Speed limit class
* Always use class A for every vehicle.
; [**X*] Axle load class
* Use all classes A through E according to the maximum axle weight of the vehicle.
* Extend the predefined classes only if you also provide a track set that makes use of these;
** When extending the predefined classes A through E, define a fallback type via the railtype table in case you want the vehicle to be available if no matching track set is loaded.
; [***X] Energy source type class
* Use the energy source type class that matches the vehicle;
* When using specialized classes, define a fallback type via the railtype table in case you want the vehicle to be available if no matching track set is loaded.
; Standard labels [RAIL, ELRL, MONO, MGLV]
* Define a fallback type to the standard labels via the railtype table in case you want the vehicle to be available on the standard tracks if no matching track set is loaded. This is a decision you need to make depending on the design of your train set.

Be as specific as you want when selecting the railtype, it is the job of the track set to select a playable, reduced subset out of all possible type combinations. This can mean that some vehicles may not appear with some set combinations, but if a player does not want to have e.g. narrow gauge tracks, they might not want narrow gauge vehicles either.

== In case you're not convinced by this scheme ==
Adopting this scheme gives the player freedom to use any track set in combination with any train set that follow the scheme.

This means that you can make your train set compatible with track sets that provide axle load classes, and track sets that provide speed limits, and at the same time with track sets that provide none of this. This way, the player can decide to play with or without axle load classes, or with or without speed limits, simply by loading a track set that does or does not provide these features.

And for your track set, it means that you can make it as simple or as complicated as you want (within the 64 track type limit), while not having to worry about compatibility with train sets.

Still not convinced? Feel free to use railtype labels of your own, but know that you will likely come to regret that at some point in the future.

==Forum topic==
If you want to discuss the standardized railtype scheme or have any questions about it, you can visit [http://www.tt-forums.net/viewtopic.php?t=59379 the forum topic].

==Extensions and best practice==
See [https://newgrf-specs.tt-wiki.net/wiki/Standardized_Railtype_Scheme_extensions Standardized Railtype Scheme extensions]

CargoTypes

2025-01-07T07:30:43Z

Andythenorth: /* Cargo Labels */ typo

'''Cargo labels in OpenTTD'''

{{grfFrom|8}} In GRF version 8 the value to be used in all vehicle and industry properties, and in [[Action3|action 3]], is the position of the cargo label in the [[Action0/Global_Settings#Cargo_translation_table_.2809.29|cargo translation table]] included in the GRF.

{{grfTill|7}} GRF version 7 and below used different cargo properties for different properties (called "Type A" or "translated" and "Type B" or "untranslated" cargo slots), for historical reasons. This method is deprecated as it meant relying solely on cargos always using the same slots. You can see the table of Type A and Type B slots [http://newgrf-specs.tt-wiki.net/index.php?title=CargoTypes&oldid=2861 here] if you really want to.

{{ottd|15.0}} Since 15.0, a default cargo translation table corresponding to the climate (see [[CargoDefaultProps]]) is used if one is not provided. 
{{grfFrom|8}} In GRF version 8, the default translation table is 32 entries long and maps "Type B" slots to each cargo label. 
{{grfTill|7}} In GRF version 7, the default translation table is 12 entries long and uses "Type A" slots to each cargo label. 
The default translation table works just like a GRF provided table: If a cargo label is redefined in a different slot this is correctly translated, and if the cargo label is replaced the cargo type is mapped to invalid.

== Cargo Labels ==

The following cargo labels have been defined so far:

{|class="wikitable"
|-
! Label
! Cargo Description
! [[Action0Cargos#CargoClasses_.2816.29|Cargo classes]]
! colspan="7" | Usage
! Notes
|-
| align="center" colspan="2" | '''Basic Cargos'''
| align="center" colspan="9" | These cargos are present when no NewGRF is used, or in some common Industry NewGRFs
|-
| PASS
| Passengers
| 0001 Passengers
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
|
|-
| COAL
| Coal
| 0010 Bulk
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
|
|-
| MAIL
| Mail
| 0002 Mail
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
|
|-
| OIL_
| Oil
| 0040 Liquid
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
|
|-
| LVST
| Livestock
| 0020 Piece goods
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| GOOD
| Goods
| 0004 Express
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
|
|-
| GRAI
| Grain
| 0010 Bulk
| style="background: #CC00CC; color: black" | TTD
|
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
| Temperate; see also WHEA, MAIZ, CERE. YETI & OTIS: 0210 Covered, bulk
|-
| WOOD
| Wood
| 0020 Piece goods
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
| Named Logs in some industry sets (2TT)
|-
| IORE
| Iron Ore
| 0010 Bulk
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
|
|-
| STEL
| Steel
| 0020 Piece goods
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
| YETI: Renamed "Balls of Steel", OTIS: Renamed "Metal"
|-
| VALU
| Valuables
| 0008 Armoured
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
| Temperate; see also GOLD, DIAM
|-
| PAPR
| Paper
| 0020 Piece goods
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
| OTIS: 0220 Covered, piece goods
|-
| WHEA
| Wheat
| 0010 Bulk
| style="background: #CC00CC; color: black" | TTD
|
|
|
|
|
|
| Arctic; see also GRAI, MAIZ, CERE
|-
| FOOD
| Food
| 0084 Express, refrigerated
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
| YETI: 00A0 Refrigerated, piece goods
|-
| GOLD
| Gold
| 0008 Armoured
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|
|
|
| Arctic; see also VALU, DIAM
|-
| RUBR
| Rubber
| 0040 Liquid
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
|
|-
| FRUT
| Fruit
| 0090 Bulk, refrigerated
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
| XIS: 00A4 Express, piece goods, refrigerated, YETI: 00A0 Piece goods, covered.
|-
| MAIZ
| Maize
| 0010 Bulk
| style="background: #CC00CC; color: black" | TTD
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
| Tropic; see also GRAI, WHEA, CERE. OTIS: Renamed "Animal Feed"
|-
| CORE
| Copper Ore
| 0010 Bulk
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| WATR
| Water
| 0040 Liquid
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
| OTIS: 0044 Express, liquid
|-
| DIAM
| Diamonds
| 0008 Armoured
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
| Tropic; see also VALU, GOLD
|-
| SUGR
| Sugar
| 0010 Bulk
| style="background: #CC00CC; color: black" | TTD
|
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| Toyland
|-
| AORE
| Bauxite (Aluminium ore)
| 0010 Bulk
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| BDMT
| Building Materials
| 0220 Piece goods, covered/sheltered
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
| XIS: 0030 Bulk, piece goods. YETI: 0020 Piece goods.
|-
| BEAN
| Beans
| 0010 Bulk
|
|
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
| CZIS renamed to Potatoes
|-
| BEER
| Alcohol
| 0064 Express, piece goods, liquids
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
|
|-
| BOOM
| Explosives
| 0024 Express, piece goods
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
| OTIS: 0124 Express, Piece goods, hazardous
|-
| BRCK
| Bricks
| 0020 Piece goods
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|
|
|
|
|-
| CBLK
| Carbon Black
| 0230 Piece goods, bulk, covered/sheltered
|
|
|
|
|
|
|
|
|-
| CERA
| Ceramics
| 0020 Piece goods
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|
|
|
|
|-
| CERE
| Cereals
| 0210 Bulk, covered/sheltered
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|
|
|
| ECS: <ref name="ecs_cargo_change" />
|-
| CLAY
| Clay
| 0210 Bulk covered/sheltered
|
|
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| CMNT
| Cement
| 0210 Bulk covered/sheltered
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| COPR
| Copper
| 0020 Piece goods
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| CSTI
| Cast Iron
| 0020 Piece goods
|
|
|
|
|
|
|
|
|-
| CTAR
| Coal Tar
| 0140 Liquids, hazardous
|
|
|
|
|
|
|
|
|-
| DYES
| Dyes
| 0060 Piece goods, liquids
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|
|
|
|
|-
| ENSP
| Engineering Supplies
| 0024 Express, piece goods
|
|
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
| 2TT Industries of the Caribbean: named Machinery
|-
| FECR
| Ferrochrome
| 0010 Bulk
|
|
|
|
|
|
|
|
|-
| FERT
| Fertiliser
| 0030 Bulk, piece goods
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| OTIS: 0034 Express, piece goods, bulk. XIS: 0230 Covered, piece goods, bulk. ECS: <ref name="ecs_cargo_change" />
|-
| FICR
| Fibre crops
| 0030 Bulk, piece goods
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
| OTIS: 0230 Piece goods, bulk, covered/sheltered, renamed "Cotton"
|-
| FISH
| Fish
| 0084 Express, refrigerated
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
|
|-
| FMSP
| Farm Supplies
| 0024 Express, piece goods
|
|
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| GLAS
| Glass
| 0420 Piece goods, oversized
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
| style="background: #FF0000; color: white" | CZIS
| OTIS: 0410 Piece goods, bulk
|-
| GRVL
| Stone
| 0010 Bulk
|
|
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
| Renamed from "Gravel / Ballast" XIS: Renamed "Aggregate"
|-
| JAVA
| Coffee
| 0024 Piece goods, express
|
|
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
|
|-
| KAOL
| Kaolin (China Clay)
| 0250 Bulk, liquids, covered
|
|
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
| XIS: Renamed "Lithium"
|-
| LIME
| Lime stone
| 0010 Bulk
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| MILK
| Milk
| 00C4 Express, liquid, refrigerated
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| OLSD
| Oil seed
| 0210 Bulk, covered/sheltered
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|
|
|
| ECS: <ref name="ecs_cargo_change" />
|-
| PEAT
| Peat
| 0010 Bulk
|
|
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
| XIS: Renamed "Biomass"
|-
| PETR
| Petrol / Fuel Oil
| 0040 Liquid
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
| OTIS: 0130 Hazardous, liquid
|-
| PHOS
| Phosphate
| 0010 Bulk
|
|
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
| XIS: Renamed "Oil sands"
|-
| PLAS
| Plastic
| 0060 Piece goods, liquid
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| PORE
| Pyrite Ore
| 0010 Bulk
|
|
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
| XIS: Renamed "Zinc ore"
|-
| POTA
| Potash
| 0210 Bulk, covered/sheltered
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|
|
|
| ECS: <ref name="ecs_cargo_change" />
|-
| RFPR
| Refined products
| 0040 Liquid
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
| OTIS: renamed "Sewage", XIS: renamed "Petrochemicals"
|-
| SAND
| Sand
| 0010 Bulk
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| SCMT
| Scrap Metal
| 1010 Bulk, non-pourable
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
| OTIS: Renamed "Waste/Garbage"
|-
| SULP
| Sulphur
| 0250 Bulk, liquid, covered/sheltered.
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
| ECS: 0210 Bulk, covered/sheltered <ref name="ecs_cargo_change">ECS cargo classes changed as of Dec 31, 2010</ref>
|-
| TOUR
| Tourists
| 0005 Passengers, express
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| ECS; see also OTI2
|-
| TYRE
| Tyres
| 0020 Piece goods
|
|
|
|
|
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| URAN
| Uranium
| 0110 Bulk, hazardous
|
|
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| 2TT: Piece goods, hazardous
|-
| VEHI
| Vehicles
| 0420 Piece goods, oversized
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
| XIS: 0020 Piece goods. OTIS: 0020 Piece goods, renamed "Cars"
|-
| WDPR
| Wood Products
| 0030 Bulk, piece goods
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
| XIS & OTIS: Renamed "Timber"
|-
| WOOL
| Wool
| 0220 Piece goods, covered/sheltered
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
| ECS: <ref name="ecs_cargo_change" />
|-
| ZINC
| Zinc
| 0020 Piece goods
|
|
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
|
|-
| align="center" colspan="2" | '''Extended Cargos'''
| align="center" colspan="9" | these cargos are only present in rare/specialized situations
|-
| ACID
| Acid
| 0140 Liquids, hazardous
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| ALUM
| Aluminium
| 0020 Piece goods
|
|
|
|
|
|
| style="background: #FF0000; color: white" | CZIS
| See also METL
|-
| BAKE
| Flour
| 0A30 Bulk, powderized, piece goods, covered
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
|
|-
| CASS
| Cassava
| 0010 Bulk
|
|
|
|
|
|
|
|
|-
| CHLO
| Chlorine
| 0140 Liquids, hazardous
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
|
|-
| CHSE
| Cheese
| 00C4 Express, liquid, refrigerated
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
|
|-
| CIGR
| Cigars
| 0024 Piece goods, express
|
|
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| Industries of the Caribbean
|-
| COAT
| Paints & Coatings
| 0060 Piece goods, liquids
|
|
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| 2TT Lumberjack Industries: renamed Varnish
|-
| COBL
| Cobalt
| 0020 Piece goods
|
|
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| Industries of the Caribbean
|-
| COKE
| Coke
| 0010 Bulk
|
|
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| ELTR
| Electricity
| 8000 Special
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
|CZIS uses its own labels... see ELEC and NODC
|-
| EOIL
| Edible Oil
| 0060 Piece goods, liquids
|
|
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
|
|-
| FRVG
| Fruit (and optionally Vegetables)
| 00A4 Express, piece goods, refrigerated
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
| See also FRUT
|-
| FUEL
| Natural Gas
| 0140 Liquid, hazardous
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| Use PETR for refined-oil fuel
|-
| FURN
| Furniture
| 0230 Piece goods, bulk, covered
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| IRON
| Pig Iron
| 0020 Piece goods
|
|
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
|
|-
| LYE_
| Sodium Hydroxide (Lye)
| 0140 Liquids, hazardous
|
|
|
|
|
|
|
|
|-
| MEAT
| Meat
| 00A4 Express, piece goods, refrigerated
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
|
|-
| METL
| Metal
| 0020 Piece goods
|
|
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
| XIS: Renamed "Aluminium"; See also ALUM
|-
| MNO2
| Manganese
| 0010 Bulk
|
|
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
|
|-
| MNSP
| Manufacturing Supplies
| 0024 Piece goods, express
|
|
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| XIS: Renamed "Packaging"
|-
| MOLS
| Molasses
| 0040 Liquid
|
|
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| Industries of the Caribbean
|-
| MPTS
| Machine parts
| 0220 Covered, piece goods
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
|
|-
| NH3_
| Ammonia
| 0140 Liquids, hazardous
|
|
|
|
|
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| NHNO
| [https://en.wikipedia.org/wiki/Ammonium_nitrate NH4NO3 chemical]
| 0130 Hazardous, bulk, piece goods
|
|
|
|
|
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| NUTS
| Nuts
| 0020 Piece goods
|
|
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
|
|-
| NICK
| Nickel
| 0010 Bulk
|
|
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
|
|-
| NITR
| Nitrate
| 0010 Bulk
|
|
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| NKOR
| Nickel ore
| 0010 Bulk
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| OTIS: Renamed "Nickel"
|-
| NUKF
| Nuclear fuel
| Piece goods, hazardous
|
|
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| Improved Town Industries
|-
| NUKW
| Nuclear waste
| Piece goods, hazardous
|
|
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| Improved Town Industries
|-
| OILI
| Oil (imported)
| 0040 Liquid
|
|
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| Industries of the Caribbean
|-
| OILD
| Oil (domestic)
| 0040 Liquid
|
|
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| Industries of the Caribbean
|-
| OTI1
| Workers
| 0001 Passengers
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
|
|-
| OTI2
| Tourists
| 0001 Passengers
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
|
|-
| OYST
| Oysters
| 00A4 Express, piece goods, refrigerated
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
|
|-
| O2__
| Oxygen
| 0040 Liquids
|
|
|
|
|
|
|
|
|-
| PACK
| Packaging
| 0020 Piece goods
|
|
|
|
|
|
| style="background: #FF0000; color: white" | CZIS
|Packaging used mostly for food production.
|-
| PCL_
| Parcels
| 0006 Express, mail
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
|
|-
| PIPE
| Pipe
| 0020 Piece goods
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
|
|-
| POWR
| Electrical Parts
| 0020 Piece goods
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
| OTIS: 0220 Covered, piece goods, renamed "Electrical Machines". XIS and CZIS: Renamed "Electrical Machines"
|-
| QLME
| Quicklime
| 0210 Bulk, covered/sheltered
|
|
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| RCYC
| Recyclables
| 0030 Bulk, piece goods
|
|
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
|
|-
| SALT
| Salt
| 0010 Bulk
|
|
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
|
|-
| SASH
| Soda Ash
| 0210 Bulk, covered/sheltered
|
|
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
|
|-
| SEED
| Seed
| 0230 Piece goods, bulk, covered
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
|
|-
| SESP
| Marine Supplies
| 0024 Express, piece goods
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
|
|-
| SGBT
| Sugar beet
| 0010 Bulk
|
|
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
| not in tropical
|-
| SGCN
| Sugarcane
| 1010 Bulk, non-pourable
|
|
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| only tropical
|-
| SLAG
| Slag
| 0010 Bulk
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| SOAP
| Cleaning Agents
| 0060 Piece goods, liquids
|
|
|
|
|
|
|
|
|-
| STAL
| Alloy Steel
| 0020 Piece goods
|
|
|
|
|
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| STCB
| Carbon Steel
| 0020 Piece goods
|
|
|
|
|
|
|
|
|-
| STSE
| Steel Sections
| 0020 Piece goods
|
|
|
|
|
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| STSH
| Steel Sheet
| 0020 Piece goods
|
|
|
|
|
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| STST
| Stainless Steel
| 0020 Piece goods
|
|
|
|
|
|
|
|
|-
| STWR
| Steel Wire Rod
| 0020 Piece goods
|
|
|
|
|
|
|
|
|-
| TATO
| Potatoes
| 00A4 Express, piece goods, refrigerated
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
| CZIS uses renamed Beans
|-
| TEXT
| Textile
| 0220 Piece goods, covered
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
|
|-
| TBCO
| Tobacco
| 1010 Bulk, non-pourable
|
|
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| Industries of the Caribbean
|-
| TWOD
| Tropic Wood
| 0020 Piece goods
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
| formerly intended as a default cargo
|-
| VBOD
| Vehicle bodies
| 0020 Piece goods
|
|
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| VENG
| Vehicle Engines
| 0020 Piece goods
|
|
|
|
|
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| VPTS
| Vehicle Parts
| 0024 Piece goods, express
|
|
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
| XIS: 0020 Piece goods, renamed "Parts"
|-
| WSTE
| Waste
| 0230 Piece goods, bulk, covered
|
|
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| Used by Improved Town Industries.
|-
| align="center" colspan="2" | '''Fantasy Cargos'''
| align="center" colspan="9" | these cargos are for use in fantasy or science fiction settings
|-
| BATT
| Batteries
| 0020 Piece goods
| style="background: #CC00CC; color: black" | TTD
|
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
|
|
|
|
| Toyland
|-
| BUBL
| Bubbles
| 0020 Piece goods
| style="background: #CC00CC; color: black" | TTD
|
|
|
|
|
|
| Toyland
|-
| COLA
| Cola
| 0040 Liquid
| style="background: #CC00CC; color: black" | TTD
|
|
|
|
|
|
| Toyland
|-
| CTCD
| Cotton Candy (Candyfloss)
| 0010 Bulk
| style="background: #CC00CC; color: black" | TTD
|
|
|
|
|
|
| Toyland
|-
| FZDR
| Fizzy Drinks
| 0020 Piece goods
| style="background: #CC00CC; color: black" | TTD
|
|
|
|
|
|
| Toyland
|-
| PLST
| Plastic
| 0040 Liquid
| style="background: #CC00CC; color: black" | TTD
|
|
|
|
|
|
| Toyland; see also PLAS
|-
| SWET
| Sweets (Candy)
| 0004 Express
| style="background: #CC00CC; color: black" | TTD
|
|
|
|
|
|
| Toyland
|-
| TOFF
| Toffee
| 0010 Bulk
| style="background: #CC00CC; color: black" | TTD
|
|
|
|
|
|
| Toyland
|-
| TOYS
| Toys
| 0020 Piece goods
| style="background: #CC00CC; color: black" | TTD
|
|
|
|
|
|
| Toyland
|-
| YETI
| Workers, YETI dudes
| 0404 Express, oversized
|
|
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
|
|
|
|
|
|-
| YETY
| Tired Workers, Tired YETI dudes
| 0404 Express, oversized
|
|
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
|
|
|
|
|
|-
| ELEC
| Charged Batteries (electricity from PP)
| 0020 Piece goods
|
|
|
|
|
|
| style="background: #FF0000; color: white" | CZIS
| Used as means of electricity transportation.
|-
| NODC
| Uncharged Batteries (return of batteries) aka No Direct Current
| 0020 Piece goods
|
|
|
|
|
|
| style="background: #FF0000; color: white" | CZIS
|Used as means of electricity transportation.
|-
| align="center" colspan="2" | '''Special Cargos'''
| align="center" colspan="9" | these cargos are for use outside industry sets and do not represent transporting anything
|-
| GEAR
| Locomotive regearing
| 8000 Special
|
|
|
|
|
|
|
| Using this cargo may make your vehicle set incompatible with some industry sets
use CB36 instead to set capacity to 0
|-
| align="center" colspan="2" | '''Deprecated Cargos'''
| align="center" colspan="9" | these cargos are not used by any current industry set, and are listed here for backwards compatibility
|-
| RSGR
| Raw Sugar
| 0010 Bulk
|
|
|
|
|
|
|
| Deprecated see SGBT and SGCN
|-
| SCRP
| Scrap Metal
| 0010 Piece goods
|
|
|
|
|
|
|
| Deprecated see SCMT instead
|}

<references />

An overview of FIRS cargos is available [https://grf.farm/firs/code_reference_latest.html here] for the latest version. Please don't add FIRS labels here, as they have a history of being outdated or wrong, which is unhelpful to other grf authors. Thanks.

If you write or publish a NewGRF which introduces a new cargo label, please also add a comment where the new label is used.

NML:Cargos

2025-01-05T20:01:42Z

Andythenorth: /* Cargo classes */ - don't imply that bitmask(CC_EXPRESS, CC_REFRIGERATED) can be assumed to be food, that just adds to existing confusions.

{{NMLNavPropVarCB}}

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

==Cargo properties==

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

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

===Cargo classes===

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

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

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

===Cargo effects on town growth===

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

If no cargos in the game are defined as TOWNGROWTH_FOOD, towns above the snowline will not require food to grow. If no cargos in the game are defined as TOWNGROWTH_FOOD or TOWNGROWTH_WATER, 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.

There are some additional effects of these flags on subsidies and town cargo transport statistics. See the nfo docs for details: https://newgrf-specs.tt-wiki.net/wiki/Action0/Cargos#Substitute_type_and_multiplier_for_town_growth_.2818.2C_19.29

===Town production effect===

{| class="wikitable sortable"
! value
! effect
|-
| TOWNPRODUCTION_PASSENGERS
| Town produces cargo as like passengers
|-
| TOWNPRODUCTION_MAIL
| Town produces cargo as like mail
|-
| TOWNPRODUCTION_NONE
| Town does not produce cargo (default)
|}

==Cargo variables==

Cargos have no variables (yet).

==Cargo callbacks==

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

===Station rating callback===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

====Callback parameters====

<ul><li>
<code style="color:darkgreen">getbits(extra_callback_info1, 0, 8)</code>:
{| |-
!value!!meaning
|-
|0x10||the last vehicle entering the station was a train
|-
|0x11||the last vehicle entering the station was a road vehicle
|-
|0x12||the last vehicle entering the station was a ship
|-
|0x13||the last vehicle entering the station was an aircraft
|-
|0||no vehicle entered the station yet, or (TTDPatch) the last one entering was sold
|}
Please note that there's only one "last vehicle type" field per station, so the vehicle this refers to may not have picked up any of your cargo.
</li><li>
<code style="color:darkgreen">getbits(extra_callback_info2, 0, 8)</code>: The time since the cargo was last picked up, in the time units described above (1 unit = 2.5 days independent of vehicle type)
</li><li>
<code style="color:darkgreen">getbits(extra_callback_info2, 8, 16)</code>: The amount of cargo waiting.
</li><li>
<code style="color:darkgreen">getbits(extra_callback_info2, 24, 8)</code>: The speed of the last vehicle picking the cargo up, in the speed units described above (if no vehicle entered the station yet, the value is 0xFF).
</li></ul>

====Effect of callback====

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

NML:Cargos

2024-12-08T18:01:08Z

Andythenorth: /* Cargo classes */ add CC_POTABLE and CC_NON_POTABLE

{{NMLNavPropVarCB}}

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

==Cargo properties==

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

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

===Cargo classes===

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

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

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

===Cargo effects on town growth===

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

If no cargos in the game are defined as TOWNGROWTH_FOOD, towns above the snowline will not require food to grow. If no cargos in the game are defined as TOWNGROWTH_FOOD or TOWNGROWTH_WATER, 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.

There are some additional effects of these flags on subsidies and town cargo transport statistics. See the nfo docs for details: https://newgrf-specs.tt-wiki.net/wiki/Action0/Cargos#Substitute_type_and_multiplier_for_town_growth_.2818.2C_19.29

===Town production effect===

{| class="wikitable sortable"
! value
! effect
|-
| TOWNPRODUCTION_PASSENGERS
| Town produces cargo as like passengers
|-
| TOWNPRODUCTION_MAIL
| Town produces cargo as like mail
|-
| TOWNPRODUCTION_NONE
| Town does not produce cargo (default)
|}

==Cargo variables==

Cargos have no variables (yet).

==Cargo callbacks==

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

===Station rating callback===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

====Callback parameters====

<ul><li>
<code style="color:darkgreen">getbits(extra_callback_info1, 0, 8)</code>:
{| |-
!value!!meaning
|-
|0x10||the last vehicle entering the station was a train
|-
|0x11||the last vehicle entering the station was a road vehicle
|-
|0x12||the last vehicle entering the station was a ship
|-
|0x13||the last vehicle entering the station was an aircraft
|-
|0||no vehicle entered the station yet, or (TTDPatch) the last one entering was sold
|}
Please note that there's only one "last vehicle type" field per station, so the vehicle this refers to may not have picked up any of your cargo.
</li><li>
<code style="color:darkgreen">getbits(extra_callback_info2, 0, 8)</code>: The time since the cargo was last picked up, in the time units described above (1 unit = 2.5 days independent of vehicle type)
</li><li>
<code style="color:darkgreen">getbits(extra_callback_info2, 8, 16)</code>: The amount of cargo waiting.
</li><li>
<code style="color:darkgreen">getbits(extra_callback_info2, 24, 8)</code>: The speed of the last vehicle picking the cargo up, in the speed units described above (if no vehicle entered the station yet, the value is 0xFF).
</li></ul>

====Effect of callback====

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

NML:Vehicles

2024-11-23T20:00:50Z

Andythenorth: /* Vehicle callbacks */ document reverse_build_probability callback

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

===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>
| 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
|-
| 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
| No
| [0 <nowiki>|</nowiki> 1]
| {{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>

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

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 .. 100
| Probability of reversing rail vehicle, i.e. facing forward or backward, when purchased.
|}

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:Cargos

2024-11-23T19:53:16Z

Andythenorth: /* Cargo classes */ link to FRAX Cargo Class Scheme

{{NMLNavPropVarCB}}

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

==Cargo properties==

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

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

===Cargo classes===

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

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

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

===Cargo effects on town growth===

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

If no cargos in the game are defined as TOWNGROWTH_FOOD, towns above the snowline will not require food to grow. If no cargos in the game are defined as TOWNGROWTH_FOOD or TOWNGROWTH_WATER, 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.

There are some additional effects of these flags on subsidies and town cargo transport statistics. See the nfo docs for details: https://newgrf-specs.tt-wiki.net/wiki/Action0/Cargos#Substitute_type_and_multiplier_for_town_growth_.2818.2C_19.29

===Town production effect===

{| class="wikitable sortable"
! value
! effect
|-
| TOWNPRODUCTION_PASSENGERS
| Town produces cargo as like passengers
|-
| TOWNPRODUCTION_MAIL
| Town produces cargo as like mail
|-
| TOWNPRODUCTION_NONE
| Town does not produce cargo (default)
|}

==Cargo variables==

Cargos have no variables (yet).

==Cargo callbacks==

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

===Station rating callback===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

====Callback parameters====

<ul><li>
<code style="color:darkgreen">getbits(extra_callback_info1, 0, 8)</code>:
{| |-
!value!!meaning
|-
|0x10||the last vehicle entering the station was a train
|-
|0x11||the last vehicle entering the station was a road vehicle
|-
|0x12||the last vehicle entering the station was a ship
|-
|0x13||the last vehicle entering the station was an aircraft
|-
|0||no vehicle entered the station yet, or (TTDPatch) the last one entering was sold
|}
Please note that there's only one "last vehicle type" field per station, so the vehicle this refers to may not have picked up any of your cargo.
</li><li>
<code style="color:darkgreen">getbits(extra_callback_info2, 0, 8)</code>: The time since the cargo was last picked up, in the time units described above (1 unit = 2.5 days independent of vehicle type)
</li><li>
<code style="color:darkgreen">getbits(extra_callback_info2, 8, 16)</code>: The amount of cargo waiting.
</li><li>
<code style="color:darkgreen">getbits(extra_callback_info2, 24, 8)</code>: The speed of the last vehicle picking the cargo up, in the speed units described above (if no vehicle entered the station yet, the value is 0xFF).
</li></ul>

====Effect of callback====

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

Action0/Cargos

2024-11-23T19:52:30Z

Andythenorth: /* CargoClasses (16) */ link to FRAX

== 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}}||Color for the station list window
|-
|14||B||{{ottdp|0.6|2.5}}||Color 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
|Not 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 ==

Action0/Cargos

2024-11-23T19:49:21Z

Andythenorth: /* CargoClasses (16) */ sentence case not title

== 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}}||Color for the station list window
|-
|14||B||{{ottdp|0.6|2.5}}||Color 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.

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

Action0/Cargos

2024-11-23T19:48:54Z

Andythenorth: /* CargoClasses (16) */ bits 13 and 14 defined as potable and non-potable by https://github.com/OpenTTD/OpenTTD/pull/12979

== 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}}||Color for the station list window
|-
|14||B||{{ottdp|0.6|2.5}}||Color 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.

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

Action0/Cargos

2024-11-23T19:45:29Z

Andythenorth: /* CargoClasses (16) */

== 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}}||Color for the station list window
|-
|14||B||{{ottdp|0.6|2.5}}||Color 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.

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
|Not Pourable
|open wagon, but not hopper wagon
|AND NOT
|only exclude, when Bulk included
|combine with Bulk
|-
|13
|2000
|reserved. No canonical specification
| -
| -
| -
| -
|-
|14
|4000
|reserved. No canonical specification
| -
| -
| -
| -
|-
|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 ==

Action0/Cargos

2024-11-23T19:44:48Z

Andythenorth: /* CargoClasses (16) */ bit 11 (Powderized) was incorrectly documented as 'moisture protected', probably clerical error - original definition is made clear at http://www.ttdpatch.de/grfspecs/Action0Cargos.html#Cargo+classes+%2816%29

== 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}}||Color for the station list window
|-
|14||B||{{ottdp|0.6|2.5}}||Color 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.

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 wagon
|OR/AND NOT
|only exclude, when Bulk included
|combine with Bulk
|-
|12
|1000
|Not Pourable
|open wagon, but not hopper wagon
|AND NOT
|only exclude, when Bulk included
|combine with Bulk
|-
|13
|2000
|reserved. No canonical specification
| -
| -
| -
| -
|-
|14
|4000
|reserved. No canonical specification
| -
| -
| -
| -
|-
|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:Cargos

2024-11-17T16:24:02Z

Andythenorth: /* Cargo classes */ Cargo class bit 15 (CC_SPECIAL) has been deprecated for years in nfo spec with 'do not set' in docs

{{NMLNavPropVarCB}}

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

==Cargo properties==

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

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

===Cargo classes===

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

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

===Cargo effects on town growth===

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

If no cargos in the game are defined as TOWNGROWTH_FOOD, towns above the snowline will not require food to grow. If no cargos in the game are defined as TOWNGROWTH_FOOD or TOWNGROWTH_WATER, 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.

There are some additional effects of these flags on subsidies and town cargo transport statistics. See the nfo docs for details: https://newgrf-specs.tt-wiki.net/wiki/Action0/Cargos#Substitute_type_and_multiplier_for_town_growth_.2818.2C_19.29

===Town production effect===

{| class="wikitable sortable"
! value
! effect
|-
| TOWNPRODUCTION_PASSENGERS
| Town produces cargo as like passengers
|-
| TOWNPRODUCTION_MAIL
| Town produces cargo as like mail
|-
| TOWNPRODUCTION_NONE
| Town does not produce cargo (default)
|}

==Cargo variables==

Cargos have no variables (yet).

==Cargo callbacks==

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

===Station rating callback===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

====Callback parameters====

<ul><li>
<code style="color:darkgreen">getbits(extra_callback_info1, 0, 8)</code>:
{| |-
!value!!meaning
|-
|0x10||the last vehicle entering the station was a train
|-
|0x11||the last vehicle entering the station was a road vehicle
|-
|0x12||the last vehicle entering the station was a ship
|-
|0x13||the last vehicle entering the station was an aircraft
|-
|0||no vehicle entered the station yet, or (TTDPatch) the last one entering was sold
|}
Please note that there's only one "last vehicle type" field per station, so the vehicle this refers to may not have picked up any of your cargo.
</li><li>
<code style="color:darkgreen">getbits(extra_callback_info2, 0, 8)</code>: The time since the cargo was last picked up, in the time units described above (1 unit = 2.5 days independent of vehicle type)
</li><li>
<code style="color:darkgreen">getbits(extra_callback_info2, 8, 16)</code>: The amount of cargo waiting.
</li><li>
<code style="color:darkgreen">getbits(extra_callback_info2, 24, 8)</code>: The speed of the last vehicle picking the cargo up, in the speed units described above (if no vehicle entered the station yet, the value is 0xFF).
</li></ul>

====Effect of callback====

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

CargoTypes

2024-11-16T16:42:46Z

Andythenorth: Note on why FIRS isn't listed.

'''Cargo labels in OpenTTD'''

{{grfFrom|8}} In GRF version 8 the value to be used in all vehicle and industry properties, and in [[Action3|action 3]], is the position of the cargo label in the [[Action0/Global_Settings#Cargo_translation_table_.2809.29|cargo translation table]] included in the GRF.

{{grfTill|7}} GRF version 7 and below used different cargo properties for different properties (called "Type A" or "translated" and "Type B" or "untranslated" cargo slots), for historical reasons. This method is deprecated as it meant relying solely on cargos always using the same slots. You can see the table of Type A and Type B slots [http://newgrf-specs.tt-wiki.net/index.php?title=CargoTypes&oldid=2861 here] if you really want to.

{{ottd|15.0}} Since 15.0, a default cargo translation table corresponding to the climate (see [[CargoDefaultProps]]) is used if one is not provided. 
{{grfFrom|8}} In GRF version 8, the default translation table is 32 entries long and maps "Type B" slots to each cargo label. 
{{grfTill|7}} In GRF version 7, the default translation table is 12 entries long and uses "Type A" slots to each cargo label. 
The default translation table works just like a GRF provided table: If a cargo label is redefined in a different slot this is correctly translated, and if the cargo label is replaced the cargo type is mapped to invalid.

== Cargo Labels ==

The following cargo labels have been defined so far:

{|class="wikitable"
|-
! Label
! Cargo Description
! [[Action0Cargos#CargoClasses_.2816.29|Cargo classes]]
! colspan="7" | Usage
! Notes
|-
| align="center" colspan="2" | '''Basic Cargos'''
| align="center" colspan="9" | These cargos are present when no NewGRF is used, or in some common Industry NewGRFs
|-
| PASS
| Passengers
| 0001 Passengers
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
|
|-
| COAL
| Coal
| 0010 Bulk
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
|
|-
| MAIL
| Mail
| 0002 Mail
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
|
|-
| OIL_
| Oil
| 0040 Liquid
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
|
|-
| LVST
| Livestock
| 0020 Piece goods
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| GOOD
| Goods
| 0004 Express
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
|
|-
| GRAI
| Grain
| 0010 Bulk
| style="background: #CC00CC; color: black" | TTD
|
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
| Temperate; see also WHEA, MAIZ, CERE. YETI & OTIS: 0210 Covered, bulk
|-
| WOOD
| Wood
| 0020 Piece goods
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
| Named Logs in some industry sets (2TT)
|-
| IORE
| Iron Ore
| 0010 Bulk
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
|
|-
| STEL
| Steel
| 0020 Piece goods
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
| YETI: Renamed "Balls of Steel", OTIS: Renamed "Metal"
|-
| VALU
| Valuables
| 0008 Armoured
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
| Temperate; see also GOLD, DIAM
|-
| PAPR
| Paper
| 0020 Piece goods
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
| OTIS: 0220 Covered, piece goods
|-
| WHEA
| Wheat
| 0010 Bulk
| style="background: #CC00CC; color: black" | TTD
|
|
|
|
|
|
| Arctic; see also GRAI, MAIZ, CERE
|-
| FOOD
| Food
| 0084 Express, refrigerated
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
| YETI: 00A0 Refrigerated, piece goods
|-
| GOLD
| Gold
| 0008 Armoured
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|
|
|
| Arctic; see also VALU, DIAM
|-
| RUBR
| Rubber
| 0040 Liquid
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
|
|-
| FRUT
| Fruit
| 0090 Bulk, refrigerated
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
| XIS: 00A4 Express, piece goods, refrigerated, YETI: 00A0 Piece goods, covered.
|-
| MAIZ
| Maize
| 0010 Bulk
| style="background: #CC00CC; color: black" | TTD
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
| Tropic; see also GRAI, WHEA, CERE. OTIS: Renamed "Animal Feed"
|-
| CORE
| Copper Ore
| 0010 Bulk
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| WATR
| Water
| 0040 Liquid
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
| OTIS: 0044 Express, liquid
|-
| DIAM
| Diamonds
| 0008 Armoured
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
| Tropic; see also VALU, GOLD
|-
| SUGR
| Sugar
| 0010 Bulk
| style="background: #CC00CC; color: black" | TTD
|
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| Toyland
|-
| AORE
| Bauxite (Aluminium ore)
| 0010 Bulk
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| BDMT
| Building Materials
| 0220 Piece goods, covered/sheltered
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
| XIS: 0030 Bulk, piece goods. YETI: 0020 Piece goods.
|-
| BEAN
| Beans
| 0010 Bulk
|
|
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
| CZIS renamed to Potatoes
|-
| BEER
| Alcohol
| 0064 Express, piece goods, liquids
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
|
|-
| BOOM
| Explosives
| 0024 Express, piece goods
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
| OTIS: 0124 Express, Piece goods, hazardous
|-
| BRCK
| Bricks
| 0020 Piece goods
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|
|
|
|
|-
| CBLK
| Carbon Black
| 0230 Piece goods, bulk, covered/sheltered
|
|
|
|
|
|
|
|
|-
| CERA
| Ceramics
| 0020 Piece goods
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|
|
|
|
|-
| CERE
| Cereals
| 0210 Bulk, covered/sheltered
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|
|
|
| ECS: <ref name="ecs_cargo_change" />
|-
| CLAY
| Clay
| 0210 Bulk covered/sheltered
|
|
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| CMNT
| Cement
| 0210 Bulk covered/sheltered
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| COPR
| Copper
| 0020 Piece goods
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| CSTI
| Cast Iron
| 0020 Piece goods
|
|
|
|
|
|
|
|
|-
| CTAR
| Coal Tar
| 0140 Liquids, hazardous
|
|
|
|
|
|
|
|
|-
| DYES
| Dyes
| 0060 Piece goods, liquids
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|
|
|
|
|-
| ENSP
| Engineering Supplies
| 0024 Express, piece goods
|
|
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
| 2TT Industries of the Caribbean: named Machinery
|-
| FECR
| Ferrochrome
| 0010 Bulk
|
|
|
|
|
|
|
|
|-
| FERT
| Fertiliser
| 0030 Bulk, piece goods
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| OTIS: 0034 Express, piece goods, bulk. XIS: 0230 Covered, piece goods, bulk. ECS: <ref name="ecs_cargo_change" />
|-
| FICR
| Fibre crops
| 0030 Bulk, piece goods
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
| OTIS: 0230 Piece goods, bulk, covered/sheltered, renamed "Cotton"
|-
| FISH
| Fish
| 0084 Express, refrigerated
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
|
|-
| FMSP
| Farm Supplies
| 0024 Express, piece goods
|
|
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| GLAS
| Glass
| 0420 Piece goods, oversized
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
| style="background: #FF0000; color: white" | CZIS
| OTIS: 0410 Piece goods, bulk
|-
| GRVL
| Stone
| 0010 Bulk
|
|
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
| Renamed from "Gravel / Ballast" XIS: Renamed "Aggregate"
|-
| JAVA
| Coffee
| 0024 Piece goods, express
|
|
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
|
|-
| KAOL
| Kaolin (China Clay)
| 0250 Bulk, liquids, covered
|
|
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
| XIS: Renamed "Lithium"
|-
| LIME
| Lime stone
| 0010 Bulk
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| MILK
| Milk
| 00C4 Express, liquid, refrigerated
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| OLSD
| Oil seed
| 0210 Bulk, covered/sheltered
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|
|
|
| ECS: <ref name="ecs_cargo_change" />
|-
| PEAT
| Peat
| 0010 Bulk
|
|
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
| XIS: Renamed "Biomass"
|-
| PETR
| Petrol / Fuel Oil
| 0040 Liquid
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
| OTIS: 0130 Hazardous, liquid
|-
| PHOS
| Phosphate
| 0010 Bulk
|
|
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
| XIS: Renamed "Oil sands"
|-
| PLAS
| Plastic
| 0060 Piece goods, liquid
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| PORE
| Pyrite Ore
| 0010 Bulk
|
|
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
| XIS: Renamed "Zinc ore"
|-
| POTA
| Potash
| 0210 Bulk, covered/sheltered
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|
|
|
| ECS: <ref name="ecs_cargo_change" />
|-
| RFPR
| Refined products
| 0040 Liquid
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
| OTIS: renamed "Sewage", XIS: renamed "Petrochemicals"
|-
| SAND
| Sand
| 0010 Bulk
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| SCMT
| Scrap Metal
| 1010 Bulk, non-pourable
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
| OTIS: Renamed "Waste/Garbage"
|-
| SULP
| Sulphur
| 0250 Bulk, liquid, covered/sheltered.
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
| ECS: 0210 Bulk, covered/sheltered <ref name="ecs_cargo_change">ECS cargo classes changed as of Dec 31, 2010</ref>
|-
| TOUR
| Tourists
| 0005 Passengers, express
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| ECS; see also OTI2
|-
| TYRE
| Tyres
| 0020 Piece goods
|
|
|
|
|
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| URAN
| Uranium
| 0110 Bulk, hazardous
|
|
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| 2TT: Piece goods, hazardous
|-
| VEHI
| Vehicles
| 0420 Piece goods, oversized
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
| XIS: 0020 Piece goods. OTIS: 0020 Piece goods, renamed "Cars"
|-
| WDPR
| Wood Products
| 0030 Bulk, piece goods
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
| XIS & OTIS: Renamed "Timber"
|-
| WOOL
| Wool
| 0220 Piece goods, covered/sheltered
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
| ECS: <ref name="ecs_cargo_change" />
|-
| ZINC
| Zinc
| 0020 Piece goods
|
|
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
|
|-
| align="center" colspan="2" | '''Extended Cargos'''
| align="center" colspan="9" | these cargos are only present in rare/specialized situations
|-
| ACID
| Acid
| 0140 Liquids, hazardous
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| ALUM
| Aluminium
| 0020 Piece goods
|
|
|
|
|
|
| style="background: #FF0000; color: white" | CZIS
| See also METL
|-
| BAKE
| Flour
| 0A30 Bulk, powderized, piece goods, covered
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
|
|-
| CASS
| Cassava
| 0010 Bulk
|
|
|
|
|
|
|
|
|-
| CHLO
| Chlorine
| 0140 Liquids, hazardous
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
|
|-
| CHSE
| Cheese
| 00C4 Express, liquid, refrigerated
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
|
|-
| CIGR
| Cigars
| 0024 Piece goods, express
|
|
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| Industries of the Caribbean
|-
| COAT
| Paints & Coatings
| 0060 Piece goods, liquids
|
|
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| 2TT Lumberjack Industries: renamed Varnish
|-
| COBL
| Cobalt
| 0020 Piece goods
|
|
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| Industries of the Caribbean
|-
| COKE
| Coke
| 0010 Bulk
|
|
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| ELTR
| Electricity
| 8000 Special
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
|CZIS uses its own labels... see ELEC and NODC
|-
| EOIL
| Edible Oil
| 0060 Piece goods, liquids
|
|
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
|
|-
| FRVG
| Fruit (and optionally Vegetables)
| 00A4 Express, piece goods, refrigerated
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
| See also FRUT
|-
| FUEL
| Natural Gas
| 0140 Liquid, hazardous
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| Use PETR for refined-oil fuel
|-
| FURN
| Furniture
| 0230 Piece goods, bulk, covered
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| IRON
| Pig Iron
| 0020 Piece goods
|
|
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
|
|-
| LYE_
| Sodium Hydroxide (Lye)
| 0140 Liquids, hazardous
|
|
|
|
|
|
|
|
|-
| MEAT
| Meat
| 00A4 Express, piece goods, refrigerated
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
|
|-
| METL
| Metal
| 0020 Piece goods
|
|
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
| XIS: Renamed "Aluminium"; See also ALUM
|-
| MNO2
| Manganese
| 0010 Bulk
|
|
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
|
|-
| MNSP
| Manufacturing Supplies
| 0024 Piece goods, express
|
|
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| XIS: Renamed "Packaging"
|-
| MOLS
| Molasses
| 0040 Liquid
|
|
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| Industries of the Caribbean
|-
| MPTS
| Machine parts
| 0220 Covered, piece goods
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
|
|-
| NH3_
| Ammonia
| 0140 Liquids, hazardous
|
|
|
|
|
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| NHNO
| [https://en.wikipedia.org/wiki/Ammonium_nitrate NH4NO3 chemical]
| 0130 Hazardous, bulk, piece goods
|
|
|
|
|
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| NUTS
| Nuts
| 0020 Piece goods
|
|
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
|
|-
| NICK
| Nickel
| 0010 Bulk
|
|
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
|
|-
| NITR
| Nitrate
| 0010 Bulk
|
|
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| NKOR
| Nickel ore
| 0010 Bulk
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| OTIS: Renamed "Nickel"
|-
| NUKF
| Nuclear fuel
| Piece goods, hazardous
|
|
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| Improved Town Industries
|-
| NUKW
| Nuclear waste
| Piece goods, hazardous
|
|
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| Improved Town Industries
|-
| OILI
| Oil (imported)
| 0040 Liquid
|
|
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| Industries of the Caribbean
|-
| OILD
| Oil (domestic)
| 0040 Liquid
|
|
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| Industries of the Caribbean
|-
| OTI1
| Workers
| 0001 Passengers
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
|
|-
| OTI2
| Tourists
| 0001 Passengers
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
|
|-
| OYST
| Oysters
| 00A4 Express, piece goods, refrigerated
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
|
|-
| O2__
| Oxygen
| 0040 Liquids
|
|
|
|
|
|
|
|
|-
| PACK
| Packaging
| 0020 Piece goods
|
|
|
|
|
|
| style="background: #FF0000; color: white" | CZIS
|Packaging used mostly for food production.
|-
| PCL_
| Parcels
| 0006 Express, mail
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
|
|-
| PIPE
| Pipe
| 0020 Piece goods
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
|
|-
| POWR
| Electrical Parts
| 0020 Piece goods
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
| OTIS: 0220 Covered, piece goods, renamed "Electrical Machines". XIS and CZIS: Renamed "Electrical Machines"
|-
| QLME
| Quicklime
| 0210 Bulk, covered/sheltered
|
|
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| RCYC
| Recyclables
| 0030 Bulk, piece goods
|
|
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
|
|-
| SALT
| Salt
| 0010 Bulk
|
|
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
|
|-
| SASH
| Soda Ash
| 0210 Bulk, covered/sheltered
|
|
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
|
|-
| SEED
| Seed
| 0230 Piece goods, bulk, covered
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
|
|-
| SESP
| Marine Supplies
| 0024 Express, piece goods
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
|
|-
| SGBT
| Sugar beet
| 0010 Bulk
|
|
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
| not in tropical
|-
| SGCN
| Sugarcane
| 1010 Bulk, non-pourable
|
|
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| only tropical
|-
| SLAG
| Slag
| 0010 Bulk
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| SOAP
| Cleaning Agents
| 0060 Piece goods, liquids
|
|
|
|
|
|
|
|
|-
| STAL
| Alloy Steel
| 0020 Piece goods
|
|
|
|
|
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| STCB
| Carbon Steel
| 0020 Piece goods
|
|
|
|
|
|
|
|
|-
| STSE
| Steel Sections
| 0020 Piece goods
|
|
|
|
|
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| STSH
| Steel Sheet
| 0020 Piece goods
|
|
|
|
|
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| STST
| Stainless Steel
| 0020 Piece goods
|
|
|
|
|
|
|
|
|-
| STWR
| Steel Wire Rod
| 0020 Piece goods
|
|
|
|
|
|
|
|
|-
| TATO
| Potatoes
| 00A4 Express, piece goods, refrigerated
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
| CZIS uses renamed Beans
|-
| TEXT
| Textile
| 0220 Piece goods, covered
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
|
|-
| TBCO
| Tobacco
| 1010 Bulk, non-pourable
|
|
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| Industries of the Caribbean
|-
| TWOD
| Tropic Wood
| 0020 Piece goods
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
| formerly intended as a default cargo
|-
| VBOD
| Vehicle bodies
| 0020 Piece goods
|
|
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| VENG
| Vehicle Engines
| 0020 Piece goods
|
|
|
|
|
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| VPTS
| Vehicle Parts
| 0024 Piece goods, express
|
|
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
| XIS: 0020 Piece goods, renamed "Parts"
|-
| WSTE
| Waste
| 0230 Piece goods, bulk, covered
|
|
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| Used by Improved Town Industries.
|-
| align="center" colspan="2" | '''Fantasy Cargos'''
| align="center" colspan="9" | these cargos are for use in fantasy or science fiction settings
|-
| BATT
| Batteries
| 0020 Piece goods
| style="background: #CC00CC; color: black" | TTD
|
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
|
|
|
|
| Toyland
|-
| BUBL
| Bubbles
| 0020 Piece goods
| style="background: #CC00CC; color: black" | TTD
|
|
|
|
|
|
| Toyland
|-
| COLA
| Cola
| 0040 Liquid
| style="background: #CC00CC; color: black" | TTD
|
|
|
|
|
|
| Toyland
|-
| CTCD
| Cotton Candy (Candyfloss)
| 0010 Bulk
| style="background: #CC00CC; color: black" | TTD
|
|
|
|
|
|
| Toyland
|-
| FZDR
| Fizzy Drinks
| 0020 Piece goods
| style="background: #CC00CC; color: black" | TTD
|
|
|
|
|
|
| Toyland
|-
| PLST
| Plastic
| 0040 Liquid
| style="background: #CC00CC; color: black" | TTD
|
|
|
|
|
|
| Toyland; see also PLAS
|-
| SWET
| Sweets (Candy)
| 0004 Express
| style="background: #CC00CC; color: black" | TTD
|
|
|
|
|
|
| Toyland
|-
| TOFF
| Toffee
| 0010 Bulk
| style="background: #CC00CC; color: black" | TTD
|
|
|
|
|
|
| Toyland
|-
| TOYS
| Toys
| 0020 Piece goods
| style="background: #CC00CC; color: black" | TTD
|
|
|
|
|
|
| Toyland
|-
| YETI
| Workers, YETI dudes
| 0404 Express, oversized
|
|
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
|
|
|
|
|
|-
| YETY
| Tired Workers, Tired YETI dudes
| 0404 Express, oversized
|
|
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
|
|
|
|
|
|-
| ELEC
| Charged Batteries (electricity from PP)
| 0020 Piece goods
|
|
|
|
|
|
| style="background: #FF0000; color: white" | CZIS
| Used as means of electricity transportation.
|-
| NODC
| Uncharged Batteries (return of batteries) aka No Direct Current
| 0020 Piece goods
|
|
|
|
|
|
| style="background: #FF0000; color: white" | CZIS
|Used as means of electricity transportation.
|-
| align="center" colspan="2" | '''Special Cargos'''
| align="center" colspan="9" | these cargos are for use outside industry sets and do not represent transporting anything
|-
| GEAR
| Locomotive regearing
| 8000 Special
|
|
|
|
|
|
|
| Using this cargo may make your vehicle set incompatible with some industry sets
use CB36 instead to set capacity to 0
|-
| align="center" colspan="2" | '''Deprecated Cargos'''
| align="center" colspan="9" | these cargos are not used by any current industry set, and are listed here for backwards compatibility
|-
| RSGR
| Raw Sugar
| 0010 Bulk
|
|
|
|
|
|
|
| Deprecated see SGBT and SGCN
|-
| SCRP
| Scrap Metal
| 0010 Piece goods
|
|
|
|
|
|
|
| Deprecated see SCMT instead
|}

<references />

An overview of FIRS cargos is avaliable [https://grf.farm/firs/code_reference_latest.html here] for the latest version. Please don't add FIRS labels here, as they have a history of being outdated or wrong, which is unhelpful to other grf authors. Thanks.

If you write or publish a NewGRF which introduces a new cargo label, please also add a comment where the new label is used.

CargoTypes

2024-10-08T22:09:54Z

Andythenorth: /* Cargo Labels */ remove outdated class

'''Cargo labels in OpenTTD'''

{{grfFrom|8}} In GRF version 8 the value to be used in all vehicle and industry properties, and in [[Action3|action 3]], is the position of the cargo label in the [[Action0/Global_Settings#Cargo_translation_table_.2809.29|cargo translation table]] included in the GRF.

{{grfTill|7}} GRF version 7 and below used different cargo properties for different properties (called "Type A" or "translated" and "Type B" or "untranslated" cargo slots), for historical reasons. This method is deprecated as it meant relying solely on cargos always using the same slots. You can see the table of Type A and Type B slots [http://newgrf-specs.tt-wiki.net/index.php?title=CargoTypes&oldid=2861 here] if you really want to.

{{ottd|15.0}} Since 15.0, a default cargo translation table corresponding to the climate (see [[CargoDefaultProps]]) is used if one is not provided. 
{{grfFrom|8}} In GRF version 8, the default translation table is 32 entries long and maps "Type B" slots to each cargo label. 
{{grfTill|7}} In GRF version 7, the default translation table is 12 entries long and uses "Type A" slots to each cargo label. 
The default translation table works just like a GRF provided table: If a cargo label is redefined in a different slot this is correctly translated, and if the cargo label is replaced the cargo type is mapped to invalid.

== Cargo Labels ==

The following cargo labels have been defined so far:

{|class="wikitable"
|-
! Label
! Cargo Description
! [[Action0Cargos#CargoClasses_.2816.29|Cargo classes]]
! colspan="8" | Usage
! Notes
|-
| align="center" colspan="2" | '''Basic Cargos'''
| align="center" colspan="10" | These cargos are present when no NewGRF is used, or in some common Industry NewGRFs
|-
| PASS
| Passengers
| 0001 Passengers
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
|
|-
| COAL
| Coal
| 0010 Bulk
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
|
|-
| MAIL
| Mail
| 0002 Mail
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
|
|-
| OIL_
| Oil
| 0040 Liquid
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
|
|-
| LVST
| Livestock
| 0020 Piece goods
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| GOOD
| Goods
| 0004 Express
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
|
|-
| GRAI
| Grain
| 0010 Bulk
| style="background: #CC00CC; color: black" | TTD
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
| Temperate; see also WHEA, MAIZ, CERE. YETI & OTIS: 0210 Covered, bulk
|-
| WOOD
| Wood
| 0020 Piece goods
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
| Named Logs in some industry sets (FIRS, 2TT)
|-
| IORE
| Iron Ore
| 0010 Bulk
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
|
|-
| STEL
| Steel
| 0020 Piece goods
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
| YETI: Renamed "Balls of Steel", OTIS: Renamed "Metal"
|-
| VALU
| Valuables
| 0008 Armoured
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
| Temperate; see also GOLD, DIAM
|-
| PAPR
| Paper
| 0020 Piece goods
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
| OTIS: 0220 Covered, piece goods
|-
| WHEA
| Wheat
| 0010 Bulk
| style="background: #CC00CC; color: black" | TTD
|
|
|
|
|
|
|
| Arctic; see also GRAI, MAIZ, CERE
|-
| FOOD
| Food
| 0084 Express, refrigerated
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
| YETI: 00A0 Refrigerated, piece goods
|-
| GOLD
| Gold
| 0008 Armoured
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|
|
|
| Arctic; see also VALU, DIAM
|-
| RUBR
| Rubber
| 0040 Liquid
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
|
|-
| FRUT
| Fruit
| 0090 Bulk, refrigerated
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
| FIRS & XIS: 00A4 Express, piece goods, refrigerated, YETI: 00A0 Piece goods, covered.
|-
| MAIZ
| Maize
| 0010 Bulk
| style="background: #CC00CC; color: black" | TTD
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
| Tropic; see also GRAI, WHEA, CERE. OTIS: Renamed "Animal Feed"
|-
| CORE
| Copper Ore
| 0010 Bulk
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| WATR
| Water
| 0040 Liquid
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
| OTIS: 0044 Express, liquid
|-
| DIAM
| Diamonds
| 0008 Armoured
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
| Tropic; see also VALU, GOLD
|-
| SUGR
| Sugar
| 0010 Bulk
| style="background: #CC00CC; color: black" | TTD
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| Toyland. FIRS: 0030 Bulk, piece goods
|-
| AORE
| Bauxite (Aluminium ore)
| 0010 Bulk
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| BDMT
| Building Materials
| 0220 Piece goods, covered/sheltered
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
| FIRS & XIS: 0030 Bulk, piece goods. YETI: 0020 Piece goods.
|-
| BEAN
| Beans
| 0010 Bulk
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
| CZIS renamed to Potatoes
|-
| BEER
| Alcohol
| 0064 Express, piece goods, liquids
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
|
|-
| BOOM
| Explosives
| 0024 Express, piece goods
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
| OTIS: 0124 Express, Piece goods, hazardous
|-
| BRCK
| Bricks
| 0020 Piece goods
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|
|
|
|
|
|-
| CBLK
| Carbon Black
| 0230 Piece goods, bulk, covered/sheltered
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|
|
|
|
|-
| CERA
| Ceramics
| 0020 Piece goods
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|
|
|
|
|
|-
| CERE
| Cereals
| 0210 Bulk, covered/sheltered
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|
|
|
|
| ECS: <ref name="ecs_cargo_change" />
|-
| CLAY
| Clay
| 0210 Bulk covered/sheltered
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| CMNT
| Cement
| 0210 Bulk covered/sheltered
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| COPR
| Copper
| 0020 Piece goods
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| CSTI
| Cast Iron
| 0020 Piece goods
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|
|
|
|
|-
| CTAR
| Coal Tar
| 0140 Liquids, hazardous
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|
|
|
|
|-
| DYES
| Dyes
| 0060 Piece goods, liquids
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|
|
|
|
|
|-
| ENSP
| Engineering Supplies
| 0024 Express, piece goods
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
| 2TT Industries of the Caribbean: named Machinery
|-
| FECR
| Ferrochrome
| 0010 Bulk
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|
|
|
|
|-
| FERT
| Fertiliser
| 0030 Bulk, piece goods
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| FIRS: 0024 Express, piece goods. OTIS: 0034 Express, piece goods, bulk. XIS: 0230 Covered, piece goods, bulk. ECS: <ref name="ecs_cargo_change" />
|-
| FICR
| Fibre crops
| 0030 Bulk, piece goods
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
| OTIS: 0230 Piece goods, bulk, covered/sheltered, renamed "Cotton"
|-
| FISH
| Fish
| 0084 Express, refrigerated
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
|
|-
| FMSP
| Farm Supplies
| 0024 Express, piece goods
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| GLAS
| Glass
| 0420 Piece goods, oversized
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
| style="background: #FF0000; color: white" | CZIS
| OTIS: 0410 Piece goods, bulk
|-
| GRVL
| Stone
| 0010 Bulk
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
| Renamed from "Gravel / Ballast" XIS: Renamed "Aggregate"
|-
| JAVA
| Coffee
| 0024 Piece goods, express
|
|
| style="background: #1AD74C; color: black" | [[ttwiki:FIRS|FIRS]]
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| Units in FIRS are 'bags'
|-
| KAOL
| Kaolin (China Clay)
| 0250 Bulk, liquids, covered
|
|
| style="background: #1AD74C; color: black" | [[ttwiki:FIRS|FIRS]]
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
| XIS: Renamed "Lithium"
|-
| LIME
| Lime stone
| 0010 Bulk
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| MILK
| Milk
| 00C4 Express, liquid, refrigerated
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| OLSD
| Oil seed
| 0210 Bulk, covered/sheltered
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|
|
|
|
| ECS: <ref name="ecs_cargo_change" />
|-
| PEAT
| Peat
| 0010 Bulk
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
| XIS: Renamed "Biomass"
|-
| PETR
| Petrol / Fuel Oil
| 0040 Liquid
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
| OTIS: 0130 Hazardous, liquid
|-
| PHOS
| Phosphate
| 0010 Bulk
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
| XIS: Renamed "Oil sands"
|-
| PLAS
| Plastic
| 0060 Piece goods, liquid
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|
|
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| PORE
| Pyrite Ore
| 0010 Bulk
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
| XIS: Renamed "Zinc ore"
|-
| POTA
| Potash
| 0210 Bulk, covered/sheltered
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|
|
|
| FIRS: 0010 Bulk. ECS: <ref name="ecs_cargo_change" />
|-
| RFPR
| Refined products
| 0040 Liquid
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
| OTIS: renamed "Sewage", XIS: renamed "Petrochemicals", FIRS4: 0160 Liquid, Piece Goods, Hazardous, renamed "Chemicals"
|-
| SAND
| Sand
| 0010 Bulk
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| SCMT
| Scrap Metal
| 1010 Bulk, non-pourable
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
| OTIS: Renamed "Waste/Garbage"
|-
| SULP
| Sulphur
| 0250 Bulk, liquid, covered/sheltered.
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
| ECS: 0210 Bulk, covered/sheltered <ref name="ecs_cargo_change">ECS cargo classes changed as of Dec 31, 2010</ref>
|-
| TOUR
| Tourists
| 0005 Passengers, express
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| ECS; see also OTI2
|-
| TYRE
| Tyres
| 0020 Piece goods
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| URAN
| Uranium
| 0110 Bulk, hazardous
|
|
|
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| 2TT: Piece goods, hazardous
|-
| VEHI
| Vehicles
| 0420 Piece goods, oversized
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
| XIS: 0020 Piece goods. OTIS: 0020 Piece goods, renamed "Cars"
|-
| WDPR
| Wood Products
| 0030 Bulk, piece goods
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
| XIS & OTIS: Renamed "Timber"
|-
| WOOL
| Wool
| 0220 Piece goods, covered/sheltered
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
| ECS: <ref name="ecs_cargo_change" />
|-
| ZINC
| Zinc
| 0020 Piece goods
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
|
|-
| align="center" colspan="2" | '''Extended Cargos'''
| align="center" colspan="10" | these cargos are only present in rare/specialized situations
|-
| ACID
| Acid
| 0140 Liquids, hazardous
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| ALUM
| Aluminium
| 0020 Piece goods
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|
|
| style="background: #FF0000; color: white" | CZIS
| FIRS; See also METL
|-
| BAKE
| Flour
| 0A30 Bulk, powderized, piece goods, covered
|
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
|
|-
| CASS
| Cassava
| 0010 Bulk
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|
|
|
|
|-
| CHLO
| Chlorine
| 0140 Liquids, hazardous
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
|
|-
| CHSE
| Cheese
| 00C4 Express, liquid, refrigerated
|
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
|
|-
| CIGR
| Cigars
| 0024 Piece goods, express
|
|
|
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| Industries of the Caribbean
|-
| COAT
| Paints & Coatings
| 0060 Piece goods, liquids
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| 2TT Lumberjack Industries: renamed Varnish
|-
| COBL
| Cobalt
| 0020 Piece goods
|
|
|
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| Industries of the Caribbean
|-
| COKE
| Coke
| 0010 Bulk
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| ELTR
| Electricity
| 8000 Special
|
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
|CZIS uses its own labels... see ELEC and NODC
|-
| EOIL
| Edible Oil
| 0060 Piece goods, liquids
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
|
|-
| FRVG
| Fruit (and optionally Vegetables)
| 00A4 Express, piece goods, refrigerated
|
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
| Deprecated FIRS cargo. Replaced by FRUT for FIRS > v1.3.0
|-
| FUEL
| Natural Gas
| 0140 Liquid, hazardous
|
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| Use PETR for refined-oil fuel
|-
| FURN
| Furniture
| 0230 Piece goods, bulk, covered
|
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| IRON
| Pig Iron
| 0020 Piece goods
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
|
|-
| LYE_
| Sodium Hydroxide (Lye)
| 0140 Liquids, hazardous
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|
|
|
|
|-
| MEAT
| Meat
| 00A4 Express, piece goods, refrigerated
|
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
|
|-
| METL
| Metal
| 0020 Piece goods
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
| XIS: Renamed "Aluminium"; See also ALUM
|-
| MNO2
| Manganese
| 0010 Bulk
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
|
|-
| MNSP
| Manufacturing Supplies
| 0024 Piece goods, express
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| XIS: Renamed "Packaging"
|-
| MOLS
| Molasses
| 0040 Liquid
|
|
|
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| Industries of the Caribbean
|-
| MPTS
| Machine parts
| 0220 Covered, piece goods
|
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
|
|-
| NH3_
| Ammonia
| 0140 Liquids, hazardous
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| NHNO
| [https://en.wikipedia.org/wiki/Ammonium_nitrate NH4NO3 chemical]
| 0130 Hazardous, bulk, piece goods
|
|
|
|
|
|
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| NUTS
| Nuts
| 0020 Piece goods
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
|
|-
| NICK
| Nickel
| 0010 Bulk
|
|
|
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
|
|-
| NITR
| Nitrate
| 0010 Bulk
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| NKOR
| Nickel ore
| 0010 Bulk
|
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| OTIS: Renamed "Nickel"
|-
| NUKF
| Nuclear fuel
| Piece goods, hazardous
|
|
|
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| Improved Town Industries
|-
| NUKW
| Nuclear waste
| Piece goods, hazardous
|
|
|
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| Improved Town Industries
|-
| OILI
| Oil (imported)
| 0040 Liquid
|
|
|
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| Industries of the Caribbean
|-
| OILD
| Oil (domestic)
| 0040 Liquid
|
|
|
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| Industries of the Caribbean
|-
| OTI1
| Workers
| 0001 Passengers
|
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
|
|-
| OTI2
| Tourists
| 0001 Passengers
|
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
|
|-
| OYST
| Oysters
| 00A4 Express, piece goods, refrigerated
|
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
|
|-
| O2__
| Oxygen
| 0040 Liquids
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|
|
|
|
|-
| PACK
| Packaging
| 0020 Piece goods
|
|
|
|
|
|
|
| style="background: #FF0000; color: white" | CZIS
|Packaging used mostly for food production.
|-
| PCL_
| Parcels
| 0006 Express, mail
|
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
|
|-
| PIPE
| Pipe
| 0020 Piece goods
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
|
|-
| POWR
| Electrical Parts
| 0020 Piece goods
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
| OTIS: 0220 Covered, piece goods, renamed "Electrical Machines". XIS and CZIS: Renamed "Electrical Machines"
|-
| QLME
| Quicklime
| 0210 Bulk, covered/sheltered
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| RCYC
| Recyclables
| 0030 Bulk, piece goods
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
|
|-
| SALT
| Salt
| 0010 Bulk
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
|
|-
| SASH
| Soda Ash
| 0210 Bulk, covered/sheltered
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
|
|-
| SEED
| Seed
| 0230 Piece goods, bulk, covered
|
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
|
|-
| SESP
| Marine Supplies
| 0024 Express, piece goods
|
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
|
|-
| SGBT
| Sugar beet
| 0010 Bulk
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
| not in tropical
|-
| SGCN
| Sugarcane
| 1010 Bulk, non-pourable
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| only tropical
|-
| SLAG
| Slag
| 0010 Bulk
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| SOAP
| Cleaning Agents
| 0060 Piece goods, liquids
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|
|
|
|
|-
| STAL
| Alloy Steel
| 0020 Piece goods
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| STCB
| Carbon Steel
| 0020 Piece goods
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|
|
|
|
|-
| STSE
| Steel Sections
| 0020 Piece goods
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| STSH
| Steel Sheet
| 0020 Piece goods
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| STST
| Stainless Steel
| 0020 Piece goods
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|
|
|
|
|-
| STWR
| Steel Wire Rod
| 0020 Piece goods
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|
|
|
|
|-
| TATO
| Potatoes
| 00A4 Express, piece goods, refrigerated
|
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
| CZIS uses renamed Beans
|-
| TEXT
| Textile
| 0220 Piece goods, covered
|
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
|
|-
| TBCO
| Tobacco
| 1010 Bulk, non-pourable
|
|
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
|
| Industries of the Caribbean
|-
| TWOD
| Tropic Wood
| 0020 Piece goods
|
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
| formerly intended as a default cargo
|-
| VBOD
| Vehicle bodies
| 0020 Piece goods
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| VENG
| Vehicle Engines
| 0020 Piece goods
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| VPTS
| Vehicle Parts
| 0024 Piece goods, express
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
| XIS: 0020 Piece goods, renamed "Parts"
|-
| WSTE
| Waste
| 0230 Piece goods, bulk, covered
|
|
|
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| Used by Improved Town Industries. Deprecated in FIRS.
|-
| align="center" colspan="2" | '''Fantasy Cargos'''
| align="center" colspan="10" | these cargos are for use in fantasy or science fiction settings
|-
| BATT
| Batteries
| 0020 Piece goods
| style="background: #CC00CC; color: black" | TTD
|
|
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
|
|
|
|
| Toyland
|-
| BUBL
| Bubbles
| 0020 Piece goods
| style="background: #CC00CC; color: black" | TTD
|
|
|
|
|
|
|
| Toyland
|-
| COLA
| Cola
| 0040 Liquid
| style="background: #CC00CC; color: black" | TTD
|
|
|
|
|
|
|
| Toyland
|-
| CTCD
| Cotton Candy (Candyfloss)
| 0010 Bulk
| style="background: #CC00CC; color: black" | TTD
|
|
|
|
|
|
|
| Toyland
|-
| FZDR
| Fizzy Drinks
| 0020 Piece goods
| style="background: #CC00CC; color: black" | TTD
|
|
|
|
|
|
|
| Toyland
|-
| PLST
| Plastic
| 0040 Liquid
| style="background: #CC00CC; color: black" | TTD
|
|
|
|
|
|
|
| Toyland; see also PLAS
|-
| SWET
| Sweets (Candy)
| 0004 Express
| style="background: #CC00CC; color: black" | TTD
|
|
|
|
|
|
|
| Toyland
|-
| TOFF
| Toffee
| 0010 Bulk
| style="background: #CC00CC; color: black" | TTD
|
|
|
|
|
|
|
| Toyland
|-
| TOYS
| Toys
| 0020 Piece goods
| style="background: #CC00CC; color: black" | TTD
|
|
|
|
|
|
|
| Toyland
|-
| YETI
| Workers, YETI dudes
| 0404 Express, oversized
|
|
|
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
|
|
|
|
|
|-
| YETY
| Tired Workers, Tired YETI dudes
| 0404 Express, oversized
|
|
|
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
|
|
|
|
|
|-
| ELEC
| Charged Batteries (electricity from PP)
| 0020 Piece goods
|
|
|
|
|
|
|
| style="background: #FF0000; color: white" | CZIS
| Used as means of electricity transportation.
|-
| NODC
| Uncharged Batteries (return of batteries) aka No Direct Current
| 0020 Piece goods
|
|
|
|
|
|
|
| style="background: #FF0000; color: white" | CZIS
|Used as means of electricity transportation.
|-
| align="center" colspan="2" | '''Special Cargos'''
| align="center" colspan="10" | these cargos are for use outside industry sets and do not represent transporting anything
|-
| GEAR
| Locomotive regearing
| 8000 Special
|
|
|
|
|
|
|
|
| Using this cargo may make your vehicle set incompatible with some industry sets
use CB36 instead to set capacity to 0
|-
| align="center" colspan="2" | '''Deprecated Cargos'''
| align="center" colspan="10" | these cargos are not used by any current industry set, and are listed here for backwards compatibility
|-
| RSGR
| Raw Sugar
| 0010 Bulk
|
|
|
|
|
|
|
|
| Deprecated in FIRS. See SGBT and SGCN
|-
| SCRP
| Scrap Metal
| 0010 Piece goods
|
|
|
|
|
|
|
|
| Deprecated in FIRS. See SCMT instead
|}

<references />

If you write or publish a NewGRF which introduces a new cargo label, please also add a comment where the new label is used.

CargoTypes

2024-10-08T22:09:11Z

Andythenorth: remove 'blindly' not helpful language here

'''Cargo labels in OpenTTD'''

{{grfFrom|8}} In GRF version 8 the value to be used in all vehicle and industry properties, and in [[Action3|action 3]], is the position of the cargo label in the [[Action0/Global_Settings#Cargo_translation_table_.2809.29|cargo translation table]] included in the GRF.

{{grfTill|7}} GRF version 7 and below used different cargo properties for different properties (called "Type A" or "translated" and "Type B" or "untranslated" cargo slots), for historical reasons. This method is deprecated as it meant relying solely on cargos always using the same slots. You can see the table of Type A and Type B slots [http://newgrf-specs.tt-wiki.net/index.php?title=CargoTypes&oldid=2861 here] if you really want to.

{{ottd|15.0}} Since 15.0, a default cargo translation table corresponding to the climate (see [[CargoDefaultProps]]) is used if one is not provided. 
{{grfFrom|8}} In GRF version 8, the default translation table is 32 entries long and maps "Type B" slots to each cargo label. 
{{grfTill|7}} In GRF version 7, the default translation table is 12 entries long and uses "Type A" slots to each cargo label. 
The default translation table works just like a GRF provided table: If a cargo label is redefined in a different slot this is correctly translated, and if the cargo label is replaced the cargo type is mapped to invalid.

== Cargo Labels ==

The following cargo labels have been defined so far:

{|class="wikitable"
|-
! Label
! Cargo Description
! [[Action0Cargos#CargoClasses_.2816.29|Cargo classes]]
! colspan="8" | Usage
! Notes
|-
| align="center" colspan="2" | '''Basic Cargos'''
| align="center" colspan="10" | These cargos are present when no NewGRF is used, or in some common Industry NewGRFs
|-
| PASS
| Passengers
| 0001 Passengers
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
|
|-
| COAL
| Coal
| 0010 Bulk
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
|
|-
| MAIL
| Mail
| 0002 Mail
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
|
|-
| OIL_
| Oil
| 0040 Liquid
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
|
|-
| LVST
| Livestock
| 0020 Piece goods
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| GOOD
| Goods
| 0004 Express
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
|
|-
| GRAI
| Grain
| 0010 Bulk
| style="background: #CC00CC; color: black" | TTD
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
| Temperate; see also WHEA, MAIZ, CERE. YETI & OTIS: 0210 Covered, bulk
|-
| WOOD
| Wood
| 0020 Piece goods
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
| Named Logs in some industry sets (FIRS, 2TT)
|-
| IORE
| Iron Ore
| 0010 Bulk
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
|
|-
| STEL
| Steel
| 0020 Piece goods
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
| YETI: Renamed "Balls of Steel", OTIS: Renamed "Metal"
|-
| VALU
| Valuables
| 0008 Armoured
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
| Temperate; see also GOLD, DIAM
|-
| PAPR
| Paper
| 0020 Piece goods
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
| OTIS: 0220 Covered, piece goods
|-
| WHEA
| Wheat
| 0010 Bulk
| style="background: #CC00CC; color: black" | TTD
|
|
|
|
|
|
|
| Arctic; see also GRAI, MAIZ, CERE
|-
| FOOD
| Food
| 0084 Express, refrigerated
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
| YETI: 00A0 Refrigerated, piece goods
|-
| GOLD
| Gold
| 0008 Armoured
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|
|
|
| Arctic; see also VALU, DIAM
|-
| RUBR
| Rubber
| 0040 Liquid
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
|
|-
| FRUT
| Fruit
| 0090 Bulk, refrigerated
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
| FIRS & XIS: 00A4 Express, piece goods, refrigerated, YETI: 00A0 Piece goods, covered.
|-
| MAIZ
| Maize
| 0010 Bulk
| style="background: #CC00CC; color: black" | TTD
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
| Tropic; see also GRAI, WHEA, CERE. OTIS: Renamed "Animal Feed"
|-
| CORE
| Copper Ore
| 0010 Bulk
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| WATR
| Water
| 0040 Liquid
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
| OTIS: 0044 Express, liquid
|-
| DIAM
| Diamonds
| 0008 Armoured
| style="background: #CC00CC; color: black" | TTD
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
| Tropic; see also VALU, GOLD
|-
| SUGR
| Sugar
| 0010 Bulk
| style="background: #CC00CC; color: black" | TTD
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| Toyland. FIRS: 0030 Bulk, piece goods
|-
| AORE
| Bauxite (Aluminium ore)
| 0010 Bulk
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| BDMT
| Building Materials
| 0220 Piece goods, covered/sheltered
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
| FIRS & XIS: 0030 Bulk, piece goods. YETI: 0020 Piece goods.
|-
| BEAN
| Beans
| 0010 Bulk
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
| CZIS renamed to Potatoes
|-
| BEER
| Alcohol
| 0064 Express, piece goods, liquids
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
|
|-
| BOOM
| Explosives
| 0024 Express, piece goods
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
| OTIS: 0124 Express, Piece goods, hazardous
|-
| BRCK
| Bricks
| 0020 Piece goods
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|
|
|
|
|
|-
| CBLK
| Carbon Black
| 0230 Piece goods, bulk, covered/sheltered
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|
|
|
|
|-
| CERA
| Ceramics
| 0020 Piece goods
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|
|
|
|
|
|-
| CERE
| Cereals
| 0210 Bulk, covered/sheltered
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|
|
|
|
| ECS: <ref name="ecs_cargo_change" />
|-
| CLAY
| Clay
| 0210 Bulk covered/sheltered
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| CMNT
| Cement
| 0210 Bulk covered/sheltered
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| COPR
| Copper
| 0020 Piece goods
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| CSTI
| Cast Iron
| 0020 Piece goods
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|
|
|
|
|-
| CTAR
| Coal Tar
| 0140 Liquids, hazardous
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|
|
|
|
|-
| DYES
| Dyes
| 0060 Piece goods, liquids
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|
|
|
|
|
|-
| ENSP
| Engineering Supplies
| 0024 Express, piece goods
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
| 2TT Industries of the Caribbean: named Machinery
|-
| FECR
| Ferrochrome
| 0010 Bulk
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|
|
|
|
|-
| FERT
| Fertiliser
| 0030 Bulk, piece goods
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| FIRS: 0024 Express, piece goods. OTIS: 0034 Express, piece goods, bulk. XIS: 0230 Covered, piece goods, bulk. ECS: <ref name="ecs_cargo_change" />
|-
| FICR
| Fibre crops
| 0030 Bulk, piece goods
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
| OTIS: 0230 Piece goods, bulk, covered/sheltered, renamed "Cotton"
|-
| FISH
| Fish
| 0084 Express, refrigerated
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
|
|-
| FMSP
| Farm Supplies
| 0024 Express, piece goods
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| GLAS
| Glass
| 0420 Piece goods, oversized
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
| style="background: #FF0000; color: white" | CZIS
| OTIS: 0410 Piece goods, bulk
|-
| GRVL
| Stone
| 0010 Bulk
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
| Renamed from "Gravel / Ballast" XIS: Renamed "Aggregate"
|-
| JAVA
| Coffee
| 0024 Piece goods, express
|
|
| style="background: #1AD74C; color: black" | [[ttwiki:FIRS|FIRS]]
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| Units in FIRS are 'bags'
|-
| KAOL
| Kaolin (China Clay)
| 0250 Bulk, liquids, covered
|
|
| style="background: #1AD74C; color: black" | [[ttwiki:FIRS|FIRS]]
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
| XIS: Renamed "Lithium"
|-
| LIME
| Lime stone
| 0010 Bulk
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| MILK
| Milk
| 00C4 Express, liquid, refrigerated
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| OLSD
| Oil seed
| 0210 Bulk, covered/sheltered
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|
|
|
|
| ECS: <ref name="ecs_cargo_change" />
|-
| PEAT
| Peat
| 0010 Bulk
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
| XIS: Renamed "Biomass"
|-
| PETR
| Petrol / Fuel Oil
| 0040 Liquid
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
| OTIS: 0130 Hazardous, liquid
|-
| PHOS
| Phosphate
| 0010 Bulk
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
| XIS: Renamed "Oil sands"
|-
| PLAS
| Plastic
| 0060 Piece goods, liquid
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|
|
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| PORE
| Pyrite Ore
| 0010 Bulk
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
| XIS: Renamed "Zinc ore"
|-
| POTA
| Potash
| 0210 Bulk, covered/sheltered
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|
|
|
| FIRS: 0010 Bulk. ECS: <ref name="ecs_cargo_change" />
|-
| RFPR
| Refined products
| 0040 Liquid
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
| OTIS: renamed "Sewage", XIS: renamed "Petrochemicals", FIRS4: 0160 Liquid, Piece Goods, Hazardous, renamed "Chemicals"
|-
| SAND
| Sand
| 0010 Bulk
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| SCMT
| Scrap Metal
| 1010 Bulk, non-pourable
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
| OTIS: Renamed "Waste/Garbage"
|-
| SULP
| Sulphur
| 0250 Bulk, liquid, covered/sheltered.
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
| ECS: 0210 Bulk, covered/sheltered <ref name="ecs_cargo_change">ECS cargo classes changed as of Dec 31, 2010</ref>
|-
| TOUR
| Tourists
| 0005 Passengers, express
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| ECS; see also OTI2
|-
| TYRE
| Tyres
| 0020 Piece goods
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| URAN
| Uranium
| 0110 Bulk, hazardous
|
|
|
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| 2TT: Piece goods, hazardous
|-
| VEHI
| Vehicles
| 0420 Piece goods, oversized
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
| XIS: 0020 Piece goods. OTIS: 0020 Piece goods, renamed "Cars"
|-
| WDPR
| Wood Products
| 0030 Bulk, piece goods
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
| XIS & OTIS: Renamed "Timber"
|-
| WOOL
| Wool
| 0220 Piece goods, covered/sheltered
|
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
| ECS: <ref name="ecs_cargo_change" />
|-
| ZINC
| Zinc
| 0020 Piece goods
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
|
|-
| align="center" colspan="2" | '''Extended Cargos'''
| align="center" colspan="10" | these cargos are only present in rare/specialized situations
|-
| ACID
| Acid
| 0140 Liquids, hazardous
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| ALUM
| Aluminium
| 0020 Piece goods
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|
|
| style="background: #FF0000; color: white" | CZIS
| FIRS; See also METL
|-
| BAKE
| Flour
| 0A30 Bulk, powderized, piece goods, covered
|
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
|
|-
| CASS
| Cassava
| 0010 Bulk
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|
|
|
|
|-
| CHLO
| Chlorine
| 0140 Liquids, hazardous
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
|
|-
| CHSE
| Cheese
| 00C4 Express, liquid, refrigerated
|
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
|
|-
| CIGR
| Cigars
| 0024 Piece goods, express
|
|
|
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| Industries of the Caribbean
|-
| COAT
| Paints & Coatings
| 0060 Piece goods, liquids
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| 2TT Lumberjack Industries: renamed Varnish
|-
| COBL
| Cobalt
| 0020 Piece goods
|
|
|
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| Industries of the Caribbean
|-
| COKE
| Coke
| 0010 Bulk
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| ELTR
| Electricity
| 8000 Special
|
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
|CZIS uses its own labels... see ELEC and NODC
|-
| EOIL
| Edible Oil
| 0060 Piece goods, liquids
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
|
|-
| FRVG
| Fruit (and optionally Vegetables)
| 00A4 Express, piece goods, refrigerated
|
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
| Deprecated FIRS cargo. Replaced by FRUT for FIRS > v1.3.0
|-
| FUEL
| Natural Gas
| 0140 Liquid, hazardous
|
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| Use PETR for refined-oil fuel
|-
| FURN
| Furniture
| 0230 Piece goods, bulk, covered
|
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| IRON
| Pig Iron
| 0020 Piece goods
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
|
|-
| LYE_
| Sodium Hydroxide (Lye)
| 0140 Liquids, hazardous
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|
|
|
|
|-
| MEAT
| Meat
| 00A4 Express, piece goods, refrigerated
|
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
|
|-
| METL
| Metal
| 0020 Piece goods
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
| XIS: Renamed "Aluminium"; See also ALUM
|-
| MNO2
| Manganese
| 0010 Bulk
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
|
|-
| MNSP
| Manufacturing Supplies
| 0024 Piece goods, express
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| XIS: Renamed "Packaging"
|-
| MOLS
| Molasses
| 0040 Liquid
|
|
|
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| Industries of the Caribbean
|-
| MPTS
| Machine parts
| 0220 Covered, piece goods
|
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
|
|-
| NH3_
| Ammonia
| 0140 Liquids, hazardous
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| NHNO
| [https://en.wikipedia.org/wiki/Ammonium_nitrate NH4NO3 chemical]
| 0130 Hazardous, bulk, piece goods
|
|
|
|
|
|
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| NUTS
| Nuts
| 0020 Piece goods
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
|
|-
| NICK
| Nickel
| 0010 Bulk
|
|
|
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
|
|-
| NITR
| Nitrate
| 0010 Bulk
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| NKOR
| Nickel ore
| 0010 Bulk
|
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| OTIS: Renamed "Nickel"
|-
| NUKF
| Nuclear fuel
| Piece goods, hazardous
|
|
|
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| Improved Town Industries
|-
| NUKW
| Nuclear waste
| Piece goods, hazardous
|
|
|
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| Improved Town Industries
|-
| OILI
| Oil (imported)
| 0040 Liquid
|
|
|
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| Industries of the Caribbean
|-
| OILD
| Oil (domestic)
| 0040 Liquid
|
|
|
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| Industries of the Caribbean
|-
| OTI1
| Workers
| 0001 Passengers
|
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
|
|-
| OTI2
| Tourists
| 0001 Passengers
|
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
|
|-
| OYST
| Oysters
| 00A4 Express, piece goods, refrigerated
|
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
|
|-
| O2__
| Oxygen
| 0040 Liquids
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|
|
|
|
|-
| PACK
| Packaging
| 0020 Piece goods
|
|
|
|
|
|
|
| style="background: #FF0000; color: white" | CZIS
|Packaging used mostly for food production.
|-
| PCL_
| Parcels
| 0006 Express, mail
|
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
|
|-
| PIPE
| Pipe
| 0020 Piece goods
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
| style="background: #FF0000; color: white" | CZIS
|
|-
| POWR
| Electrical Parts
| 0020 Piece goods
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
| OTIS: 0220 Covered, piece goods, renamed "Electrical Machines". XIS and CZIS: Renamed "Electrical Machines"
|-
| QLME
| Quicklime
| 0210 Bulk, covered/sheltered
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| RCYC
| Recyclables
| 0030 Bulk, piece goods
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
|
|-
| SALT
| Salt
| 0010 Bulk
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
|
|-
| SASH
| Soda Ash
| 0210 Bulk, covered/sheltered
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
|
|
|-
| SEED
| Seed
| 0230 Piece goods, bulk, covered
|
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
|
|-
| SESP
| Marine Supplies
| 0024 Express, piece goods
|
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
|
|-
| SGBT
| Sugar beet
| 0010 Bulk
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
| not in tropical
|-
| SGCN
| Sugarcane
| 1010 Bulk, non-pourable
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| only tropical
|-
| SLAG
| Slag
| 0010 Bulk
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| SOAP
| Cleaning Agents
| 0060 Piece goods, liquids
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|
|
|
|
|-
| STAL
| Alloy Steel
| 0020 Piece goods
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| STCB
| Carbon Steel
| 0020 Piece goods
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|
|
|
|
|-
| STSE
| Steel Sections
| 0020 Piece goods
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| STSH
| Steel Sheet
| 0020 Piece goods
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| STST
| Stainless Steel
| 0020 Piece goods
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|
|
|
|
|-
| STWR
| Steel Wire Rod
| 0020 Piece goods
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|
|
|
|
|-
| TATO
| Potatoes
| 00A4 Express, piece goods, refrigerated
|
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
| CZIS uses renamed Beans
|-
| TEXT
| Textile
| 0220 Piece goods, covered
|
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
|
|-
| TBCO
| Tobacco
| 1010 Bulk, non-pourable
|
|
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
|
| Industries of the Caribbean
|-
| TWOD
| Tropic Wood
| 0020 Piece goods
|
|
|
|
| style="background: #D1D1D1; color: black" | [[ttwiki:OTIS|OTIS]]
|
|
|
| formerly intended as a default cargo
|-
| VBOD
| Vehicle bodies
| 0020 Piece goods
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| VENG
| Vehicle Engines
| 0020 Piece goods
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|
|
| style="background: #FF0000; color: white" | CZIS
|
|-
| VPTS
| Vehicle Parts
| 0024 Piece goods, express
|
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
| style="background: #80A0D0; color: white" | [[ttwiki:XIS|XIS]]
|
| style="background: #FF0000; color: white" | CZIS
| XIS: 0020 Piece goods, renamed "Parts"
|-
| WSTE
| Waste
| 0230 Piece goods, bulk, covered
|
|
|
|
|
|
| style="background: #B4A7D6; color: white" | [[ttwiki:2TT|2TT]]
|
| Used by Improved Town Industries. Deprecated in FIRS.
|-
| align="center" colspan="2" | '''Fantasy Cargos'''
| align="center" colspan="10" | these cargos are for use in fantasy or science fiction settings
|-
| BATT
| Batteries
| 0020 Piece goods
| style="background: #CC00CC; color: black" | TTD
|
|
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
|
|
|
|
| Toyland
|-
| BUBL
| Bubbles
| 0020 Piece goods
| style="background: #CC00CC; color: black" | TTD
|
|
|
|
|
|
|
| Toyland
|-
| COLA
| Cola
| 0040 Liquid
| style="background: #CC00CC; color: black" | TTD
|
|
|
|
|
|
|
| Toyland
|-
| CTCD
| Cotton Candy (Candyfloss)
| 0010 Bulk
| style="background: #CC00CC; color: black" | TTD
|
|
|
|
|
|
|
| Toyland
|-
| FZDR
| Fizzy Drinks
| 0020 Piece goods
| style="background: #CC00CC; color: black" | TTD
|
|
|
|
|
|
|
| Toyland
|-
| PLST
| Plastic
| 0040 Liquid
| style="background: #CC00CC; color: black" | TTD
|
|
|
|
|
|
|
| Toyland; see also PLAS
|-
| SWET
| Sweets (Candy)
| 0004 Express
| style="background: #CC00CC; color: black" | TTD
|
|
|
|
|
|
|
| Toyland
|-
| TOFF
| Toffee
| 0010 Bulk
| style="background: #CC00CC; color: black" | TTD
|
|
|
|
|
|
|
| Toyland
|-
| TOYS
| Toys
| 0020 Piece goods
| style="background: #CC00CC; color: black" | TTD
|
|
|
|
|
|
|
| Toyland
|-
| YETI
| Workers, YETI dudes
| 0404 Express, oversized
|
|
|
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
|
|
|
|
|
|-
| YETY
| Tired Workers, Tired YETI dudes
| 0404 Express, oversized
|
|
|
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
|
|
|
|
|
|-
| ELEC
| Charged Batteries (electricity from PP)
| 0020 Piece goods
|
|
|
|
|
|
|
| style="background: #FF0000; color: white" | CZIS
| Used as means of electricity transportation.
|-
| NODC
| Uncharged Batteries (return of batteries) aka No Direct Current
| 0020 Piece goods
|
|
|
|
|
|
|
| style="background: #FF0000; color: white" | CZIS
|Used as means of electricity transportation.
|-
| align="center" colspan="2" | '''Special Cargos'''
| align="center" colspan="10" | these cargos are for use outside industry sets and do not represent transporting anything
|-
| DFLT
| 'Default'
| ---- None
|
|
|
|
|
|
|
|
| Used by andythenorth to identify default cargo graphics in newgrfs that use code/graphics generation.
Not intended to be used as an actual cargo in translation tables.
|-
| GEAR
| Locomotive regearing
| 8000 Special
|
|
|
|
|
|
|
|
| Using this cargo may make your vehicle set incompatible with some industry sets
use CB36 instead to set capacity to 0
|-
| align="center" colspan="2" | '''Deprecated Cargos'''
| align="center" colspan="10" | these cargos are not used by any current industry set, and are listed here for backwards compatibility
|-
| RSGR
| Raw Sugar
| 0010 Bulk
|
|
|
|
|
|
|
|
| Deprecated in FIRS. See SGBT and SGCN
|-
| SCRP
| Scrap Metal
| 0010 Piece goods
|
|
|
|
|
|
|
|
| Deprecated in FIRS. See SCMT instead
|}

<references />

If you write or publish a NewGRF which introduces a new cargo label, please also add a comment where the new label is used.

NML:Cargos

2024-10-06T09:51:56Z

Andythenorth: /* Cargo classes */ - note about CC_NON_POURABLE and CC_NEO_BULK

{{NMLNavPropVarCB}}

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

==Cargo properties==

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

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

===Cargo classes===

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

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

===Cargo effects on town growth===

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

If no cargos in the game are defined as TOWNGROWTH_FOOD, towns above the snowline will not require food to grow. If no cargos in the game are defined as TOWNGROWTH_FOOD or TOWNGROWTH_WATER, 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.

There are some additional effects of these flags on subsidies and town cargo transport statistics. See the nfo docs for details: https://newgrf-specs.tt-wiki.net/wiki/Action0/Cargos#Substitute_type_and_multiplier_for_town_growth_.2818.2C_19.29

===Town production effect===

{| class="wikitable sortable"
! value
! effect
|-
| TOWNPRODUCTION_PASSENGERS
| Town produces cargo as like passengers
|-
| TOWNPRODUCTION_MAIL
| Town produces cargo as like mail
|-
| TOWNPRODUCTION_NONE
| Town does not produce cargo (default)
|}

==Cargo variables==

Cargos have no variables (yet).

==Cargo callbacks==

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

===Station rating callback===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

====Callback parameters====

<ul><li>
<code style="color:darkgreen">getbits(extra_callback_info1, 0, 8)</code>:
{| |-
!value!!meaning
|-
|0x10||the last vehicle entering the station was a train
|-
|0x11||the last vehicle entering the station was a road vehicle
|-
|0x12||the last vehicle entering the station was a ship
|-
|0x13||the last vehicle entering the station was an aircraft
|-
|0||no vehicle entered the station yet, or (TTDPatch) the last one entering was sold
|}
Please note that there's only one "last vehicle type" field per station, so the vehicle this refers to may not have picked up any of your cargo.
</li><li>
<code style="color:darkgreen">getbits(extra_callback_info2, 0, 8)</code>: The time since the cargo was last picked up, in the time units described above (1 unit = 2.5 days independent of vehicle type)
</li><li>
<code style="color:darkgreen">getbits(extra_callback_info2, 8, 16)</code>: The amount of cargo waiting.
</li><li>
<code style="color:darkgreen">getbits(extra_callback_info2, 24, 8)</code>: The speed of the last vehicle picking the cargo up, in the speed units described above (if no vehicle entered the station yet, the value is 0xFF).
</li></ul>

====Effect of callback====

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

Action0/Railtypes

2023-12-09T15:21:02Z

Andythenorth: /* Compatible rail type list (0E) */

'''''Action 0 properties for rail types'''''

= Action 0 - Properties for rail types =

Defining properties of rail types.

{{ottdp|1.0|no|ottdrev=r18969}} 16 railtypes can be defined.

{{ottdp|1.9|no|ottdrev=bf8d7df7}} 64 railtypes can be defined.

== Properties ==

{| class="wikitable"
|-
!'''Number'''
!'''Version'''
!'''Size'''
!'''Description'''
|-
|08
|{{ottdp|1.0}}
|4*B
|Rail type label
|-
|09
|{{ottdp|1.0}}
|W
|StringID: Build rail toolbar caption<ref>{{grfTill|7}} For GRF version 7 or earlier, setting property 09 sets property 1B as well.</ref>
|-
|0A
|{{ottdp|1.0}}
|W
|StringID: Rail construction dropdown text
|-
|0B
|{{ottdp|1.0}}
|W
|StringID: Build vehicle window caption
|-
|0C
|{{ottdp|1.0}}
|W
|StringID: Autoreplace text
|-
|0D
|{{ottdp|1.0}}
|W
|StringID: New engine text
|-
|0E
|{{ottdp|1.0}}
|B n*D
|Compatible rail type list<ref name="alt_label">Rail type labels in this list are ''not'' resolved using the alternate label list.</ref>
|-
|0F
|{{ottdp|1.0}}
|B n*D
|Powered rail type list<ref name="alt_label" />
|-
|10
|{{ottdp|1.0}}
|B
|Rail type flags
|-
|11
|{{ottdp|1.0}}
|B
|Curve speed advantage multiplier
|-
|12
|{{ottdp|1.0}}
|B
|Station (and depot) graphics
|-
|13
|{{ottdp|1.0}}
|W <ref>In r18969 to 19306 this property was byte-sized.</ref>
|Construction costs
|-
|14
|{{ottdp|1.0}}
|W
|Speed limit
|-
|15
|{{ottdp|1.0}}
|B
|Acceleration model
|-
|16
|{{ottdp|1.0|no|ottdrev=r19307}}
|B
|Minimap colour
|-
|17
|{{ottdp|1.1|no|ottdrev=r21842}}
|D
|Introduction date
|-
|18
|{{ottdp|1.1|no|ottdrev=r21842}}
|B n*D
|Introduction required rail type list<ref name="alt_label" />
|-
|19
|{{ottdp|1.1|no|ottdrev=r21841}}
|B n*D
|Introduced rail type list<ref name="alt_label" />
|-
|1A
|{{ottdp|1.1|no|ottdrev=r21866}}
|B
|Sort order
|-
|1B
|{{ottdp|1.2|no|ottdrev=r23129}}
|W
|StringID: Rail type name<ref>{{grfTill|7}} For GRF version 7 or earlier, set property 1B ''after'' setting property 09, as property 09 sets the rail type name as well for backwards compatibility.</ref>
|-
|1C
|{{ottdp|1.2|no|ottdrev=r23415}}
|W
|Infrastructure maintenance cost factor
|-
|1D
|{{ottdp|1.2|no|ottdrev=r23758}}
|B n*D
|Alternate rail type labels that shall be "redirected" to this rail type
|}

<references />

In NFO, rail type IDs will be GRF local, with an ID to label mapping. Therefore to modify an existing rail type, specify its label in property 08. To create a new rail type, again just specify its label in property 08. This way there is no need for complex GRM mechanisms to allocate IDs. If a label 'clashes' with another GRF, then one GRF will end up modifying the properties instead of creating a new rail type.

When a new rail type is created, it is populated with the information from the first rail type, except that the compatible and powered list contain only the rail type being created. However, no default values should be assumed, as the first rail type may have been modified.

== Vehicle and Railtype availability ==

Vehicle and railtype availability and compatibility is influenced by multiple properties.
Generally, the vehicle defines which railtype it is, and the railtypes define the compatibility between each other.
* A vehicle exists, if its railtype (train prop 05) is defined. Otherwise the vehicle is disabled.
* When a vehicle is introduced, it always introduces its railtype (train prop 05).
* A railtype is introduced, if at least one of the following conditions is met:
** A vehicle is introduced, that references the railtype (train prop 05).
** Another railtype is introduced, that references the railtype via the introduced railtype list (railtype prop 19).
** The introduction date (railtype prop 17) is passed and all required railtypes (railtype prop 18) are available.

Via railtype property 1D multiple railtypes can be defined, which shall be considered equivalent to a railtype.
This affects the interpretation of train property 05. If train property 05 references an undefined railtype, then
railtype property 1D is checked for all defined railtypes, whether the vehicle can be reassigned to some other railtype.
Otherwise the vehicle is disabled.

== Rail type label (08) ==

These are globally unique four-letter identifiers for specific rail types (analoguous to [[Action0Cargos#Cargo label 17|cargo labels]]), used to make various rail types accessible from train vehicle grfs. Reserved labels for default rail types are:

{| class="wikitable
|-
!'''Label'''
!'''Rail Type'''
|-
|RAIL
| Normal Rail
|-
|ELRL
| Electrified Rail
|-
|MONO
| Mono Rail
|-
|MGLV
| Maglev Rail
|}

{{ottdp|1.0|no|ottdrev=r18969}} 16 railtypes can be defined.

{{ottdp|1.9|no|ottdrev=bf8d7df7}} 64 railtypes can be defined.

Rail type sets may use up to 64 railtypes and have to specify their own [[RailtypeLabels|labels]].

See also [[Action0/Global Settings#Rail type translation table 12|Rail Type Translation Table]] for further info.

== Build rail toolbar caption (09) ==

String ID of the name of the rail type as shown in the toolbar caption.

{{grfTill|7}} {{ottd|1.2|ottdrev=r23129}} For backwards compatibility, setting this property sets the rail type name (property 1B) to this string as well for GRF versions 7 or below.

OpenTTD before r20342 and 1.0.3 require the string to start with the white control code. Later versions of OpenTTD will automatically default to white.

== Rail construction dropdown text (0A) ==

String ID for text in the dropdown of all rail types.

This string must never start with a colour control code.

== Build vehicle window caption (0B) ==

String ID for build vehicle window caption.

OpenTTD before r20342 and 1.0.3 require the string to start with the white control code. Later versions of OpenTTD will automatically default to white.

== Autoreplace text (0C) ==

String ID for rail type shown in autoreplace window.

== New engines (0D) ==

StringID to use for showing texts of the type "We have invented a new <rail type> engine".

== Compatible rail type list (0E) ==

List of rail types on which trains of this rail type can run, even though they might not be powered. E.g. wagons/engines of "eletrified rail"-type are also compatible to "normal rail" and "third rail" type, but they are not powered (there need to be an other powered engine in the consist to move the train).

The format is:

<pre>0E <nvar> (<rail type label>){n}</pre>

That is you give the number of compatible rail types in a single byte followed by a list of that length of rail type labels. A rail type is automatically compatible (and powered) with itself, so you don't need to list the current rail type.

Note that these properties apply to trains of this rail type, not the track. If you want trains of other rail types to be able to run on your rail types, you must set the compatible rail types property for each rail type. Setting these properties behaves always incremental, so you only need to the set additional bits for each
other rail type, you cannot remove compatibility/poweredness once it is set (by some other grf).

Note that when routing trains, the compatibility is only evaluated for the lead engine of a consist. This means that trains will run on incompatible rail types if they are in a consist where the lead engine is compatible with the rail type. This applies to both engines and wagons.

== Powered rail type list (0F) ==

List of rail types on which trains of this rail type are powered. E.g. engines of "normal rail"-type are powered on "electrified rail"- and "third-rail"-type as well.

Same format as for property 0E above.

== Rail type flags (10) ==

Flags to define properties related to the rail type:

{| class="wikitable"
|-
!'''Bit'''
!'''Value'''
!'''Version'''
!'''Meaning'''
|-
|0
|1
||{{ottdp|1.0}}
|Draw catenary for this rail type
|-
|1
|2
||{{ottdp|1.1|no|ottdrev=r20049}}
|Disallow level crossings for this rail type
|-
|2
|4
||{{ottdp|1.9|no|ottdrev=e3b440c9c5}}
|Hide this rail type from construction menu
|-
|3
|8
||{{ottdp|1.10|no|ottdrev=g42046af933}}
|Enable use of precombined overlay sprites
|-
|4
|16
||{{ottdp|1.10|no|ottdrev=gcc5f175615}}
|Always allow 90 degree turns
|-
|5
|32
||{{ottdp|1.10|no|ottdrev=gcc5f175615}}
|Always prohibit 90 degree turns (takes precedence over bit 4)
|}

== Curve Speed advantage multiplier (11) ==

This property sets the multiplier to the curve speed advantage which all trains running on this track type get. The base curve speed advantage is given by the multiplication of the value of this property with the base speed advantage - which depends on the curve length in wagons:

{| class="wikitable"
|-
!'''Curve Length'''
!'''Base Speed Adv.'''
|-
|0 (90° turn)
|30
|-
|1 (2x45° turn)
|44
|-
|2
| 55
|-
|3
| 66
|-
|4
| 75
|-
|5
| 84
|-
|6
| 91
|-
|7
| 98
|-
|8
| 103
|-
|9
| 108
|-
|10
| 111
|-
|11
| 114
|-
|12+
| 115
|}

"Curve length" is the average number of wagons of the train between turns. However, very sharp turns (values 0 and 1) are not averaged out in longer trains.

The maximum speed for a train in a curve is defined by "base speed advantage" * (2 + "property 11"). Tilting trains get an additional bonus of 20% to this value.

For the default rail types this property is 0 for normal rail and electrified rail, 1 for monorail, and 2 for maglev.

== Station (and depot) graphics (12) ==

This property defines the default graphics for the stations. If no depot sprites are defined, this also defines at the same time the depot sprites to be used. There are three kind of default stations (and depots), usually associated with rail, monorail and maglev tracks. Valid values are:

{| class="wikitable"
|-
!'''Value'''
!'''Meaning'''
|-
|0
|Normal Rail
|-
|1
|Monorail
|-
|2
|Maglev
|}

== Speed limit (14) ==

Speed limit in mph*1.6 (approx. km/h). Set to "0" for no limit at all.

== Acceleration model (15) ==

This property defines the acceleration model used. Valid values range from 0 to 2:

{| class="wikitable"
|-
!'''Value'''
!'''Meaning'''
|-
|0
|Normal Rail
|-
|1
|Monorail
|-
|2
|Maglev
|}

There is currently no difference between normal rail and monorail.

== Map colour (16) ==

This property defines the colour this track type is drawn in the minimap view. The byte value specifies the colour entry in the [[PalettesAndCoordinates|DOS palette]].

== Introduction date (17) ==

This property defines the long date formatted introduction date of this rail type. With this property set the rail type will be introduced at (or after) this date when all of the introduction required rail types are available to the company of the player, or whenever a vehicle using this rail type gets introduced whichever is first.

== Introduction required rail type list (18) ==

List of rail types on that need to be available to the company of the player for this rail type to be introduced at (or after) the introduction date. This limit does not apply when the rail type is introduced by the introduction of a vehicle.

Same format as for property 0E above.

This can, for example, be used to introduce a third rail with catenary track type when both third rail and catenary rail types are available.

== Introduced rail type list (19) ==

List of rail types that get introduced when this rail type is introduced. For example, to make sure that when a fast rail type is introduced the slow variant exists.

Same format as for property 0E above.

== Sort order (1A) ==

Property for influencing the sort order of the drop down lists with rail types. Default values are as follows:

{| class="wikitable"
|-
!'''Value'''
!'''Meaning'''
|-
|07
|Normal Rail
|-
|17
|Electrified Rail
|-
|27
|Monorail
|-
|37
|Maglev
|-
|n7
|Railtype #n
|}

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

== Rail type name (1B) ==

String ID of the name of the rail type.

{{grfTill|7}} For GRF versions 7 or earlier, set property 1B ''after'' setting property 09, as property 09 sets the rail type name as well for backwards compatibility.

== Alternate rail type labels (1D) ==

A list of alternate labels that get "redirected" to this rail type when used e.g. as track type of train or when testing if a label is defined. The redirection only happens if the alternate label isn't defined as a real rail type. Same format as for property 0E above.

Alternate labels are not considered when evaluating properties 0E, 0F, 18, and 19.

= Example =

To be written

NML:Railtypes

2023-12-09T15:20:23Z

Andythenorth:

{{NMLNavPropVarCB}}

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

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

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

== Vehicle and Railtype availability ==

Vehicle and railtype availability and compatibility is influenced by multiple properties.
Generally, the vehicle defines which railtype it is, and the railtypes define the compatibility between each other.
* A vehicle exists, if its railtype (train property <code style="color:green">track_type</code>) is defined. Otherwise the vehicle is disabled.
* When a vehicle is introduced, it always introduces its railtype (train property <code style="color:green">track_type</code>).
* A railtype is introduced, if at least one of the following conditions is met:
** A vehicle is introduced, that references the railtype (train property <code style="color:green">track_type</code>).
** Another railtype is introduced, that references the railtype via the introduced railtype list (railtype propery <code style="color:green">introduces_railtype_list</code>).
** The introduction date (railtype property <code style="color:green">introduction_date</code>) is passed and all required railtypes (railtype property <code style="color:green">requires_railtype_list </code>) are available.

Via railtype property <code style="color:green">compatible_railtype_list</code> multiple railtypes can be defined, which shall be considered equivalent to a railtype.
This affects the interpretation of train property <code style="color:green">track_type</code>. If train property <code style="color:green">track_type</code> references an undefined railtype, then
railtype property <code style="color:green">compatible_railtype_list</code> is checked for all defined railtypes, whether the vehicle can be reassigned to some other railtype.
Otherwise the vehicle is disabled. However note also that <code style="color:green">alternative_railtype_list</code> provides an alternative/complementary approach to handling undefined railtypes.

Note that when routing trains onto railtypes, the compatibility is only evaluated for the lead engine of a consist. This means that trains will run on incompatible rail types if they are in a consist where the lead engine is compatible with the rail type. This applies to both engines and wagons.

==Railtype properties==

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

===Sort order===

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

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

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

===Base speeds for curves===

The base speeds relevant for the curve_speed_multiplier are:

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

==Railtype variables==

{| class="wikitable sortable"
! name
! value range
! comment
|-
| terrain_type
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|
|-
| enhanced_tunnels
| 0
| Reserved for future use, always returns 0 in OpenTTD. Should custom tunnel entrances be implemented, other values than 0 might be returned
|-
| level_crossing_status
| LEVEL_CROSSING_CLOSED, LEVEL_CROSSING_OPEN
|
|-
| build_date
| 0 .. 5000000
| for depots only: build date of the depot in days since 0
|-
| town_zone
| [[NML:List of town zones|town zone]]
| Town zone of the tile. (Only available for level crossings and depots.)
|-
| random_bits
|
| 2 pseudo-random bits, based on tile location
|}

==Railtype callbacks==

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

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

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

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

[[File:railtype_gui.png]]

==== track_overlay ====

[[File:railtype_overlay.png]]

==== underlay ====

[[File:railtype_underlay.png]]

==== level_crossings ====

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

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

[[File:railtype_levelcrossing.png]]

==== depots ====

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

==== fences ====

[[File:railtype_fences.png]]

{{ottdp|1.6|no|ottdrev=r27343}} Since OpenTTD r27343 there is also a 16 sprites version, this allows to use different sprites resp. offsets for the fences on either track side.

{| |-
! Sprite number !! Tile slope !! Track bit !! Fence position !! Version
|-
| 0 || flat || X || NW || {{ottdp|1.0|no|ottdrev=r19056}}
|-
| 1 || flat || Y || NE || {{ottdp|1.0|no|ottdrev=r19056}}
|-
| 2 || flat || left || E || {{ottdp|1.0|no|ottdrev=r19056}}
|-
| 3 || flat || upper || S || {{ottdp|1.0|no|ottdrev=r19056}}
|-
| 4 || SW || X || NW || {{ottdp|1.0|no|ottdrev=r19056}}
|-
| 5 || SE || Y || NE || {{ottdp|1.0|no|ottdrev=r19056}}
|-
| 6 || NE || X || NW || {{ottdp|1.0|no|ottdrev=r19056}}
|-
| 7 || NW || Y || NE || {{ottdp|1.0|no|ottdrev=r19056}}
|-
| 8 || flat || X || SE || {{ottdp|1.6|no|ottdrev=r27343}}
|-
| 9 || flat || Y || SW || {{ottdp|1.6|no|ottdrev=r27343}}
|-
| 10 || flat || left || W || {{ottdp|1.6|no|ottdrev=r27343}}
|-
| 11 || flat || upper || N || {{ottdp|1.6|no|ottdrev=r27343}}
|-
| 12 || SW || X || SE || {{ottdp|1.6|no|ottdrev=r27343}}
|-
| 13 || SE || Y || SW || {{ottdp|1.6|no|ottdrev=r27343}}
|-
| 14 || NE || X || SE || {{ottdp|1.6|no|ottdrev=r27343}}
|-
| 15 || NW || Y || SW || {{ottdp|1.6|no|ottdrev=r27343}}
|}

==== tunnel_overlay ====

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

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

Illustration: [[File:RailtypeTunnelExample.png]]

==== signals ====

This callback can be used to supply custom signal graphics.

The resulting sprite set must consist of 8 sprites, corresponding to the following signal directions: SW-facing, NE-facing, NW-facing, SE-facing, E-facing, W-facing, S-facing, N-facing. If resolving fails or results in an empty sprite group, the matching base set sprite will be used instead.

Variable <code style:darkgreen>extra_callback_info2</code> contains the state, variant and type of the signal. Use the builtin function <code style:darkgreen>getbits()</code> in the following fashion to access the information:
<ul><li>
Signal state: <code style:darkgreen>getbits(extra_callback_info2, 0, 8)</code>:
{| |-
! Result !! Meaning
|-
| 00 || Red signal
|-
| 01 || Green signal
|-
| all other values || Reserved
|}
</li><li>
Signal variant: <code style:darkgreen>getbits(extra_callback_info2, 8, 8)</code>:
{| |-
! Result !! Meaning
|-
| 00 || Light (electric) signal
|-
| 01 || Semaphore
|-
| all other values || Reserved
|}
</li><li>
Signal type: <code style:darkgreen>getbits(extra_callback_info2, 16, 8)</code>:
{| |-
! Result !! Meaning
|-
| 00 || Normal block signal
|-
| 01 || Entry pre-signal
|-
| 02 || Exit pre-signal
|-
| 03 || Combo pre-signal
|-
| 04 || Two-way path signal
|-
| 05 || One-way path signal
|-
| all other values || Reserved
|}
</li></ul>
Variable <code style:darkgreen>extra_callback_info1</code> contains the drawing context.
<ul><li>
<code style:darkgreen>getbits(extra_callback_info1, 0, 8)</code>:
{| |-
! Result !! Meaning
|-
| 0 || Signal is drawn in a viewport, i.e. on the map.
|-
| 0x10 || Signal is drawn in the signal GUI. The returned sprite set must still have 8 sprites, but OpenTTD will only use the 7th sprite, so all other sprites can be empty.
|-
| all other values || Reserved
|}
</li></ul>

====Precombined overlay sprites====

[[File:Rails_combined.png]]

===Example code===

A typical implementation for railtypes can look like:

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

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

Action0/Railtypes

2023-12-09T14:55:48Z

Andythenorth: /* Compatible rail type list (0E) */ - note that compatibility is only evaluated for the lead engine.

'''''Action 0 properties for rail types'''''

= Action 0 - Properties for rail types =

Defining properties of rail types.

{{ottdp|1.0|no|ottdrev=r18969}} 16 railtypes can be defined.

{{ottdp|1.9|no|ottdrev=bf8d7df7}} 64 railtypes can be defined.

== Properties ==

{| class="wikitable"
|-
!'''Number'''
!'''Version'''
!'''Size'''
!'''Description'''
|-
|08
|{{ottdp|1.0}}
|4*B
|Rail type label
|-
|09
|{{ottdp|1.0}}
|W
|StringID: Build rail toolbar caption<ref>{{grfTill|7}} For GRF version 7 or earlier, setting property 09 sets property 1B as well.</ref>
|-
|0A
|{{ottdp|1.0}}
|W
|StringID: Rail construction dropdown text
|-
|0B
|{{ottdp|1.0}}
|W
|StringID: Build vehicle window caption
|-
|0C
|{{ottdp|1.0}}
|W
|StringID: Autoreplace text
|-
|0D
|{{ottdp|1.0}}
|W
|StringID: New engine text
|-
|0E
|{{ottdp|1.0}}
|B n*D
|Compatible rail type list<ref name="alt_label">Rail type labels in this list are ''not'' resolved using the alternate label list.</ref>
|-
|0F
|{{ottdp|1.0}}
|B n*D
|Powered rail type list<ref name="alt_label" />
|-
|10
|{{ottdp|1.0}}
|B
|Rail type flags
|-
|11
|{{ottdp|1.0}}
|B
|Curve speed advantage multiplier
|-
|12
|{{ottdp|1.0}}
|B
|Station (and depot) graphics
|-
|13
|{{ottdp|1.0}}
|W <ref>In r18969 to 19306 this property was byte-sized.</ref>
|Construction costs
|-
|14
|{{ottdp|1.0}}
|W
|Speed limit
|-
|15
|{{ottdp|1.0}}
|B
|Acceleration model
|-
|16
|{{ottdp|1.0|no|ottdrev=r19307}}
|B
|Minimap colour
|-
|17
|{{ottdp|1.1|no|ottdrev=r21842}}
|D
|Introduction date
|-
|18
|{{ottdp|1.1|no|ottdrev=r21842}}
|B n*D
|Introduction required rail type list<ref name="alt_label" />
|-
|19
|{{ottdp|1.1|no|ottdrev=r21841}}
|B n*D
|Introduced rail type list<ref name="alt_label" />
|-
|1A
|{{ottdp|1.1|no|ottdrev=r21866}}
|B
|Sort order
|-
|1B
|{{ottdp|1.2|no|ottdrev=r23129}}
|W
|StringID: Rail type name<ref>{{grfTill|7}} For GRF version 7 or earlier, set property 1B ''after'' setting property 09, as property 09 sets the rail type name as well for backwards compatibility.</ref>
|-
|1C
|{{ottdp|1.2|no|ottdrev=r23415}}
|W
|Infrastructure maintenance cost factor
|-
|1D
|{{ottdp|1.2|no|ottdrev=r23758}}
|B n*D
|Alternate rail type labels that shall be "redirected" to this rail type
|}

<references />

In NFO, rail type IDs will be GRF local, with an ID to label mapping. Therefore to modify an existing rail type, specify its label in property 08. To create a new rail type, again just specify its label in property 08. This way there is no need for complex GRM mechanisms to allocate IDs. If a label 'clashes' with another GRF, then one GRF will end up modifying the properties instead of creating a new rail type.

When a new rail type is created, it is populated with the information from the first rail type, except that the compatible and powered list contain only the rail type being created. However, no default values should be assumed, as the first rail type may have been modified.

== Vehicle and Railtype availability ==

Vehicle and railtype availability and compatibility is influenced by multiple properties.
Generally, the vehicle defines which railtype it is, and the railtypes define the compatibility between each other.
* A vehicle exists, if its railtype (train prop 05) is defined. Otherwise the vehicle is disabled.
* When a vehicle is introduced, it always introduces its railtype (train prop 05).
* A railtype is introduced, if at least one of the following conditions is met:
** A vehicle is introduced, that references the railtype (train prop 05).
** Another railtype is introduced, that references the railtype via the introduced railtype list (railtype prop 19).
** The introduction date (railtype prop 17) is passed and all required railtypes (railtype prop 18) are available.

Via railtype property 1D multiple railtypes can be defined, which shall be considered equivalent to a railtype.
This affects the interpretation of train property 05. If train property 05 references an undefined railtype, then
railtype property 1D is checked for all defined railtypes, whether the vehicle can be reassigned to some other railtype.
Otherwise the vehicle is disabled.

== Rail type label (08) ==

These are globally unique four-letter identifiers for specific rail types (analoguous to [[Action0Cargos#Cargo label 17|cargo labels]]), used to make various rail types accessible from train vehicle grfs. Reserved labels for default rail types are:

{| class="wikitable
|-
!'''Label'''
!'''Rail Type'''
|-
|RAIL
| Normal Rail
|-
|ELRL
| Electrified Rail
|-
|MONO
| Mono Rail
|-
|MGLV
| Maglev Rail
|}

{{ottdp|1.0|no|ottdrev=r18969}} 16 railtypes can be defined.

{{ottdp|1.9|no|ottdrev=bf8d7df7}} 64 railtypes can be defined.

Rail type sets may use up to 64 railtypes and have to specify their own [[RailtypeLabels|labels]].

See also [[Action0/Global Settings#Rail type translation table 12|Rail Type Translation Table]] for further info.

== Build rail toolbar caption (09) ==

String ID of the name of the rail type as shown in the toolbar caption.

{{grfTill|7}} {{ottd|1.2|ottdrev=r23129}} For backwards compatibility, setting this property sets the rail type name (property 1B) to this string as well for GRF versions 7 or below.

OpenTTD before r20342 and 1.0.3 require the string to start with the white control code. Later versions of OpenTTD will automatically default to white.

== Rail construction dropdown text (0A) ==

String ID for text in the dropdown of all rail types.

This string must never start with a colour control code.

== Build vehicle window caption (0B) ==

String ID for build vehicle window caption.

OpenTTD before r20342 and 1.0.3 require the string to start with the white control code. Later versions of OpenTTD will automatically default to white.

== Autoreplace text (0C) ==

String ID for rail type shown in autoreplace window.

== New engines (0D) ==

StringID to use for showing texts of the type "We have invented a new <rail type> engine".

== Compatible rail type list (0E) ==

List of rail types on which trains of this rail type can run, even though they might not be powered. E.g. wagons/engines of "eletrified rail"-type are also compatible to "normal rail" and "third rail" type, but they are not powered (there need to be an other powered engine in the consist to move the train).

The format is:

<pre>0E <nvar> (<rail type label>){n}</pre>

That is you give the number of compatible rail types in a single byte followed by a list of that length of rail type labels. A rail type is automatically compatible (and powered) with itself, so you don't need to list the current rail type.

Note that these properties apply to trains of this rail type, not the track. If you want trains of other rail types to be able to run on your rail types, you must set the compatible rail types property for each rail type. Setting these properties behaves always incremental, so you only need to the set additional bits for each
other rail type, you cannot remove compatibility/poweredness once it is set (by some other grf).

Note that the compatibility is only evaluated for the lead engine of a consist. This means that trains will run on incompatible rail types if they are in a consist where the lead engine is compatible with the rail type. This applies to both engines and wagons.

== Powered rail type list (0F) ==

List of rail types on which trains of this rail type are powered. E.g. engines of "normal rail"-type are powered on "electrified rail"- and "third-rail"-type as well.

Same format as for property 0E above.

== Rail type flags (10) ==

Flags to define properties related to the rail type:

{| class="wikitable"
|-
!'''Bit'''
!'''Value'''
!'''Version'''
!'''Meaning'''
|-
|0
|1
||{{ottdp|1.0}}
|Draw catenary for this rail type
|-
|1
|2
||{{ottdp|1.1|no|ottdrev=r20049}}
|Disallow level crossings for this rail type
|-
|2
|4
||{{ottdp|1.9|no|ottdrev=e3b440c9c5}}
|Hide this rail type from construction menu
|-
|3
|8
||{{ottdp|1.10|no|ottdrev=g42046af933}}
|Enable use of precombined overlay sprites
|-
|4
|16
||{{ottdp|1.10|no|ottdrev=gcc5f175615}}
|Always allow 90 degree turns
|-
|5
|32
||{{ottdp|1.10|no|ottdrev=gcc5f175615}}
|Always prohibit 90 degree turns (takes precedence over bit 4)
|}

== Curve Speed advantage multiplier (11) ==

This property sets the multiplier to the curve speed advantage which all trains running on this track type get. The base curve speed advantage is given by the multiplication of the value of this property with the base speed advantage - which depends on the curve length in wagons:

{| class="wikitable"
|-
!'''Curve Length'''
!'''Base Speed Adv.'''
|-
|0 (90° turn)
|30
|-
|1 (2x45° turn)
|44
|-
|2
| 55
|-
|3
| 66
|-
|4
| 75
|-
|5
| 84
|-
|6
| 91
|-
|7
| 98
|-
|8
| 103
|-
|9
| 108
|-
|10
| 111
|-
|11
| 114
|-
|12+
| 115
|}

"Curve length" is the average number of wagons of the train between turns. However, very sharp turns (values 0 and 1) are not averaged out in longer trains.

The maximum speed for a train in a curve is defined by "base speed advantage" * (2 + "property 11"). Tilting trains get an additional bonus of 20% to this value.

For the default rail types this property is 0 for normal rail and electrified rail, 1 for monorail, and 2 for maglev.

== Station (and depot) graphics (12) ==

This property defines the default graphics for the stations. If no depot sprites are defined, this also defines at the same time the depot sprites to be used. There are three kind of default stations (and depots), usually associated with rail, monorail and maglev tracks. Valid values are:

{| class="wikitable"
|-
!'''Value'''
!'''Meaning'''
|-
|0
|Normal Rail
|-
|1
|Monorail
|-
|2
|Maglev
|}

== Speed limit (14) ==

Speed limit in mph*1.6 (approx. km/h). Set to "0" for no limit at all.

== Acceleration model (15) ==

This property defines the acceleration model used. Valid values range from 0 to 2:

{| class="wikitable"
|-
!'''Value'''
!'''Meaning'''
|-
|0
|Normal Rail
|-
|1
|Monorail
|-
|2
|Maglev
|}

There is currently no difference between normal rail and monorail.

== Map colour (16) ==

This property defines the colour this track type is drawn in the minimap view. The byte value specifies the colour entry in the [[PalettesAndCoordinates|DOS palette]].

== Introduction date (17) ==

This property defines the long date formatted introduction date of this rail type. With this property set the rail type will be introduced at (or after) this date when all of the introduction required rail types are available to the company of the player, or whenever a vehicle using this rail type gets introduced whichever is first.

== Introduction required rail type list (18) ==

List of rail types on that need to be available to the company of the player for this rail type to be introduced at (or after) the introduction date. This limit does not apply when the rail type is introduced by the introduction of a vehicle.

Same format as for property 0E above.

This can, for example, be used to introduce a third rail with catenary track type when both third rail and catenary rail types are available.

== Introduced rail type list (19) ==

List of rail types that get introduced when this rail type is introduced. For example, to make sure that when a fast rail type is introduced the slow variant exists.

Same format as for property 0E above.

== Sort order (1A) ==

Property for influencing the sort order of the drop down lists with rail types. Default values are as follows:

{| class="wikitable"
|-
!'''Value'''
!'''Meaning'''
|-
|07
|Normal Rail
|-
|17
|Electrified Rail
|-
|27
|Monorail
|-
|37
|Maglev
|-
|n7
|Railtype #n
|}

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

== Rail type name (1B) ==

String ID of the name of the rail type.

{{grfTill|7}} For GRF versions 7 or earlier, set property 1B ''after'' setting property 09, as property 09 sets the rail type name as well for backwards compatibility.

== Alternate rail type labels (1D) ==

A list of alternate labels that get "redirected" to this rail type when used e.g. as track type of train or when testing if a label is defined. The redirection only happens if the alternate label isn't defined as a real rail type. Same format as for property 0E above.

Alternate labels are not considered when evaluating properties 0E, 0F, 18, and 19.

= Example =

To be written

Callbacks

2023-11-30T20:44:15Z

Andythenorth: /* List of callbacks */

==Introduction==

A callback is a special action 2 that the patch "calls" in order to modify various features, an example being the visual effect of train vehicles.  See the [[ttwiki:CallbacksTut|callback tutorial]] on how to use them.

In the final action 2 of a chain of VarAction2s, the second byte of the matching entry has to have bit 7 set to identify it as a callback result.

For example, 04 00 is not a callback result (but it may be the ID of another chained action 2), whereas 04 80 is a callback result with a value of 4. In total a callback has 15 bit result values, where the upper 7 bits are stored in the second byte. For example, 54 C2 is a callback result with a value of 4254=16980, where again the second byte has bit 7 set, changing the 42 into C2.

{{grfTill|7}} For GRF version 7 and below not all 15 bit values are available as return values, only values between 00 and 7EFF.
For compatibility with earlier patch versions, FF in the high byte is taken to mean the same thing as 80, so 04 FF also has a callback result of 4. Note that if your grf file needs to be compatible with versions before TTDPatch 2.0.1 alpha 40, you must set the high byte to FF, and so can use only 8 bit results.

{{grfFrom|8}} For GRF version 8 and above this compatibility layer has been removed. Callbacks can return all 15 bit values between 00 and 7FFF.

To check for a specific callback, use an [[VariationalAction2]] or [[VarAction2Advanced]] to check for variable 0C.
* Variable 0C contains the callback number.
* Variable 0C is a word, thus the VarAction2 must use type 85.
* Results can be specified directly using 8xxx values (see above), or with 8xxx value in subsequent (Basic/Variational/Random)Action2 which are referenced as usual with their set-id.
* The default case of the VarAction2 must point to the regular graphics chain, so that unknown/future callbacks results in a "callback failure" result.

Example:
<Sprite-number> * <Length> 02 <feature> <set-id> 85 0C 00 \wxFFFF
<nvar> (<set-id/result> \wx <callback> \wx <callback>){n}
<set-id of graphics chain>

The format for VarAction2 is explained in detail on the [[VariationalAction2]] page.

== List of callbacks ==

The following callbacks are defined by the patch.  The number of the callback is what will be stored in variable 0C so that you can return the right results if you have several callbacks.  All callbacks are explained in more detail below.

'''PLEASE NOTE:''' Since TTDPatch 2.5 beta 5, the size of variable 0C has changed, and now there are word-sized callback numbers as well. To maintain backwards compatibility, only callbacks 10..3F can be checked using a byte-sized check. Callbacks 140 and above, on the other hand, must be checked using a word or dword sized check, to make sure they are identified uniquely.

{| |-
!Number!!Feature(s)!!Meaning
|-
|10||Vehicles||[[Callback: Visual effect and wagon power|Visual effect and wagon power]]
|-
|11||Vehicles||[[Callback: Wagon length|Wagon length]]
|-
|12||Vehicles||[[Callback: Load amount|Load amount]]
|-
|13||Stations||[[Callback: Station availability|Station availability]]
|-
|14||Stations||[[Callback: Station sprite layout|Select sprite layout]]
|-
|15||Vehicles||[[Callback: Refitted capacity callback|Refitted capacity callback]]
|-
|16||Trains||[[Callback: Articulated engine|Build articulated engines]]
|-
|17||Houses||[[Callback: House construction check|House construction check]]
|-
|18||Several <ref name="generic">Generic callbacks are called for the feature, not any specific vehicle ID. Read the [[Action3#n-id|Action 3]] entry on how to define these.</ref>||[[Callback: AI construction/purchase selection|AI construction/purchase selection]]
|-
|19||Vehicles||[[Callback: Cargo Subtype Display|Cargo sub-type display]]
|-
|1A||Houses||Next animation frame
|-
|1B||Houses||Animation control
|-
|1C||Houses||Construction stage changes
|-
|1D||Trains||Can wagon be attached
|-
|1E||Houses||Decide colour of building
|-
|1F||Houses||Cargo acceptance
|-
|20||Houses||Length of animation frame
|-
|21||Houses||Trigger building destruction
|-
|22||Industries||Availability
|-
|23||Vehicles||Additional text in purchase screen
|-
|24||Stations||Custom station layout
|-
|25||Industry tiles||Animation control
|-
|26||Industry tiles||Next animation frame
|-
|27||Industry tiles||Length of animation frame
|-
|28||Industries||Industry location permissibility
|-
|29||Industries||Random production change
|-
|2A||Houses||Get accepted cargo types
|-
|2B||Industry tiles||Decide cargo acceptance
|-
|2C||Industry tiles||Get accepted cargo types
|-
|2D||Vehicles||Select colour mapping for vehicle
|-
|2E||Houses||Custom cargo production
|-
|2F||Industry tiles||Custom shape check
|-
|30||Industry tiles||Decide drawing default foundations
|-
|31||Vehicles||Start/stop check
|-
|32||Vehicles||32-day callback
|-
|33||Several||Sound effect callback
|-
|34||Vehicles <ref name="generic"/>||Autoreplace vehicle selection
|-
|35||Industries||Monthly random production change
|-
|36||Vehicles||Change vehicle Properties
|-
|37||Industries||Cargo sub-type display
|-
|38||Industries||Show additional text in fund window
|-
|39||Cargoes||Custom profit calculation
|-
|3A||Industries||Show additional text in industry window
|-
|3B||Industries||Control special effects
|-
|3C||Industry tiles||Disable autosloping
|-
|3D||Industries||Opt out of accepting cargo
|-
|40..13F|| ||--Reserved--
|-
|140||Stations||Animation control
|-
|141||Stations||Next animation frame
|-
|142||Stations||Length of animation frame
|-
|143||Houses||Protect building conditionally
|-
|144||Sounds <ref name="generic"/>||{{ottdp|1.2|2.6|ottdrev=r23144|ttdprev=r821}} Ambient sound effects
|-
|145||Cargoes||Custom station rating calculation
|-
|146||New Signals <ref name="generic"/>||New signals sprite drawing
|-
|147||Canals||Add sprite offset
|-
|148||Houses||Watched cargo accepted
|-
|149||Stations||Land slope check
|-
|14A||Industries||Decide industry color
|-
|14B||Industries||Decide input cargo types
|-
|14C||Industries||Decide output cargo types
|-
|14D||Houses||Customized building name
|-
|14E||Houses||Decide drawing default foundations
|-
|14F||Houses||Disable autosloping
|-
|150||Airport tiles||{{ottdp|1.1|no|ottdrev=r19197}} Decide drawing default foundations
|-
|152||Airport tiles||{{ottdp|1.1|no|ottdrev=r19197}} Animation control
|-
|153||Airport tiles||{{ottdp|1.1|no|ottdrev=r19197}} Next Animation frame
|-
|154||Airport tiles||{{ottdp|1.1|no|ottdrev=r19197}} Length of animation frame
|-
|155||Airports||{{ottdp|1.1|no|ottdrev=r20373}} Extra information about airport layout in the build gui
|-
|156||Airports||{{ottdp|1.1|no|ottdrev=r20373}} Airport layout name
|-
|157||Objects||Land slope check
|-
|158||Objects||Next animation frame
|-
|159||Objects||Animation control
|-
|15A||Objects||Length of animation frame
|-
|15B||Objects||Decide colour of building
|-
|15C||Objects||Show additional text in building window
|-
|15D||Objects||Disable autosloping
|-
|15E||Vehicles||{{ottdp|1.2|no|ottdrev=r23124}} Refit cost factor
|-
|15F||Industries||{{ottdp|1.3|no|ottdrev=r24186}} Set initial production level on construction
|-
|160||Vehicles||{{ottdp|1.5|no|ottdrev=r26747}} Advanced effect creation
|-
|161||Vehicles||{{ottdp|14|no|ottdrev=g05ed9f56fd}} Engine name
|-
|162||Vehicles||{{ottdp|14|no|ottdrev=gddd609ce9b}} Probability of reversing rail vehicle on build
|}
<references/>

{{:Callback: Visual effect and wagon power}}
{{:Callback: Wagon length}}
{{:Callback: Load amount}}
{{:Callback: Station availability}}
{{:Callback: Station sprite layout}}
{{:Callback: Refitted capacity callback}}
{{:Callback: Articulated engine}}
{{:Callback: House construction check}}
{{:Callback: AI construction/purchase selection}}
{{:Callback: Cargo Subtype Display}}
{{:Callback: Next animation frame}}
{{:Callback: Animation control}}
{{:Callback: Construction stage changes}}
{{:Callback: Can wagon be attached}}
{{:Callback: Building colour}}
{{:Callback: Cargo acceptance}}
{{:Callback: Length of animation frame}}
{{:Callback: Trigger building destruction}}
{{:Callback: Industry availability}}
{{:Callback: Additional text in purchase screen}}
{{:Callback: Custom station layout}}
{{:Callback: Industry location permissibility}}
{{:Callback: Random production change}}
{{:Callback: Get accepted cargo types}}
{{:Callback: Decide cargo acceptance}}
{{:Callback: Select colour mapping for vehicle}}
{{:Callback: Custom cargo production}}
{{:Callback: Custom shape check}}
{{:Callback: Decide drawing default foundations}}
{{:Callback: Vehicle Start/stop check}}
{{:Callback: 32-day callback}}
{{:Callback: Sound effect}}
{{:Callback: Autoreplace vehicle selection}}
{{:Callback: Monthly random production change}}
{{:Callback: Change vehicle properties}}
{{:Callback: Cargo sub-type display for industries}}
{{:Callback: Show additional text in fund/building window}}
{{:Callback: Custom profit calculation for cargoes}}
{{:Callback: Show additional text in industry window}}
{{:Callback: Control special industry effects}}
{{:Callback: Disable autosloping}}
{{:Callback: Opt out of accepting cargo}}
{{:Callback: Protect building conditionally}}
{{:Callback: Ambient sound effects}}
{{:Callback: Custom station rating calculation}}
{{:Callback: New signals sprite drawing callback}}
{{:Callback: Add sprite offset callback}}
{{:Callback: Watched cargo accepted}}
{{:Callback: Station slope check}}
{{:Callback: Decide industry colour}}
{{:Callback: Decide input and output cargo types}}
{{:Callback: Customized building name}}
{{:Callback: Extra information about layout in the build gui}}
{{:Callback: Layout name}}
{{:Callback: Object slope check}}
{{:Callback: Decide object colour}}
{{:Callback: Refit cost factor}}
{{:Callback: Set initial production level on construction}}
{{:Callback: Advanced effect creation}}
{{:Callback: Engine name}}
{{:Callback: Build probability}}

Callback: Build probability

2023-11-30T20:43:34Z

Andythenorth: /* Build probability (e.g. Reverse rail vehicle on build) (162) */

== Probability of reversing rail vehicle on build (162) ==

This callback assigns rail vehicles a random chance of being built facing forward or backward (reversed) when purchased.

Return a value between 0...100 (decimal) to indicate the probability of being reversed.

The same random-reverse behaviour can be implemented without the callback, by randomly switching to reversed sprites in the vehicle's varaction 2 chain, but this is inefficient as it typically causes sprites to be duplicated in the grf.

This callback is available from {{ottdp|14|no|ottdrev=g05ed9f56fd}} OpenTTD 14 and above.
[[Category:Callbacks]]

Callback: Build probability

2023-11-30T20:41:25Z

Andythenorth: /* Build probability (e.g. Reverse rail vehicle on build) (162) */

== Build probability (e.g. Reverse rail vehicle on build) (162) ==

This callback assigns rail vehicles a random chance of being built facing forward or backward (reversed) when purchased.

Return a value between 0...100 (decimal) to indicate the probability of being reversed.

The same random-reverse behaviour can be implemented without the callback, by randomly switching to reversed sprites in the vehicle's varaction 2 chain, but this is inefficient as it typically causes sprites to be duplicated in the grf.

This callback is available from {{ottdp|14|no|ottdrev=g05ed9f56fd}} OpenTTD 14 and above.
[[Category:Callbacks]]

Callback: Build probability random reverse

2023-11-30T20:34:38Z

Andythenorth: Blanked the page

Callback: Build probability

2023-11-30T20:34:31Z

Andythenorth: Add CB 162 (third time lucky?)

== Build probability (e.g. Reverse rail vehicle on build) (162) ==

(Details to be added)

This callback is available from {{ottdp|14|no|ottdrev=g05ed9f56fd}} OpenTTD 14 and above.
[[Category:Callbacks]]

Callback: build probability random reverse

2023-11-30T20:33:36Z

Andythenorth: Andythenorth moved page Callback: build probability random reverse to Callback: Build probability random reverse

#REDIRECT [[Callback: Build probability random reverse]]