NML documentation

# Vehicles

## Vehicle variables

Please note that while those 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 | comment
--- | --- | ---
position_in_consist | 0 ... 255 | 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 | Same as position_in_consist but counted from the end. The last wagon will get value 0.
num_vehs_in_consist | 1 ... 256 | 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 | 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 | 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 | 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 | cargo classes
most_common_refit | cargo class | cargo class most often refit to
bitmask_consist_info | Bitmask 8 bit | OR of all bitmask_vehicle_info of all vehicles (engines, wagons) in the consist. Only available for rail vehicles.
company_num | 0 ... 14 | company number of the vehicle owner. TTDPatch only supports up to 8 companies (0 ... 7)
company_type | PLAYERTYPE_XX | PLAYERTYPE_HUMAN, 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 | 0 ... 15 | index into company colour
company_colour2 | 0 ... 15 | index into company colour. It's the same as company_colour1, if no 2nd company colour is chosen.
aircraft_height | 0 ... 255 | Height difference between the aircraft and its shadow. 8 Units are equivalent to one height level on the map.
airport_type | AIRPORTTYPE_XX | AIRPORTTYPE_SMALL, AIRPORTTYPE_LARGE, AIRPORTTYPE_HELIPORT or AIRPORTTYPE_OILRIG
curv_info_prev_cur | -2 ... 2 | Curvature to the right is positive. 1 unit is 45 degrees.
curv_info_cur_next | -2 ... 2 | Curvature to the right is positive. 1 unit is 45 degrees.
curv_info_prev_next | -4 ... 4 | Curvature to the right is positive. 1 unit is 45 degrees.
motion_counter | 0 ... 15 | 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 |
cargo_unit_weight | weight per unit in 1/16t |
cargo_classes | cargo class | class of the currently transported cargo
vehicle_is_available | [0 | 1] | Value is 1 if the vehicle is available on the open market
vehicle_is_testing | [0 | 1] | Value is 1 if the vehicle is currently being tested
vehicle_is_offered | [0 | 1] | Value is 1 if the vehicle is currently being offered for exclusive preview
build_year | 0 ... 5000000 | 0-based year when the vehicle was built
direction | DIRECTION_XX | XX = NORTH, NORTHEAST, EAST, SOUTHEAST, SOUTH, SOUTHWEST, WEST or NORTHWEST. e.g. DIRECTION_NORTH.
cargo_capacity | 0 ... 65535 | Cargo capacity (number of units) of the vehicle
cargo_count | 0 ... 65535 | Number of cargo units of cargo in the vehicle
vehicle_type_id |  | ID of the vehicle
refit_cycle | 0 ... 255 | How many times the vehicle has been refitted to the same cargo type
vehicle_is_powered | [0 | 1] | vehicle provides power and is on the correct track type
vehicle_is_not_powered | [0 | 1] | vehicle is either on a wrong track type or it doesn't provide power at all
vehicle_is_potentially_powered | [0 | 1] | vehicle provides power, if it is on a suitable track type
vehicle_is_reversed | [0 | 1] | Value is 1 if the vehicle has reversed an odd number of times
built_during_preview | [0 | 1] | Value is 1 if the vehicle was built during the exclusive preview stage
current_railtype | 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 |  | Random triggers waiting to be matched. (see Random switch)
random_bits | 0 ... 255 | Random data that can be used to randomize certain descisions. (see Random switch)
grfid | 0 ... 0xFFFFFFFF | GRFID that defined the graphics-block for this vehicle.
vehicle_is_hidden | [0 | 1] | Value is 1 if the vehicle is hidden in a depot or tunnel.
vehicle_is_stopped | [0 | 1] | Value is 1 if the vehicle is stopped, or if it is braking for a stop (trains only).
vehicle_is_crashed | [0 | 1] | Value is 1 if the vehicle has crashed.
vehicle_is_broken | [0 | 1] | Value is 1 if the vehicle is broken down.
date_of_last_service | date(year, month, day) | Not valid before 1920 and after 2090.
breakdowns_since_last_service | 0 ... 255 | Number of breakdowns since the last service
reliability | 0 ... 100 | Reliability (percentage)
age_in_days | 0 ... 65535 | Vehicle age in days.
max_age_in_days | 0 ... 65535 | Maximum vehicle age in days.
current_speed | (speed units) | The current speed of the vehicle in m/s
max_speed | (speed units) | The maximum speed of the vehicle in m/s
vehicle_is_in_depot | [0 | 1] | Value is 1 if the vehicle is inside a depot

