GRFSpecs - User contributions [en-gb]

NML:Vehicles

2026-09-15T19:23:46Z

Kuhnovic: Added vehicle_is_moving_backwards, deprecated train_is_driving_backwards

{{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]].
|-
| extra_flags
| bitmask(VEHICLE_FLAG_XXX, ...)
| {{ottd|17}}
;VEHICLE_FLAG_SHIP_IS_DOUBLE_ENDED
: Ship can reverse direction without having to turn around.
Additionally, ships have the extra flags common to all vehicle types, described above.
|-
| 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). Deprecated, use vehicle_is_moving_backwards instead.
|-
| vehicle_is_moving_backwards
| [0 <nowiki>|</nowiki> 1]
| No
| {{ottd|17}} Value is 1 if the vehicle is moving backwards (trains and ships 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-09-15T19:21:21Z

Kuhnovic: /* Modflags (FE and FF) */

<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). {{ottd|17}} Applies to ships as well.
|}
<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-09-15T18:55:30Z

Kuhnovic: Added VEHICLE_FLAG_SHIP_IS_DOUBLE_ENDED

{{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]].
|-
| extra_flags
| bitmask(VEHICLE_FLAG_XXX, ...)
| {{ottd|17}}
;VEHICLE_FLAG_SHIP_IS_DOUBLE_ENDED
: Ship can reverse direction without having to turn around.
Additionally, ships have the extra flags common to all vehicle types, described above.
|-
| 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.