NML:Vehicles

property	value range	available for articulated vehicle	comment
`name`	(string)	yes	for example `string(STR_NAME_HEREFORD_TRAM)`
`climates_available`	bitmask(CLIMATE_XXX, CLIMATE_YYY, ...)	set to `NO_CLIMATE`	XXX = [TEMPERATE \| ARCTIC \| TROPICAL \| TOYLAND], alternatively `NO_CLIMATE` or `ALL_CLIMATES`. To make a vehicle available in all climates except toyland you could use: `ALL_CLIMATES & ~bitmask(CLIMATE_TOYLAND)`.
`introduction_date`	`date`(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.
`model_life`	0 ... 254 (years) or `VEHICLE_NEVER_EXPIRES`	no	Number of years a model is "supported" by the manufacturer, see below.
`retire_early`	-128 ... 127 (years)	no	Retire the vehicle (make it unavailable in the purchase menu) this many years before reliability starts dropping, see below. May be negative.
`vehicle_life`	0 ... 255 (years)	no	Life length of an individual vehicle, before it is considered too old and in need of replacement.
`reliability_decay`	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
`refittable_cargo_classes`	bit set of cargo classes	yes	for example: `bitmask(CC_BULK, CC_COVERED)`
`non_refittable_cargo_classes`	bit set of cargo classes	yes	for example: `bitmask(CC_OVERSIZED, CC_SPECIAL)`
`refittable_cargo_types`	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.
`cargo_allow_refit`	Array of cargo labels from the cargotable	Yes	1.2 A list of cargo types to allow refitting to, irrespective of cargo classes. Example: `[COAL, IORE]`
`cargo_disallow_refit`	Array of cargo labels from the cargotable	Yes	1.2 A list of cargo types to disallow refitting to, irrespective of cargo classes. Example: `[MAIL]`
`loading_speed`	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.
`cost_factor`	0 ... 255	Set to 0	multiplier to the base purchase cost
`running_cost_factor`	0 ... 255	Set to 0	multiplier to the base running costs
`cargo_age_period`	0 ... 65535	yes	1.2 This property specifies after how many ticks cargo is aged. Default value is 185. 74 ticks is equal to 1 day.

Refittability

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

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.

phase	duration	reliability
1	7 to 38 months	increases from 48-73% to 75-100%
2	`model_life` - 8 years	stays constant at peak, 75-100%
3	10 to 20.5 years	decreases from peak to 25-50%

If model_life is set to VEHICLE_NEVER_EXPIRES, 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 retire_early property, it will be retired this many years before (or after, if the value is negative) the end of phase 2.

Sorting vehicles in the purchase list

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

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

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

Train properties

property	value range	available for articulated vehicle	comment
`sprite_id`	`SPRITE_ID_NEW_TRAIN`	yes	Set this property to enable new graphics
`speed`	0 ... 65000 (float, speed units)	no	Max speed for engines, speed limit for wagons
`misc_flags`	bitmask(TRAIN_FLAG_XXX, ...)	FLIP should not be set, TILT and MU the same value	XXX=[TILT \| 2CC \| MU \| FLIP \| AUTOREFIT] which allows the train to enjoy the tilt bonus, use the 2nd company colour, act as a multiple unit (used for livery selection only) or allow the vehicle to be flipped (reversed) in the depot
`refit_cost`	0 ... 255	yes	in 50% units of the purchase price cost base
`callback_flags`	bitmask(VEH_CBF_XXX, ...)	yes	Do not set this, unless you use old-style callbacks.
`track_type`	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 `track_type` to RAIL and make sure that you set `engine_class` to `ENGINE_CLASS_ELECTRIC`.
`ai_special_flag`	[`AI_FLAG_PASSENGER` \| `AI_FLAG_CARGO`]	no	Set to `AI_FLAG_PASSENGER` to tell computer players that it's an engine that should only be used for passenger service.
`power`	0 ... 65000 hp (float, power units)	Set to 0
`running_cost_base`	RUNNING_COST_XXX	Set to RUNNING_COST_NONE	XXX = [STEAM \| DIESEL \| ELECTRIC \| ROADVEH \| NONE]
`dual_headed`	[0 \| 1]	Set to 0 for all parts of an articulated vehicle	1 = dual_headed, otherwise normal engine
`default_cargo_type`	An identifier from the 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 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 `cargo_capacity` callback to avoid this effect.
`weight`	0 .. 1279 ton (float, mass units)	Set to 0
`ai_engine_rank`	0 ... 255	no	TTDPatch only: Higher values make the engine for the TTDPatch AI more attractive
`engine_class`	ENGINE_CLASS_XXX	no	XXX=[STEAM \| DIESEL \| ELECTRIC \| MONORAIL \| MAGLEV]
`extra_power_per_wagon`	0 ... 65000 hp (float, power units)	Set to 0	Only wagons with a livery override for this engine will add power
`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.
`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.
`visual_effect_and_powered`	`visual_effect_and_powered`(VISUAL_EFFECT_XXX, offset, `ENABLE_WAGON_POWER` or `DISABLE_WAGON_POWER`)	yes	XXX=[DEFAULT \| STEAM \| DIESEL \| ELECTRIC \| DISABLE], it is the type of the visual effect you want for this vehicle. Default means "take from engine_class property". 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.
`extra_weight_per_wagon`	0 ... 255 ton (float, mass units)	Set to 0	Adds extra weight for powered wagons, see `extra_power_per_wagon`
`bitmask_vehicle_info`	8-bit bitmask	yes	Used for obtaining `bitmask_consist_info`

Road vehicle properties

property	value range	available for articulated vehicle	comment
sprite_id	SPRITE_ID_NEW_ROADVEH	yes	Set this property to enable new graphics
speed	0 ... 514km/h (float, speed units)	no
misc_flags	bitmask(ROADVEH_FLAG_XXX, ...)	partly; tram flag must the same	The following flags are defined: ROADVEH_FLAG_TRAM, ROADVEH_FLAG_2CC, ROADVEH_FLAG_AUTOREFIT. Use 0 if you don't want to set any of these flags.
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 old-style callbacks.
running_cost_base	RUNNING_COST_XXX	set to RUNNING_COST_NONE	XXX = [STEAM \| DIESEL \| ELECTRIC \| ROADVEH \| NONE]
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.
`default_cargo_type`	An identifier from the 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 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 `cargo_capacity` callback to avoid this effect.
sound_effect	SOUND_XXX	no	See available sound effects.
visual_effect	visual_effect(VISUAL_EFFECT_XXX, offset)	yes	XXX=[DEFAULT \| STEAM \| DIESEL \| ELECTRIC \| DISABLE], it is the type of the visual effect you want for this vehicle. 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.
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

property	value range	comment
sprite_id	SPRITE_ID_NEW_SHIP	Set this property to enable new graphics
speed	0 ... 127 km/h (float, speed units)
misc_flags	bitmask(SHIP_FLAG_2CC, SHIP_FLAG_AUTOREFIT)	Bitmask with two possible flags, set to 0 to disable
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 old-style callbacks.
is_refittable	[0 \| 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.
`default_cargo_type`	An identifier from the 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 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 sound effects.
ocean_speed_fraction	0 ... 1 (float)	1.2 fraction of base speed on ocean tiles (default: 1)
canal_speed_fraction	0 ... 1 (float)	1.2 fraction of base speed on canal tiles (default: 1)
visual_effect	visual_effect(VISUAL_EFFECT_XXX, offset)	XXX=[DEFAULT \| STEAM \| DIESEL \| ELECTRIC \| DISABLE], it is the type of the visual effect you want for this ship. Default means no effect. Offset is the position of the effect. 0 is default, negative values mean more to the front and positive values are backwards. Minimum offset is -8, maximum is 7.

Aircraft properties

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 1.2 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 two possible flags, set to 0 to disable both
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 old-style callbacks.
is_helicopter	AIRCRAFT_TYPE_XXX	XXX=[NORMAL \| HELICOPTER]
is_large	AIRCRAFT_SIZE_XXX	XXX=[SMALL \| LARGE]. Set to AIRCRAFT_SIZE_SMALL for helicopters.
acceleration	0 ... 255	In arbitrary units
passenger_capacity	0 ... 65536	Capacity for the passenger compartment. See also the notes at `mail_capacity` 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 `passenger_capacity` and `mail_capacity` callbacks.
sound_effect	SOUND_XXX	See available sound effects.

Vehicle variables

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

Variables without parameter

name	value range	available in purchase list?	comment
position_in_consist	0 ... 255	No	The position of the current vehicle-part from the start of the vehicle. The engine will get value 0, the first wagon (or second engine) gets value 1, etc.
position_in_consist_from_end	0 ... 255	No	Same as position_in_consist but counted from the end. The last wagon will get value 0.
num_vehs_in_consist	1 ... 256	No	The total number of vehicles-parts in this vehicle. For aircraft this will include the shadow and the rotor.
position_in_vehid_chain	0 ... 255	No	See position_in_consist, but not of the complete vehicle but only all consecutive parts with the same id.
position_in_vehid_chain_from_end	0 ... 255	No	See position_in_consist_from_end, but not of the complete vehicle but only all consecutive parts with the same id.
num_vehs_in_vehid_chain	1 ... 256	No	See num_vehs_in_consist, but not of the complete vehicle but only all consecutive parts with the same id.
cargo_classes_in_consist	Bitmask of CC_XXX	No	cargo classes
most_common_refit	cargo class	No	cargo class most often refit to
bitmask_consist_info	Bitmask 8 bit	No	Binary OR of the values of bitmask_vehicle_info 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, PLAYERTYPE_AI, PLAYERTYPE_HUMAN_IN_AI (human managing AI company) or PLAYERTYPE_AI_IN_HUMAN (AI managing human company). OpenTTD only uses PLAYERTYPE_HUMAN and PLAYERTYPE_AI. If you cheat yourself to be part of an AI company OpenTTD will still report PLAYERTYPE_AI for the company with yourself and the AI and it'll report PLAYERTYPE_HUMAN for the now uncontrolled company.
company_colour1	COLOUR_XXX	Yes	Refer to the table here for possible values.
company_colour2	COLOUR_XXX	Yes	Same as company_colour1, if no 2nd company colour is chosen. Refer to the table 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 or AIRPORTTYPE_OILRIG
curv_info_prev_cur	-2 ... 2	No	Difference in direction between the previous (towards engine) vehicle and this vehicle. Curvature to the right is positive. 1 unit is 45 degrees.
curv_info_cur_next	-2 ... 2	No	Difference in direction between this vehicle and the next (towards rear end) vehicle. Curvature to the right is positive. 1 unit is 45 degrees.
curv_info_prev_next	-4 ... 4	No	Difference in direction between the previous (towards engine) and next (towards rear end) vehicle. Curvature to the right is positive. 1 unit is 45 degrees. Equal to `curve_invo_prev_cur + curv_info_cur_next`.
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 builtin function `vehicle_curv_info()` instead to make comparisons. `curv_info == vehicle_curv_info(a, b)` is equivalent to `(curv_info_prev_cur == a) && (curv_info_cur_next == b)`, however the former can easily be used in a switch-block.
motion_counter	0 ... 15	Yes, always 0	Is increased every time the vehicle moves a single step on the map. Useful for animations.
cargo_type_in_veh	entry in cargo translation table	Yes, for the default cargo	0xFF if not present in the table
cargo_unit_weight	weight per unit in 1/16t	Yes, for the default cargo
cargo_classes	Bitmask of cargo class	Yes, for the default cargo	class of the currently transported cargo
vehicle_is_available	[0 \| 1]	Yes	Value is 1 if the vehicle is available on the open market
vehicle_is_testing	[0 \| 1]	Yes	Value is 1 if the vehicle is currently being tested
vehicle_is_offered	[0 \| 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 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 `cargo_subtype_text` callback.
vehicle_is_powered	[0 \| 1]	No	Vehicle provides power and is on the correct track type
vehicle_is_not_powered	[0 \| 1]	No	Vehicle is either on a wrong track type or it doesn't provide power at all
vehicle_is_potentially_powered	[0 \| 1]	No	Vehicle provides power, if it is on a suitable track type
vehicle_is_reversed	[0 \| 1]	No	Value is 1 if the vehicle has reversed an odd number of times
built_during_preview	[0 \| 1]	No	Value is 1 if the vehicle was built during the exclusive preview stage
current_railtype	No	Entry from railtype translation table or 0xFF	Don't use this variable unless you've defined a railtype translation table. If the train is running on a railtype that is not listed in your railtype translation table this variable will contain 0xFF. Available since OpenTTD r20164.
waiting_triggers		No	Random triggers waiting to be matched. (see Random switch)
random_bits	0 ... 255	No	Random data that can be used to randomize certain descisions. (see Random switch)
grfid	0 ... 0xFFFFFFFF	No	GRFID that defined the graphics-block for this vehicle. To compare this with other grfids, use the builtin function `str2number()` to convert the other GRFID to a number as well.
vehicle_type_id	0 ... 65535	No	GRF-local ID of the vehicle, equal to the item ID. Note that vehicles from other NewGRFs may have the same ID, so you'll generally have to check the `grfid` as well.
vehicle_is_hidden	[0 \| 1]	No	Value is 1 if the vehicle is hidden in a depot or tunnel.
vehicle_is_stopped	[0 \| 1]	No	Value is 1 if the vehicle is stopped, or if it is braking for a stop (trains only).
vehicle_is_crashed	[0 \| 1]	No	Value is 1 if the vehicle has crashed.
vehicle_is_broken	[0 \| 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 1.3 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 \| 1]	No	Value is 1 if the vehicle is inside a depot

Variables that require an argument

name	Argument	value range	available in purchase list?	comment
count_veh_id	The vehicle ID to look for.	0..255	No	The number of vehicles in the current consist that have the given ID.

Vehicle callbacks

The following table contains a list of available vehicle callbacks. Additionally, it's possible to provide cargo-specific graphics, using the identifier from the 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 default callback is used instead. Cargo-specific graphics callbacks are never called from the purchase menu, refer to the purchase callback below instead.

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

Name	Available for	In purchase menu?	value range	comment
default	All	Yes, unless `purchase` is set separately	Sprite group	'Normal' vehicle graphics, if no cargo-specific graphics apply. See also the section on 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 `dual_headed` 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 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 random switch for more information.
cargo_subtype_text	All	No	String, or CB_RESULT_NO_TEXT	With this callback, you can display extra text after the cargo in the vehicle information window. This callback is called during refitting, with succesively increased values of the `cargo_subtype` 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 `cargo_subtype` variable, so it can be used later for other things. In the HEQS grf for example, this mechanism is used to let the user choose between different capacities of the same vehicle.
additional_text	All	Yes, only	String	Additional text to show in the purchase list.
colour_mapping	All	Yes, unless `purchase_colour_mapping` 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 here for a list of default palettes. See the builtin function `reserve_sprites()` for info on how to allocate your own sprite. For performance, the result is cached and only updated if the `every_32_days` 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 `colour_mapping` 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. `extra_callback_info1` contains the sound event, see the table below. Return SOUND_XXX (see here) to return a default sound. `sound("soundfile")` imports a sound from a .wav file. `import_sound(grfid, number)` 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. `extra_callback_info1` contains 1 during the first call, 2 during the second, etc. Note that callback may be called from the purchase list, using vehicle variables is not possible. Or CB_RESULT_REVERSED_VEHICLE to the returned vehicle ID to display the vehicle backwards. For NML 0.2 and lower the vehicle ID of the articulated part must be in the range 0 .. 127.
can_attach_wagon	Trains	No	String or CB_RESULT_ATTACH_XXX	Called when a wagon is being attached, to allow or disallow attaching. This callback has to be defined at the engine. However, variables in the `SELF` scope refer to the wagon being attached, the `PARENT` scope refers to the engine that the wagon is being attached to. Return a string to disallow with the string as error message. Return CB_RESULT_ATTACH_DISALLOW to disallow with standard message ("incompatible railtypes"), CB_RESULT_ATTACH_ALLOW to allow or CB_RESULT_ATTACH_ALLOW_IF_RAILTYPES to allow if the railtypes match (default).

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

Name	Available for	In purchase menu?	comment
loading_speed	All	No
speed	All	Yes, unless `purchase_speed` is set separately	Units are not (yet) available
cost_factor	All	Yes, only
running_cost_factor	All	Yes, unless `purchase_running_cost_factor` is set separately
refit_cost	1.2 All	Yes	0 .. 16377 as refit cost. Add `CB_RESULT_AUTOREFIT` if you want to allow autorefit.
cargo_age_period	All	No
cargo_capacity	All except aircraft	Yes, unless `purchase_cargo_capacity` is set separately
passenger_capacity	Aircraft	Yes, unless `purchase_passenger_capacity` is set separately
mail_capacity	Aircraft	Yes, unless `purchase_mail_capacity` is set separately
range	Aircraft	Yes, unless `purchase_range` is set separately
visual_effect_and_powered	Trains	No
visual_effect	Road Vehicles, Ships	No
power	Trains, Road Vehicles	Yes, unless `purchase_power` is set separately	Units are not (yet) available
weight	Trains, Road Vehicles	Yes, unless `purchase_weight` is set separately	Units are not (yet) available
length	Trains, Road vehicles	No
tractive_effort_coefficient	Trains, Road Vehicles	Yes, unless `purchase_tractive_effort_coefficient` is set separately	Value range is 0 .. 255 instead of 0 .. 1.
bitmask_vehicle_info	Trains	No

Sprites in GUI

1.2 Since OpenTTD r23080 you can use variable extra_callback_info1 to display different sprites in the GUI and on the map. Currently these cases are available:

Lowest byte of extra_callback_info1	Meaning
0x00	Vehicle is drawn in a viewport, i.e. on the map.
0x01..0x0F	reserved
0x10	Vehicle is drawn in the depot GUI.
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

The other bytes of variable extra_callback_info1 are reserved, and must be masked. The cases 0x20..0x2F are called using the purchase-callback, the other cases are called for the default- or cargo-specific callbacks.

Sound events

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

NML:Vehicles

Contents

Properties common to all vehicle types

Refittability

Engine life cycle

Sorting vehicles in the purchase list

Train properties

Road vehicle properties

Ship properties

Aircraft properties

Vehicle variables

Variables without parameter

Variables that require an argument

Vehicle callbacks

Sprites in GUI

Sound events

Navigation menu

Page actions

Page actions

Personal tools

Navigation

links

wiki

Search

Tools

Advertisements