### Variables that require an argument

name | Argument | value range | comment
--- | --- | --- | ---
count_veh_id | The vehicle ID to look for. | 0..255 | The number of vehicles in the current consist that have the given ID.

### Callbacks for vehicles

name | bit to set in callback_flags property | available for | return value | use
--- | --- | --- | --- | ---
VEH_CB_VISUAL_EFFECT_AND_POWERED | VEH_CBF_VISUAL_EFFECT_AND_POWERED | Trains | See property `visual_effect_and_powered` | decide the visual effect to use and whether a wagon has power
VEH_CB_VISUAL_EFFECT | VEH_CBF_VISUAL_EFFECT | Road Vehicles, Ships | See property `visual_effect` | decide the visual effect to use (road vehicles / ships)
VEH_CB_WAGON_LENGTH | VEH_CBF_WAGON_LENGTH | Trains, Road Vehicles | See train property `shorten_vehicle` | decide upon the length of the wagon (note: RVs have no equivalent property)
VEH_CB_LOAD_AMOUNT | VEH_CBF_LOAD_AMOUNT | All | See property `loading_speed` | decide upon the loading speed (amount loaded per tick)
VEH_CB_REFITTED_CAPACITY | VEH_CBF_REFITTED_CAPACITY | All | Cargo capacity 0 ... 255 | decide upon the capacity after refit
VEH_CB_ARTICULATED_PARTS | VEH_CBF_ARTICULATED_PARTS | Trains, Road Vehicles | ID of vehicle to attach, 0xFF if none | decide upon the ID of the next vehicle added to the articulated vehicle chain
VEH_CB_CARGO_SUFFIX | VEH_CBF_CARGO_SUFFIX | All | string | decide upon cargo subtype display for refit
VEH_CB_CAN_ATTACH_WAGON | None | Trains | string containing error message, or one of the following: 0xFD (disallow with message "incomatible railtypes"), 0xFE (allow) or 0xFF (allow if railtypes match) | decide whether a wagon can be attached
VEH_CB_TEXT_PURCHASE_SCREEN | None | All | string | decide upon an additional text for the purchase screen
VEH_CB_COLOUR_MAPPING | VEH_CBF_COLOUR_MAPPING | All | sprite number | decide upon the colour mapping instead of company colour
VEH_CB_START_STOP_CHECK | None | All | string containing error message, or 0xFF to allow | decide whether a vehicle may be started/stopped.
VEH_CB_32DAY | None | All | bitmask | Triggers one or both of Trigger vehicle trigger 10 (bit 0) and Update colour map via VEH_CB_COLOUR_MAPPING (bit 1)
VEH_CB_SOUND_EFFECT | None | All | sound effect number | decide whether and which sound is being played for certain situations
VEH_CB_AUTOREPLACE_SELECT | None | All | vehicle ID | decide upon appropriate replacement vehicles (not implemented in OpenTTD)
VEH_CB_VEHICLE_PROPERTIES | None | All | property-dependent | Change vehicle properties, see below

In order to set properties for vehicles via callback `VEH_CB_VEHICLE_PROPERTIES` it's necessary to query the general variable `extra_callback_info1` which can take different values depending upon the vehicle type:

property | available for | value
--- | --- | ---
cost_factor | all | PROP_XXX_COST_FACTOR
running_cost_factor | all | PROP_XXX_RUNNING_COST_FACTOR
speed | all | PROP_XXX_SPEED
power | trains and road vehicles | PROP_XXX_POWER
weight | trains and road vehicles | PROP_XXX_WEIGHT
tractive_effort_coefficient | trains and road vehicles | PROP_XXX_TRACTIVE_EFFORT_COEFFICIENT
cargo_capacity | all except aircraft | PROP_XXX_CARGO_CAPACITY
passenger_capacity | aircraft | PROP_AIRCRAFT_PASSENGER_CAPACITY
mail_capacity | aircraft | PROP_AIRCRAFT_MAIL_CAPACITY
bitmask_vehicle_info | trains | PROP_TRAINS_BITMASK_VEHICLE_INFO

