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 |
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. |
name | use |
---|---|
VEH_CB_VISUAL_EFFECT_AND_POWERED | decide upon whether a wagon has power |
VEH_CB_WAGON_LENGTH | decide upon the length of the wagon |
VEH_CB_LOAD_AMOUNT | decide upon the loading speed (amount loaded per tick) |
VEH_CB_REFITTED_CAPACITY | decide upon the capacity after refit |
VEH_CB_ARTICULATED_PARTS | decide upon the ID of the next vehicle added to the articulated vehicle chain |
VEH_CB_CARGO_SUFFIX | decide upon cargo subtype display for refit |
VEH_CB_CAN_ATTACH_WAGON | decide whether a wagon can be attached |
VEH_CB_TEXT_PURCHASE_SCREEN | decide upon an additional text for the purchase screen |
VEH_CB_COLOUR_MAPPING | decide upon the colour mapping instead of company colour |
VEH_CB_START_STOP_CHECK | decide whether a vehicle may be started. Return 0xFF to succeed or an error message. |
VEH_CB_32DAY | Triggers one or both of |
VEH_CB_SOUND_EFFECT | decide whether and which sound is being played for certain situations |
VEH_CB_AUTOREPLACE_SELECT | decide upon appropriate replacement vehicles |
VEH_CB_VEHICLE_PROPERTIES | Change vehicle properties |
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). Example:
switch (FEAT_TRAINS, SELF, tank_wagon_cb_property_weight_switch, cargo_type_in_veh) { // wagons transporting food need some extra stuff and are heavier WATR: return 25; MILK: return 25; CB_FAILED; // use value set in the property block for other cargos } switch (FEAT_TRAINS, SELF, tank_wagon_cb_property_switch, extra_callback_info1) { PROP_TRAINS_WEIGHT : tank_wagon_cb_property_weight_switch; PROP_TRAINS_CARGO_CAPACITY : tank_wagon_cb_capacity_switch; CB_FAILED; // we don't set other properties } switch (FEAT_TRAINS, SELF, tank_wagon_switch, current_callback) { VEH_CB_REFITTED_CAPACITY: tank_wagon_cb_capacity_switch; // switch not shown here VEH_CB_VEHICLE_PROPERTIES: tank_wagon_cb_property_switch; tank_wagon_graphics_switch; // go to graphics branch, if no callback asked for; not shown here } item(FEAT_TRAINS, tank_wagon) { property { callback_flags: VEH_CBF_REFITTED_CAPACITY; // activate callback cargo_capacity: 30; weight: 24 ton; } graphics { tank_wagon_switch; } }
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, ...) | =0 | 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 | |
non_refittable_cargo_classes | bit set of cargo classes | yes | |
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 | multiplicator to the base purchase cost |
running_cost_factor | 0 ... 255 | =0 | multiplicator 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.
property | value range | available for articulated vehicle | comment |
---|---|---|---|
sprite_id | SPRITE_ID_NEW_TRAIN | yes | defines base set spriteID to use or this constant |
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 or allow the vehicle to be flipped (reversed) in the depot |
refit_cost | yes | in 50% units of the purchase price cost base | |
callback_flags | bitmask(VEH_CBF_XXX, ...) | yes | 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 | (cargo units) | yes | |
weight | 0 .. 1279 t (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 | |
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 wagon. 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 | |
bitmask_vehicle_info | 8-bit bitmask | yes | Used for obtaining bitmask_consist_info |
property | value range | available for articulated vehicle | comment |
---|---|---|---|
sprite_id | SPRITE_ID_NEW_ROADVEH | yes | define base set spriteID to replace or this constant |
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. You can combine them with the binary or-operator (|). Use 0 if you don't want to set any of these flags. |
refit_costs | yes | in 25% units of the purchase price cost base | |
callback_flags | bitmask(VEH_CBF_XXX, ...) | yes | XXX = [LOAD_AMOUNT | REFITTED_CAPACITY | CARGO_SUFFIX | COLOUR_MAPPING | SOUND_EFFECT] |
running_cost_base | RUNNING_COST_XXX | =0 | 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. |
property | value range | comment |
---|---|---|
sprite_id | SPRITE_ID_NEW_SHIP | define base set spriteID to replace or this constant |
speed | 0 ... 127 km/h (speed units) | |
misc_flags | SHIP_FLAG_2CC | No other flags defined |
refit_costs | in 1/32 of the default refit cost base | |
callback_flags | bitmask(VEH_CBF_XXX, ...) | XXX = [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 than refittable_cargo_classes / non_refittable_cargo_classes have no effect. |
cargo_capacity | (units of cargo) | |
sound_effect | SOUND_XXX | See available sound effects. |
ocean_speed_fraction | 0 ... 1 | fraction of base speed on ocean tiles |
canal_speed_fraction | 0 ... 1 | fraction of base speed on canal tiles |
property | value range | comment |
---|---|---|
sprite_id | SPRITE_ID_NEW_AIRCRAFT | define base set spriteID to replace or this constant |
speed | 0 .. 3280 km/h (speed units) | |
misc_flags | bitmask(AIRCRAFT_FLAG_2CC) | |
refit_cost | 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 | ||
passenger_capacity | (units of cargo) | |
mail_capacity | (units of cargo) | |
sound_effect | SOUND_XXX | See available sound effects. |