Where for the properties available for all vehicle types XXX can either be TRAINS, ROADVEHS, SHIPS or AIRCRAFT. Note also that the return values don't yet support units, you'll need to enter the properties untranslated (e.g. road vehicle weights are in quantities of 0.25 tons).

The following code is an example for the use of callbacks and most notably also the creation of articulated vehicles which can only be created by means of the VEH_CB_ARTICULATED_PARTS:

    /* Here would have to be definition of sprite sets and groups */

    /* callback for articulated vehicles: 4 wagons with special sprites for first and last */
    switch(FEAT_TRAINS, SELF, rail_engine_articulated_parts, extra_callback_info1) {
        1..2: return rail_wagon; // middle parts use rail wagons
    	3: return rail_engine;   // last part is this rail engine again
        CB_FAILED;               // no more than 4 vehicles
    }

    /* Set the (empty) weight of the vehicle depending on the cargo it carries */
    switch (FEAT_TRAINS, SELF, rail_wagon_cb_property_weight_switch, cargo_type_in_veh) {
        PASS: return 30; // Passenger wagons are heavier
        TOUR: return 30; // Tourists are also passengers
        CB_FAILED;       // use value set in the property block for other cargos
    }

    /* Set (conditionally) different properties of the train */
    switch (FEAT_TRAINS, SELF, rail_engine_cb_property_switch, extra_callback_info1) {
        PROP_TRAINS_WEIGHT          : rail_engine_cb_property_weight_switch;
        PROP_TRAINS_CARGO_CAPACITY  : rail_engine_cb_capacity_switch; // not shown here
        CB_FAILED;                                                    // we don't set other properties
    }

    /* Check for each (active) callback */
    switch (FEAT_TRAINS, SELF, rail_engine_switch, current_callback) {
        VEH_CB_REFITTED_CAPACITY:  rail_engine_cb_capacity_switch; // switch not shown here
        VEH_CB_VEHICLE_PROPERTIES: rail_engine_cb_property_switch;
        VEH_CB_ARTICULATED_PARTS: rail_engine_articulated_parts;
        rail_engine_graphics_switch; // go to graphics branch, if no callback asked for; not shown here
    }

    /* Define this rail engine */
    item(FEAT_TRAINS, rail_engine) {
        property {
            callback_flags:                 bitmask(VEH_CBF_ARTICULATED_PARTS, VEH_CBF_REFITTED_CAPACITY); // activate callbacks
            cargo_capacity:                 20;
            weight:                         24 ton;
        }
        graphics {
            rail_engine_switch;
        }
    }

## Properties common to all vehicle types

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_CLIMATES | 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, before reliability starts dropping.
retire_early | (years) | no | Number of years before model_life when no new vehicles can be bought. May be negative.
vehicle_life | 0 ... 255 (years) | no | Age of a vehicle when it gets old.
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 | example: `bitmask(PASS, MAIL, GOOD)`
loading_speed | 0 ... 255 (cargo units) | yes | Units of cargo loaded per tick. Default vehicles use 5 for trains and road vehicles, 10 for ships and 20 for aircraft
cost_factor | 0 ... 255 | =0 | multiplier to the base purchase cost
running_cost_factor | 0 ... 255 | =0 | multiplier to the base running costs

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 refittable_cargo_types | Result
--- | --- | --- | ---
No | Doesn't matter | No | Not refittable
No | Doesn't matter | Yes | Refittable
Yes | No | No | Refittable
Yes | No | Yes | Not refittable
Yes | Yes | No | Not refittable
Yes | Yes | Yes | Refittable

You should use refittable_cargo_classes and non_refittable_cargo_classes to decide to which cargos your vehicle is refittable, and only use refittable_cargo_types as a last resort to include/exclude some cargo type.

Note that the default cargo cannot be selected explicitly. Instead it is automatically set to use the first refittable cargo, whenever one of the refitting properties is set.

## 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 (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] 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 | Used to enable certain callbacks. XXX = [VISUAL_EFFECT_AND_POWERED | WAGON_LENGTH | REFITTED_CAPACITY | LOAD_AMOUNT | REFITTED_CAPACITY | CARGO_SUFFIX | COLOUR_MAPPING | SOUND_EFFECT]
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 (power units) | =0 |
running_cost_base | RUNNING_COST_XXX | =0 | XXX = [STEAM | DIESEL | ELECTRIC | ROADVEH | NONE]
dual_headed | [0 | 1] | =0 for both parts | 1 = dual_headed, otherwise normal engine
cargo_capacity | 0 .. 255 | yes |
weight | 0 .. 1279 ton (mass units) | =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 (power units) | =0 | Only wagons with a livery override for this engine will add power
tractive_effort_coefficient | 0 ... 1 | =0 |
air_drag_coefficient | 0 ... 1 | =0 |
shorten_vehicle | SHORTEN_TO_XXX | yes | XXX=[8_8 | 7_8 | ... | 1_8]
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 t (mass units) | =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 (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. 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 | Used to enable certain callbacks. XXX = [VISUAL_EFFECT, LOAD_AMOUNT | REFITTED_CAPACITY | CARGO_SUFFIX | COLOUR_MAPPING | SOUND_EFFECT]
running_cost_base | RUNNING_COST_XXX | set to RUNNING_COST_NONE | XXX = [STEAM | DIESEL | ELECTRIC | ROADVEH | NONE]
power | 0 ... 2550hp (power units) | =0 |
weight | 0 ... 63.75ton (mass units) | =0 |
tractive_effort_coefficient | 0 ... 1 | =0 |
air_drag_coefficient | 0 ... 1 | =0 |
cargo_capacity | 0 ... 255 | yes |
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.

## Ship properties

property | value range | comment
--- | --- | ---
sprite_id | SPRITE_ID_NEW_SHIP | Set this property to enable new graphics
speed | 0 ... 127 km/h (speed units) |
misc_flags | bitmask(SHIP_FLAG_2CC) | Bitmask with (currently) only one possible flag, set to 0 to disable
refit_cost | 0 ... 255 | in 1/32 of the default refit cost base
callback_flags | bitmask(VEH_CBF_XXX, ...) | Used to enable certain callbacks. XXX = [VISUAL_EFFECT, LOAD_AMOUNT | REFITTED_CAPACITY | CARGO_SUFFIX | COLOUR_MAPPING | SOUND_EFFECT]
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.
cargo_capacity | 0 ... 255 |
sound_effect | SOUND_XXX | See available sound effects.
ocean_speed_fraction | 0 ... 1 | fraction of base speed on ocean tiles (currently works in TTDPatch only)
canal_speed_fraction | 0 ... 1 | fraction of base speed on canal tiles (currently works in TTDPatch only)
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.

## Plane properties

property | value range | comment
--- | --- | ---
sprite_id | SPRITE_ID_NEW_AIRCRAFT | Set this property to enable new graphics
speed | 0 .. 3280 km/h (speed units) |
misc_flags | bitmask(AIRCRAFT_FLAG_2CC) | Bitmask with (currently) only one possible flag, set to 0 to disable
refit_cost | 0 ... 255 | in 1/32 of default refit cost base
callback_flags | bitmask(VEH_CBF_XXX, ...) | XXX = [LOAD_AMOUNT | REFITTED_CAPACITY | CARGO_SUFFIX | COLOUR_MAPPING | SOUND_EFFECT]
is_helicopter | AIRCRAFT_TYPE_XXX | XXX=[NORMAL | HELICOPTER]
is_large | AIRCRAFT_TYPE_XXX | XXX=[SMALL | LARGE]. Set to AIRCRAFT_TYPE_SMALL for helicopters.
acceleration | 0 ... 255 | In arbitrary units
passenger_capacity | 0 ... 65536 |
mail_capacity | 0 ... 255 |
sound_effect | SOUND_XXX | See available sound effects.