GRFSpecs - User contributions [en-gb]

CargoTypes

2016-01-17T12:06:17Z

FooBar: Added FIRS cargoes PHOS, PORE and VPTS

'''Cargo labels in OpenTTD'''

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

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

== Cargo Labels ==

The following cargo labels have been defined so far:

{| class="wikitable
|-
! Label
! Cargo Description
! [[Action0Cargos#CargoClasses_.2816.29|Cargo classes]]
! colspan="3" | Notes
|-
| align="center" colspan="2" | '''TTD Default Cargos'''
| align="center" colspan="4" | These cargos are present when no NewGRF is used
|-
| PASS
| Passengers
| 0001 Passengers
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|-
| COAL
| Coal
| 0010 Bulk
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|-
| MAIL
| Mail
| 0002 Mail
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|-
|OIL_
| Oil
| 0040 Liquid
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
|
|-
| LVST
| Livestock
| 0020 Piece goods
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
|
|-
| GOOD
| Goods
| 0004 Express
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|-
| GRAI
| Grain
| 0010 Bulk
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| Temperate; see also WHEA, MAIZ, CERE. YETI also adds 0200 Covered.
|-
| WOOD
| Wood
| 0020 Piece goods
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
|
|-
| IORE
| Iron Ore
| 0010 Bulk
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
|
|-
| STEL
| Steel
| 0020 Piece goods
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| Renamed "Metal" in FIRS, "Balls of Steel" in YETI
|-
| VALU
| Valuables
| 0008 Armoured
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
| Temperate; see also GOLD, DIAM
|-
| PAPR
| Paper
| 0020 Piece goods
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|
|-
| WHEA
| Wheat
| 0010 Bulk
|
|
|
| Arctic; see also GRAI, MAIZ, CERE
|-
| FOOD
| Food
| 0084 Express, refrigerated
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| YETI food has Refrigerated and Piece goods
|-
| GOLD
| Gold
| 0008 Armoured
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
| Arctic; see also VALU, DIAM
|-
| RUBR
|Rubber
|0040 Liquid
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|-
| FRUT
| Fruit
| 0090 Bulk, refrigerated
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| In FIRS: 00A4 Express, piece goods, refrigerated. In YETI: Piece goods, Covered.
|-
| MAIZ
| Maize
| 0010 Bulk
|
|
|
| Tropic; see also GRAI, WHEA, CERE
|-
| CORE
| Copper Ore
| 0010 Bulk
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|-
| WATR
| Water
| 0040 Liquid
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|
|-
| DIAM
| Diamonds
| 0008 Armoured
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| Tropic; see also VALU, GOLD
|-
| SUGR
| Sugar
| 0010 Bulk
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| Toyland. In FIRS 0030 Bulk, Piece Goods
|-
| TOYS
| Toys
| 0020 Piece goods
|
|
|
| Toyland
|-
| BATT
| Batteries
| 0020 Piece goods
|
|
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| Toyland
|-
| SWET
|Sweets (Candy)
|0004 Express
|
|
|
| Toyland
|-
| TOFF
|Toffee
|0010 Bulk
|
|
|
| Toyland
|-
| COLA
|Cola
|0040 Liquid
|
|
|
| Toyland
|-
| CTCD
|Cotton Candy (Candyfloss)
|0010 Bulk
|
|
|
| Toyland
|-
| BUBL
|Bubbles
|0020 Piece goods
|
|
|
| Toyland
|-
| PLST
|Plastic
|0040 Liquid
|
|
|
| Toyland; see also PLAS
|-
| FZDR
|Fizzy Drinks
|0020 Piece goods
|
|
|
| Toyland
|-
| align="center" colspan="2" | '''New Cargos'''
| align="center" colspan="4" | these cargos are only present when NewGRF industry sets are used
|-
| AORE
|Bauxite (Aluminium ore)
|0010 Bulk
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|-
| BEAN
|Beans
|0010 Bulk
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|-
| BEER
|Alcohol
|0064 Express, piece goods, liquids
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|-
| BDMT
|Building Materials
|0220 Piece goods, covered/sheltered
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
| In FIRS: 0030 Bulk, piece goods. In YETI only Piece goods.
|-
| BRCK
|Bricks
| 0020 Piece goods
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|
|-
| CERA
|Ceramics
| 0020 Piece goods
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|
|-
| CERE
|Cereals
| 0210 Bulk, covered/sheltered
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|<ref name="ecs_cargo_change" />
|-
| CLAY
|Clay
|0210 Bulk covered/sheltered
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
|
|-
| CMNT
|Cement
| 0210 Bulk covered/sheltered
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|
|-
| COPR
|Copper
|0020 Piece goods
|
|
|
|
|-
| DYES
|Dyes
| 0060 Piece goods, liquids
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|
|-
| ENSP
|Engineering Supplies
|0024 Express, piece goods
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|-
| EOIL
|Edible Oil
| 0060 Piece goods, liquids
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| Introduced in FIRS v1.4.5+ or 2.0
|-
| FERT
|Fertiliser
| 0030 Bulk, piece goods
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|<ref name="ecs_cargo_change" />
|-
| FICR
|Fibre crops
| 0030 Bulk, piece goods
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|-
| FISH
|Fish
| 0084 Express, refrigerated
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|-
| FMSP
|Farm Supplies
|0024 Express, piece goods
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|-
| GLAS
|Glass
| 0420 Piece goods, oversized
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|
|-
| GRVL
|Gravel / Ballast
|0010 Bulk
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
|Renamed "Stone" for YETI
|-
| JAVA
|Coffee
| 0020 Piece Goods
|
| style="background: #1AD74C; color: black" | [[ttwiki:FIRS|FIRS]]
|
| Units in FIRS are 'bags'
|-
| LIME
|Lime stone
| 0010 Bulk
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|
|-
| MILK
|Milk
|00C4 Express, liquid, refrigerated
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|-
| MNSP
|Manufacturing Supplies
|0024 Piece Goods, express
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|-
| NITR
|Nitrate
|0010 Bulk
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|-
| OLSD
|Oil seed
| 0210 Bulk, covered/sheltered
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|<ref name="ecs_cargo_change" />
|-
| PETR
|Petrol / Fuel Oil
| 0040 Liquid
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|-
| PHOS
|Phosphate
|0010 Bulk
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|-
| PLAS
|Plastic
| 0060 Piece goods, liquid
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|
|-
| PORE
|Pyrite Ore
|0010 Bulk
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|-
| POTA
|Potash
| 0210 Bulk, covered/sheltered
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|<ref name="ecs_cargo_change" />
|-
| RCYC
|Recyclables
|0220 Piece Goods, covered
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|-
| RFPR
|Refined products
| 0040 Liquid
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
|
|-
| SAND
|Sand
| 0010 Bulk
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|-
| SCMT
|Scrap Metal
|1010 Bulk, non-pourable
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|-
| SGBT
|Sugar beet
|0010 Bulk
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| not in tropical
|-
| SGCN
|Sugarcane
|1010 Bulk, non-pourable
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
| only tropical
|-
| SULP
|Sulphur
| 0210 Bulk, covered/sheltered
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|<ref name="ecs_cargo_change">ECS cargo classes changed as of Dec 31, 2010</ref>
|-
| TOUR
|Tourists
| 0005 Passengers, express
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|
|-
| URAN
|Uranium
|0110 Bulk, Hazardous
|
|
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
|
|-
| VEHI
|Vehicles
| 0420 Piece goods, oversized
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
|
|-
| VPTS
|Vehicle Parts
|0024 Piece Goods, express
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|-
| WDPR
|Wood Products
| 0030 Bulk, piece goods
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|
|-
| WOOL
|Wool
| 0220 Piece goods, covered/sheltered
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|<ref name="ecs_cargo_change" />
|-
| YETI
|Workers, YETI dudes
|0404 Express, Oversized
|
|
| style="background: #009fe3; color: black" | [[ttwiki:YETI|YETI]]
|
|-
| align="center" colspan="2" |'''Special Cargos'''
| align="center" colspan="4" | these cargos are for use outside industry sets and do not represent transporting anything
|-
| DFLT
|'Default'
| ---- None
|
|
|
| Used by andythenorth to identify default cargo graphics in newgrfs that use code/graphics generation.

Not intended to be used as an actual cargo in translation tables.
|-
| GEAR
|Locomotive regearing
|8000 Special
|
|
|
| Using this cargo may make your vehicle set incompatible with some industry sets

use CB36 instead to set capacity to 0
|-
| align="center" colspan="2" |'''Deprecated Cargos'''
| align="center" colspan="4" | these cargos are not used by any current industry set, and are listed here for backwards compatibility
|-
| FRVG
|Fruit (and optionally Vegetables)
|00A4 Express, piece goods, refrigerated
|
|
|
| Deprecated FIRS cargo. Replaced by FRUT for FIRS > v1.3.0
|-
| FUEL
|Fuel
|0040 Liquid
|
|
|
|Use PETR for refined-oil fuel
|-
| RSGR
|Raw Sugar
|0010 Bulk
|
|
|
| Deprecated in FIRS. See SGBT and SGCN
|-
| SCRP
|Scrap Metal
|0010 Piece Goods
|
|
|
| Deprecated in FIRS, use SCMT instead
|-
| TWOD
|Tropic Wood
|0020 Piece goods
|
|
|
| formerly intended as a default cargo
|-
| WSTE
|Waste
|0010 Bulk
|
|
|
| Deprecated in FIRS.
|}

<references />

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

NML:Railtypes

2012-07-29T12:20:06Z

FooBar: Add: default values for cost factors

{{NMLNavPropVarCB}}

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

==Railtype properties==

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

===Sort order===

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

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

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

===Base speeds for curves===

The base speeds relevant for the curve_speed_multiplier are:

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

==Railtype variables==

{| class="t"
! name
! value range
! comment
|-
| terrain_type
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|
|-
| enhanced_tunnels
| 0
| should custom tunnel entrances be modified other values than 0 might be returned
|-
| level_crossing_status
| LEVEL_CROSSING_CLOSED, LEVEL_CROSSING_OPEN
|
|-
| build_date
| 0 .. 5000000
| for depots only: build date of the depot in days since 0
|}

==Railtype callbacks==

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

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

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

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

[[File:railtype_gui.png]]

==== track_overlay ====

[[File:railtype_overlay.png]]

==== underlay ====

[[File:railtype_underlay.png]]

==== level_crossings ====

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

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

[[File:railtype_levelcrossing.png]]

==== depots ====

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

==== fences ====

[[File:railtype_fences.png]]

==== tunnel_overlay ====

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

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

Illustration: [[File:RailtypeTunnelExample.png]]

==== signals ====

This callback can be used to supply custom signal graphics.

The resulting sprite set must consist of 8 sprites, corresponding to the following signal directions: SW-facing, NE-facing, NW-facing, SE-facing, E-facing, W-facing, S-facing, N-facing. Variable <code style:darkgreen>extra_callback_info2</code> contains information about the kind of signal to be drawn. If resolving fails or results in an empty sprite group, the matching base set sprite will be used instead.

'''Format of extra_callback_info2:''' 0xRRTTVVSS

{| |-
! TT: Signal type !! Meaning
|-
| 0 || Normal block signal
|-
| 1 || Entry pre-signal
|-
| 2 || Exit pre-signal
|-
| 3 || Combo pre-signal
|-
| 4 || Two-way path signal
|-
| 5 || One-way path signal
|-
| all other values || Reserved
|}

{| |-
! VV: Signal variant !! Meaning
|-
| 0 || Light (electric) signal
|-
| 1 || Semaphore
|-
| all other values || Reserved
|}

{| |-
! SS: Signal state !! Meaning
|-
| 0 || Red signal
|-
| 1 || Green signal
|-
| all other values || Reserved
|}

The most significant byte (RR) is reserved and must be and-masked out.

<code style:darkgreen>extra_callback_info1</code> can be used to distinguish between map and GUI sprites:
{| |-
! Lowest byte of [[GlobalVariables#Extra_callback_info_.2810_.2F_-.29_and_.2818_.2F_-.29|variable 10]] !! Meaning
|-
| 0 || Signal is drawn in a viewport, i.e. on the map.
|-
| 0x10 || Signal is drawn in the signal GUI. The returned sprite set must still have 8 sprites, but OpenTTD will only use the 7th sprite, so all other sprites can be empty.
|-
| all other values || Reserved
|}
The other bytes of <code style:darkgreen>extra_callback_info1</code> are reserved, and must be masked.

===Example code===

A typical implementation for railtypes can look like:

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

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

NML:General

2012-07-17T14:04:57Z

FooBar: loading_stage constants must be written as LOADINGSTAGE_XXX

{{NMLNavPropVarCB}}

==General variables==

A number of global variables are available. Some are only available in switch-blocks, while others can be used in any expression. This is indicated by the second column in the following table:

{| class="t"
! name
! Available outside switch blocks
! Value range
! Comment
|-
| <code style="color:green">ttd_platform</code>
| Yes
| <code style="color:green">PLATFORM_TTDPATCH</code> or <code style="color:green">PLATFORM_OPENTTD</code>
|
|-
| <code style="color:green">ttdpatch_version</code>
| Yes
|
|
|-
| <code style="color:green">openttd_version</code>
| Yes
|
| Use <code style="color:green">version_openttd(MAJOR, MINOR, BUILD)</code> to test and compare for a release version and <code style="color:green">version_openttd(MAJOR, MINOR, BUILD, REVISION)</code> to test for a specific svn version of OpenTTD
|-
| <code style="color:green">current_palette</code>
| Yes
| <code style="color:green">PALETTE_DOS</code> or <code style="color:green">PALETTE_WIN</code>
|
|-
| <code style="color:green">current_date</code>
| No
| days since year 0
| Use <code style="color:green">date(year, month, day)</code> to compare with.
|-
| <code style="color:green">current_year</code>
| No
| years since year 0
|
|-
| <code style="color:green">current_month</code>
| No
| 0 .. 11
|
|-
| <code style="color:green">current_day_of_month</code>
| No
| 0 .. 30
|
|-
| <code style="color:green">current_day_of_year</code>
| No
| 0 .. 364 (365 in leap years)
|
|-
| <code style="color:green">is_leapyear</code>
| No
| 0 or 1
|
|-
| <code style="color:green">date_loaded</code>
| Yes
| days since year 0
| Set to the time of game load, which is the current date in single player, and the date the server started in multiplayer. This to prevent desyncs.
|-
| <code style="color:green">year_loaded</code>
| Yes
| years since year 0
| See <code style="color:green">date_loaded</code>.
|-
| <code style="color:green">starting_year</code>
| Yes
| years since year 0
| Years before 1920 are clamped to 1920
|-
| <code style="color:green">animation_counter</code>
| No
| 0 .. 65535
| Increased by 1 each tick
|-
| <code style="color:green">climate</code>
| Yes <ref name=gamechange>The value of these variables can change during the game. Reading them from a switch block (which reads the current value) may result in a different value than in the rest of the code (which is evaluated when the game is loaded).</ref>
| <code style="color:green">CLIMATE_XXX</code> with <code style="color:green">XXX</code> = [<code style="color:green">TEMPERATE</code> <nowiki>|</nowiki> <code style="color:green">ARCTIC</code> <nowiki>|</nowiki> <code style="color:green">TROPICAL</code> <nowiki>|</nowiki> <code style="color:green">TOYLAND</code>]
|
|-
| <code style="color:green">game_mode</code>
| Yes
| <code style="color:green">GAMEMODE_XXX</code> with <code style="color:green">XXX</code> = [<code style="color:green">MENU</code> <nowiki>|</nowiki> <code style="color:green">GAME</code> <nowiki>|</nowiki> <code style="color:green">EDITOR</code>]
|
|-
| <code style="color:green">loading_stage</code>
| Yes
| <code style="color:green">LOADINGSTAGE_XXX</code> with <code style="color:green">XXX</code> = [<code style="color:green">INITIALIZE</code> <nowiki>|</nowiki> <code style="color:green">RESERVE</code> <nowiki>|</nowiki> <code style="color:green">ACTIVATE</code> <nowiki>|</nowiki> <code style="color:green">TEST</code>]
| 'Phase' of the GRF loading process.
|-
| <code style="color:green">difficulty_level</code>
| Yes <ref name=gamechange />
| <code style="color:green">DIFFICULTY_XXX</code> with <code style="color:green">XXX</code> = [<code style="color:green">EASY</code> <nowiki>|</nowiki> <code style="color:green">MEDIUM</code> <nowiki>|</nowiki> <code style="color:green">HARD</code> <nowiki>|</nowiki> <code style="color:green">CUSTOM</code>]
|
|-
| <code style="color:green">display_options</code>
| No
| bitmask of <code style="color:green">DISPLAY_XXX</code> with <code style="color:green">XXX</code> = [<code style="color:green">TOWN_NAMES</code> <nowiki>|</nowiki> <code style="color:green">STATION_NAMES</code> <nowiki>|</nowiki> <code style="color:green">SIGNS</code> <nowiki>|</nowiki> <code style="color:green">ANIMATION</code> <nowiki>|</nowiki> <code style="color:green">FULL_DETAIL</code>]
| Use <code style="color:green">hasbit(display_options, DISPLAY_XXX)</code> to test a particular bit.
|-
| <code style="color:green">desert_paved_roads</code>
| Yes <ref name=readwrite>These variables can be written as well as read. Use a normal assignment, for example:

<pre style="color:blue">
traininfo_y_offset = -2;
</pre></ref>
| 0 or 1
| If 1, desert roads have pavement and street lights.
|-
| <code style="color:green">train_width_32_px</code>
| Yes <ref name=readwrite />
| 0 or 1
| If 1, train vehicles are 32 instead of 29 pixels wide in the depot view.
|-
| <code style="color:green">traininfo_y_offset</code>
| Yes <ref name=readwrite />
| -128 .. 127
| Used to correctly position the depot view of trains.
|-
| <code style="color:green">snowline_height</code>
| No
| {{nml|0.2}} 16 .. 120 in steps of 8, or 0xFF if no snow.
{{nml|0.3}} 0..max_tile_height, or 0xFF if no snow.
| {{nml|0.2}} One tile height is equivalent to 8 units.
{{nml|0.3}} It's the height in tiles.
|-
| <code style="color:green">traffic_side</code>
| Yes <ref name=gamechange />
| <code style="color:green">TRAFFIC_SIDE_LEFT</code> or <code style="color:green">TRAFFIC_SIDE_RIGHT</code>
|
|-
| <code style="color:green">freight_trains</code>
| Yes
| 1 .. 255
| Weight multiplier for freight trains
|-
| <code style="color:green">plane_speed</code>
| Yes
| 1 .. 4
| Speed multiplier for planes. Value of 1 is equal to the original speed (1/4), while 4 means that planes move at full speed (4/4)
|-
| <code style="color:green">ttdpatch_flags</code>
| Yes
|
|
|-
| <code style="color:green">current_callback</code>
| No
|
| Set to the ID of the current callback, useful for old-style callbacks.
|-
| <code style="color:green">extra_callback_info1</code>
| No
| Varies
| Extra callback information, meaning differs per callback.
|-
| <code style="color:green">extra_callback_info2</code>
| No
| Varies
| Extra callback information, meaning differs per callback.
|-
| <code style="color:green">last_computed_result</code>
| No
|
| Result of the last (previously evaluated) switch block.
|-
| <code style="color:green">base_sprite_2cc</code>
| Yes
| 0 .. 65535
| Base sprite for 2cc (dual company colour) colour-maps
|-
| <code style="color:green">map_type</code>
| Yes
| <code style="color:green">MAP_TYPE_XXX</code> with <code style="color:green">XXX</code> = [<code style="color:green">RECTANGULAR</code> <nowiki>|</nowiki> <code style="color:green">X_BIGGER</code> <nowiki>|</nowiki> <code style="color:green">Y_BIGGER</code>]
|
|-
| <code style="color:green">map_min_edge</code>
| Yes
| 64 .. 2048
| Length of the smallest map edge (in tiles)
|-
| <code style="color:green">map_max_edge</code>
| Yes
| 64 .. 2048
| Length of the biggest map edge (in tiles)
|-
| <code style="color:green">map_x_edge</code>
| Yes
| 64 .. 2048
| Length of the x (top-left) map edge (in tiles)
|-
| <code style="color:green">map_y_edge</code>
| Yes
| 64 .. 2048
| Length of the y (top-right) map edge (in tiles)
|-
| <code style="color:green">map_size</code>
| Yes
| 64*64 .. 2048*2048
| Total number of tiles on the map
|-
| <code style="color:green">long_bridges</code>
| Yes
| 0 or 1
|
|-
| <code style="color:green">gradual_loading</code>
| Yes
| 0 or 1
|
|-
| <code style="color:green">bridge_speed_limits</code>
| Yes
| {{ttdp|}} 0 or 1 {{ottd|}} Always 1
|
|-
| <code style="color:green">signals_on_traffic_side</code>
| Yes
| 0 or 1
|
|-
| <code style="color:green">electrified_railways</code>
| Yes
| 0 or 1
|
|-
| <code style="color:green">unified_maglev</code>
| Yes
| {{ttdp|}} 0 .. 3 {{ottd|}} Always 3
|
|-
| <code style="color:green">temperate_snowline</code>
| Yes
| {{ttdp|}} 0 or 1 {{ottd|}} Always 0
|
|-
| <code style="color:green">dynamic_engines</code>
| Yes
| 0 or 1
|
|-
| <code style="color:green">variable_runningcosts</code>
| Yes
| {{ttdp|}} 0 or 1 {{ottd|}} Always 1
|
|-
| <code style="color:green">newtrains</code>
| Yes
| {{ttdp|}} 0 or 1 {{ottd|}} Always 1
|
|-
| <code style="color:green">newrvs</code>
| Yes
| {{ttdp|}} 0 or 1 {{ottd|}} Always 1
|
|-
| <code style="color:green">newships</code>
| Yes
| {{ttdp|}} 0 or 1 {{ottd|}} Always 1
|
|-
| <code style="color:green">newplanes</code>
| Yes
| {{ttdp|}} 0 or 1 {{ottd|}} Always 1
|
|-
| <code style="color:green">newhouses</code>
| Yes
| {{ttdp|}} 0 or 1 {{ottd|}} Always 1
|
|-
| <code style="color:green">newindustries</code>
| Yes
| {{ttdp|}} 0 or 1 {{ottd|}} Always 1
|
|-
| <code style="color:green">newcargos</code>
| Yes
| {{ttdp|}} 0 or 1 {{ottd|}} Always 1
|
|}

<references />

Standardized Railtype Scheme

2012-07-13T12:30:55Z

FooBar: Add S eyecandy speedlimit class and list what sets use custom speed limit classes

This railtype label scheme aims to bring order to the uncontrolled growth of railtype labels. It groups the rail types into what matters from a technical perspective. The scheme provides a standardized way of defining railtype labels, based on track gauge and type, speed class, allowable axle weight and electrification type.

It is the explicit intent of this scheme to decouple track sets from vehicle sets to facilitate easy mixing. This way the player can select a track set of choice to go with a train set of choice. It allows the player to play with or without axle load classes, or with or without speed limit classes, simply by loading a track set that does or does not provide these features. In some cases it will also be possible to combine niche track sets, for instance a standard gauge track set with a narrow gauge and a metro track set.

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

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

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

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

=== Speed limit class [*X**] ===
The second position in the railtype label defines the speed limit class. These classes do not map to a fixed numeric value, but are used to define an internal speed limit order for the track set. This means that if your track set has two different speed limits for track types that are otherwise identical, you'll use letters A and B here. In case of three different speed limits, use A, B and C. In case your track set does not employ speed limits, always use A. Train sets do not care about the speed limit, and will always set the lowest speed class, i.e. A.

This gives for instance the following options:

<div style="float:left;">
<div style="float:left;">
{|
! !!Speed limit class
|-
|A ||no speed limits
|}
</div>
<div style="float:left;">
 OR 
</div>
</div>
<div style="float:left;">
<div style="float:left;">
{|
! !!Speed limit class
|-
|A ||low speed
|-
|B ||high speed
|}
</div>
<div style="float:left;">
 OR 
</div>
</div>
<div style="float:left;">
<div style="float:left;">
{|
! !!Speed limit class
|-
|A ||low speed
|-
|B ||medium speed
|-
|C ||high speed
|}
</div>
<div style="float:left;">
 etc. 
</div>
</div>
<div style="clear:left;"></div>

The speed limit class may also be used for some advanced features of the label scheme, like specialized track types and eyecandy purposes. Be careful not to break the compatibility with other sets when using the speed limit class for these purposes.

An example of a special use is rack rail. In the French set it is used to give rack rail engines a higher speed and TE than normal rail engines when used on rack rail. When defining trains with a special speed limit class, always allow a fallback to speed limit class A via the railtype table.

An example of eyecandy use are urban tracks. These are a variation of regular tracks, but with concrete ground tiles to better match the urban environment. Train sets must not define vehicles for eyecandy classes.

The following special and eyecandy classes have been defined so far:

{|
! !!Description !!Type !!Used by
|-
|A-H ||speed limits ||colspan="2"|reserved
|-
|R ||rack rail ||special ||French Set Rails
|-
|S ||subterranean ||eyecandy ||Metro Track Set
|-
|U ||urban ||eyecandy ||Metro Track Set
|}

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

A train set should set the appropriate axle weight for each train via the railtype label, as to make the set work with track sets that do provide tracks with different weight limits, even if you don't care about it for your trainset. Split all vehicles of a certain track gauge/type into five groups of similar axle weight. The group with the lowest axle weights will get class '''A''', the second lowest class '''B''', etc. up to the group with the highest axle weights which will get class '''E'''. Do the same for the other track gauge/types if your train set has those.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== Summary for track sets ==
This section summarizes the above for track sets.

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

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

== Summary for train sets ==
This section summarizes the above for train sets.

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

Be as specific as you want when selecting the railtype, it is the job of the track set to select a playable, reduced subset out of all possible type combinations.

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

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

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

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

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

NML:Railtypes

2012-07-12T19:58:30Z

FooBar: callback depot should be depots (plural)

{{NMLNavPropVarCB}}

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

==Railtype properties==

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

===Sort order===

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

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

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

===Base speeds for curves===

The base speeds relevant for the curve_speed_multiplier are:

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

==Railtype variables==

{| class="t"
! name
! value range
! comment
|-
| terrain_type
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|
|-
| enhanced_tunnels
| 0
| should custom tunnel entrances be modified other values than 0 might be returned
|-
| level_crossing_status
| LEVEL_CROSSING_CLOSED, LEVEL_CROSSING_OPEN
|
|-
| build_date
| 0 .. 5000000
| for depots only: build date of the depot in days since 0
|}

==Railtype callbacks==

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

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

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

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

[[File:railtype_gui.png]]

==== track_overlay ====

[[File:railtype_overlay.png]]

==== underlay ====

[[File:railtype_underlay.png]]

==== level_crossings ====

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

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

[[File:railtype_levelcrossing.png]]

==== depot ====

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

[[File:railtype_fences.png]]

==== tunnel_overlay ====

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

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

Illustration: [[File:RailtypeTunnelExample.png]]

==== signals ====

This callback can be used to supply custom signal graphics.

The resulting sprite set must consist of 8 sprites, corresponding to the following signal directions: SW-facing, NE-facing, NW-facing, SE-facing, E-facing, W-facing, S-facing, N-facing. Variable <code style:darkgreen>extra_callback_info2</code> contains information about the kind of signal to be drawn. If resolving fails or results in an empty sprite group, the matching base set sprite will be used instead.

'''Format of extra_callback_info2:''' 0xRRTTVVSS

{| |-
! TT: Signal type !! Meaning
|-
| 0 || Normal block signal
|-
| 1 || Entry pre-signal
|-
| 2 || Exit pre-signal
|-
| 3 || Combo pre-signal
|-
| 4 || Two-way path signal
|-
| 5 || One-way path signal
|-
| all other values || Reserved
|}

{| |-
! VV: Signal variant !! Meaning
|-
| 0 || Light (electric) signal
|-
| 1 || Semaphore
|-
| all other values || Reserved
|}

{| |-
! SS: Signal state !! Meaning
|-
| 0 || Red signal
|-
| 1 || Green signal
|-
| all other values || Reserved
|}

The most significant byte (RR) is reserved and must be and-masked out.

<code style:darkgreen>extra_callback_info1</code> can be used to distinguish between map and GUI sprites:
{| |-
! Lowest byte of [[GlobalVariables#Extra_callback_info_.2810_.2F_-.29_and_.2818_.2F_-.29|variable 10]] !! Meaning
|-
| 0 || Signal is drawn in a viewport, i.e. on the map.
|-
| 0x10 || Signal is drawn in the signal GUI. The returned sprite set must still have 8 sprites, but OpenTTD will only use the 7th sprite, so all other sprites can be empty.
|-
| all other values || Reserved
|}
The other bytes of <code style:darkgreen>extra_callback_info1</code> are reserved, and must be masked.

===Example code===

A typical implementation for railtypes can look like:

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

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

NML:Objects

2012-06-25T10:26:44Z

FooBar: /* Object callbacks */ add example on how to return sound effect

{{NMLNavPropVarCB}}

==Object properties==

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

===Default object classes===

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

===List of object flags===

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

==Object variables==

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

Variables that require one or more parameters:

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

==Object callbacks==

{| class="t"
! callback
! return value
! comment
|-
| default
| Sprite layout
| Normal graphics for an object placed on the map
|-
| purchase*
| Sprite layout
| Graphics shown in the build menu
|-
| anim_next_frame
| Next animation frame or CB_RESULT_XXX
| Called for every animation frame, returns the next frame to display. Alternatively, return CB_RESULT_NEXT_FRAME or CB_RESULT_STOP_ANIMATION to show the next frame or stop animation, respectively. <code style="color:darkgreen">extra_callback_info1</code> contains random bits if the object flag OBJ_FLAG_RANDOM_ANIMATION is set. Returning a sound effect in the high byte will cause that sound effect to be played (e.g. <code>return (sound("mysound.wav") << 8) <nowiki>|</nowiki> CB_RESULT_NEXT_FRAME;</code>).
|-
| anim_control
| Next animation frame or CB_RESULT_XXX
|
Called whenever an object animation trigger happens. Return the animation frame to show, or CB_RESULT_XXX with XXX = [CB_RESULT_START_ANIMATION <nowiki>|</nowiki> STOP_ANIMATION <nowiki>|</nowiki> DO_NOTHING] to respectively start the animation in its current frame, stop the animation or do nothing. <code style="color:darkgreen">extra_callback_info1</code> contains random bits if the object flag OBJ_FLAG_RANDOM_ANIMATION is set. <code style="color:darkgreen">extra_callback_info2</code> contains the reason to trigger the animation, see the [[#Animation triggers| table]] below. Returning a sound effect in the high byte will cause that sound effect to be played.
|-
| anim_speed
| 0 .. 16
| Decide the time an animation frame should last. Return value is interpreted as (num_ticks = 2^anim_speed), which each tick lasting 30 ms. Avoid using this callback if possible, since it has to be called each tick for every animated tile. This can be used to create animation frames that last between 30 ms and 33 minutes.
|-
| colour
| colour2*16 + colour1
|
Called once, just after construction. Variable <code style="color:darkgreen">extra_callback_info1</code> contains the colour scheme of the constructing company in the same format as the return value, or random colours if not available (scenario editor). If OBJ_FLAG_2CC is not set, colour2 is zero. This callback can be used to alter the colour scheme of an object. Refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for possible colour values.
|-
| autoslope
| CB_RESULT[_NO]_AUTOSLOPE
| Return CB_RESULT_AUTOSLOPE to allow autoslope (altering the ground below a tile) or CB_RESULT_NO_AUTOSLOPE to disallow it.
|-
| tile_check*
|
Same as for the [[NML:Industries#Location check results|location_check]] industry callback
| Parameters: <code style="color:darkgreen">extra_callback_info1</code> contains the slope in bits 0..4 (see below), all other bits are reserved and should be and-masked out. <code style="color:darkgreen">extra_callback_info2</code> contains the location of the tile within the object as 16*y + x. If this callback is not implemented or fails, the default behaviour is to allow building the object if it can be placed on a flat surface. This means that steep slopes are not allowed and that the highest corner of each tile of a multi-tile object should have the same height. Additionally, all tiles must be flat if "build on slopes" is disabled.
|-
| additional_text*
| String
| Additional text to show in the purchase menu
|}

<nowiki>* These callbacks are called when the object is not yet built, so object- specific variables cannot be accessed. Trying to do so will result in undefined behaviour.</nowiki>

===Animation triggers===

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

Action0/Vehicles

2012-05-13T10:47:52Z

FooBar: /* Load amount */ explain 'unit of time'

<div style="float:right; padding-left:12px; background:none;">{{NFONavVehicles}}</div>

== Introduction ==
Action 0 properties common to all vehicle types:
The four vehicle types (trains, road vehicles, ships and planes) all have some common properties, which are described here.

== Properties ==

{| class="wikitable"
|-
!Number !![[GRFActionsDetailed|Size]]!!Version !!Description !!Available for articulated parts
|-
|00 ||W||{{ottdp|0.6|2.0}}||date of introduction||no
|-
| 02||B||{{ottdp|0.6|2.0}}||reliability decay speed||no
|-
| 03||B||{{ottdp|0.6|2.0}}||vehicle life in years||no
|-
| 04||B||{{ottdp|0.6|2.0}}||model life in years||no
|-
| 06||B||{{ottdp|0.6|2.0}}||climate availability||should be zero
|-
| 07||B||{{ottdp|0.6|2.0}} {{grfFrom|2}}||load amount||yes
|}

In TTDPatch properties 00 to 06 only apply to new games, or when using [[ttwiki:ResetVehicleData|Cht: ResetVehicles]].
In OpenTTD the same holds for 00, 02, 04 and 06 (i.e. not for 03) unless using [[ottdwiki:Console#Other_commands|resetengines]].

== Description ==

=== Date of introduction ===

The date is specified as number of days since 1920 where TTD counts 365,25 days in a year. It will have a random number from 0 to 511 days added to it at the start of every new game, or after using [[ttwiki:ResetVehicleData|Cht: ResetVehicles]] (TTDPatch) resp. [[ottdwiki:Console#Other_commands|resetengines]] (OpenTTD).

{{ottdp|<0.7|}} Note that TTD stops updating vehicle type data after the game ends in 2050, so all dates of introduction should be no later than in 2044, to ensure that all vehicle types can be introduced and reach their maximum reliability. This restriction does not apply to OpenTTD 0.7 and newer.

{{ottdp|<0.7| |ottdrev=before r16929}} If the property value is 729 (2D9h) or less, i.e. before 1922, the random number is not added and the vehicle is introduced at exactly the given date.

{{ottdp|0.7|no}} Since OpenTTD r16929 the start date is not randomised in the first two years after game-start (no matter whether before or after 1922).

The \w<date> escape sequence is especially useful here. See [[GRFActionsDetailed#Byte order|the discussion of escape sequences]] for further information.

=== Reliability decay speed ===

The reliability decay speed is set when a new vehicle is bought, and specifies how quickly the reliability decays after servicing.  The initial TTD default for all vehicles is 20.  If a vehicle goes without servicing for a long time, or if it gets very, very old, this number increases, meaning faster decay and more breakdowns.  Larger numbers mean faster decay, smaller number slower decay. If set to 0, reliability never decreases in normal operation.

=== Vehicle life ===

The number of years before a particular vehicle is considered too old and needs replacing,

=== Model life ===

The number of years that this model can be bought in the game (if PersistentEngines is off).  Usually this should be at least twice or three times as  long as the vehicle life.  When starting a new game, a random amount between 31 months and 17 years is added to this as well.

If the early retirement property (26/1B/16/16) is not set, the model life works like this:

{|
|-
!Phase !!Duration !!Reliability
|-
|1||7 to 38 months||increases from 48-73% to 75-100%
|-
|2||prop. 04 less 8 years||stays constant at peak, 75-100%
|-
|3||10 to 20.5 years||decreases from peak to 25-50%
|}

(the ranges in time and reliability are randomized at the start of each game)

At the end of phase 3, the model is retired and removed from the purchase list.  Note that when the model reliability starts dropping in phase 3, so does the reliability of every single vehicle of this make in the game.

Setting this property to 0xFF means the model will never expire.

If persistentengines is on, the model never gets to within two years of the end of phase 2, it is kept in phase 2 as long as at least one vehicle of this make is in the game.

If the early retirement property is set, the vehicle is retired this many years before the end of phase 2 (can be negative if desired), but not if persistentengines would keep the model alive.

{{ottdp|0.7|2.5|ottdrev=r14680|ttdprev=2.5 beta 7}} This property also works for wagons since TTDPatch 2.5 beta 7 resp. OpenTTD r14680.

=== Climate availability ===

This is a bit mask of the climates in which this model is available.  Simply add the values for the climates:

{|
|-
!Bit!!Value!!Climate
|-
|0||1||Temperate
|-
|1||2||Arctic
|-
|2||4||Tropical
|-
|3||8||Toyland
|}

For example, 1+2+4 = 07 would make a vehicle available in all climates except Toyland.

If you need a vehicle not to be available through the purchase menu, e.g. a locomotive tender being part of an articulated vehicle (locomotive and tender), you may use a value of zero for the bit mask.

{{ottdp|no|2.5}} Same procedure works for vehicles to be used exlusively by [[Callback:_AI_construction/purchase_selection |TTDPatch's AI]], but not by a human player.

=== Load amount ===
This is the amount of cargo transferred per unit of time if using gradualloading.  The default is 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.

{{ottdp|<0.7||ottdrev=before r14672}} For aircraft carrying both passengers and mail this property is broken (wrt. mail) in TTDPatch and OpenTTD before r14672. All aircraft effectively use the load amount of the train engine with ID 00.

{{ottdp|0.7|no|ottdrev=r14672}} Since OpenTTD r14672 this property is used for passengers, while mail uses 1/4 (rounded up). You can use [[Callbacks#Load amount (12)|callback 12]] to control load amounts for passengers and mail independently.

NML:Vehicles

2012-05-13T10:47:11Z

FooBar: explain loading_speed

{{NMLNavPropVarCB}}

==Properties common to all vehicle types==

{| class="t"
! property
! value range
! available for<br />articulated<br />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>
| XXX = [TEMPERATE <nowiki>|</nowiki> ARCTIC <nowiki>|</nowiki> TROPICAL <nowiki>|</nowiki> TOYLAND], alternatively <code style="color:green">NO_CLIMATE</code> or <code style="color:green">ALL_CLIMATES</code>. 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
| =0
| multiplier to the base purchase cost
|-
| <code style="color:green">running_cost_factor</code>
| 0 ... 255
| =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.
|}

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

{| 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
| stays constant at peak, 75-100%
|-
| 3
| 10 to 20.5 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.

==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 <code style="color:darkgreen">sort(FEAT_TRAINS, [D, B, A]);</code> the final sorting will be this: C D B A E

==Train properties==

{| class="t"
! property
! value range
! available for<br />articulated<br />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 the same value
| XXX=[TILT <nowiki>|</nowiki> 2CC <nowiki>|</nowiki> MU <nowiki>|</nowiki> FLIP <nowiki>|</nowiki> 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
|-
| <code style="color:green">refit_cost</code>
| 0 ... 255
| yes
| in 50% units of the purchase price cost base
|-
| <code style="color:green">callback_flags</code>
| bitmask(VEH_CBF_XXX, ...)
| yes
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| <code style="color:green">track_type</code>
| item from railtypetable
| must be the same as front
| Default railtype table: RAIL, MONO, MGLV. If you install a railtypetable yourself you'll always get the railtype you specified. If you want a vehicle to run on electric rail and you don't have a railtypetable, set <code style="color:green">track_type</code> to RAIL and make sure that you set <code style="color:green">engine_class</code> to <code style="color:green">ENGINE_CLASS_ELECTRIC</code>.
|-
| <code style="color:green">ai_special_flag</code>
| [<code style="color:green">AI_FLAG_PASSENGER</code> <nowiki>|</nowiki> <code style="color:green">AI_FLAG_CARGO</code>]
| no
| Set to <code style="color:green">AI_FLAG_PASSENGER</code> to 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)
| =0
|
|-
| <code style="color:green">running_cost_base</code>
| RUNNING_COST_XXX
| =0
| XXX = [STEAM <nowiki>|</nowiki> DIESEL <nowiki>|</nowiki> ELECTRIC <nowiki>|</nowiki> ROADVEH <nowiki>|</nowiki> NONE]
|-
| <code style="color:green">dual_headed</code>
| [0 <nowiki>|</nowiki> 1]
| =0 for both parts
| 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)
| =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
| XXX=[STEAM <nowiki>|</nowiki> DIESEL <nowiki>|</nowiki> ELECTRIC <nowiki>|</nowiki> MONORAIL <nowiki>|</nowiki> MAGLEV]
|-
| <code style="color:green">extra_power_per_wagon</code>
| 0 ... 65000 hp (float, power units)
| =0
| Only wagons with a livery override for this engine will add power
|-
| <code style="color:green">tractive_effort_coefficient</code>
| 0 ... 1 (float)
| =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.
|-
| <code style="color:green">air_drag_coefficient</code>
| 0 ... 1 (float)
| =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
| 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 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.
|-
| <code style="color:green">extra_weight_per_wagon</code>
| 0 ... 255 ton (float, mass units)
| =0
| Adds extra weight for powered wagons, see <code style="color:green">extra_power_per_wagon</code>
|-
| <span #id="bitmask_vehicle_info"></span><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>]]
|}

==Road vehicle properties==

{| class="t"
! property
! value range
! available for<br />articulated<br />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 [[NML:Old style callbacks|old-style callbacks]].
|-
| running_cost_base
| RUNNING_COST_XXX
| set to RUNNING_COST_NONE
| XXX = [STEAM <nowiki>|</nowiki> DIESEL <nowiki>|</nowiki> ELECTRIC <nowiki>|</nowiki> ROADVEH <nowiki>|</nowiki> NONE]
|-
| power
| 0 ... 2550hp (float, power units)
| =0
|
|-
| weight
| 0 ... 63.75ton (float, mass units)
| =0
|
|-
| tractive_effort_coefficient
| 0 ... 1 (float)
| =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)
| =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]].
|-
| visual_effect
| visual_effect(VISUAL_EFFECT_XXX, offset)
| yes
| 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 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==

{| class="t"
! 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 [[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
| 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
| 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]].
|-
| 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)
| 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.
|}

==Aircraft properties==

{| class="t"
! 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 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 [[NML:Old style callbacks|old-style callbacks]].
|-
| is_helicopter
| AIRCRAFT_TYPE_XXX
| XXX=[NORMAL <nowiki>|</nowiki> HELICOPTER]
|-
| is_large
| AIRCRAFT_SIZE_XXX
| XXX=[SMALL <nowiki>|</nowiki> 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 <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]].
|}

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

{| class="t"
! name
! value range
! available in<br />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
|
[[NML:Cargos#Cargo classes|cargo classes]]
|-
| most_common_refit
|
[[NML:Cargos#Cargo properties|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|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 [[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 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 <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 ... 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 [[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_reversed
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle has reversed an odd number of times
|-
| built_during_preview
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle was built during the exclusive preview stage
|-
| current_railtype
| 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 [[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
| 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
|-
| vehicle_is_in_depot
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle is inside a depot
|}

===Variables that require an argument===

{| class="t"
! name
! Argument
! value range
! available in<br />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 [[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="t"
! 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.
|-
| 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. )
|-
| 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
| 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 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 <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">extra_callback_info1</code> contains 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">extra_callback_info1</code> contains 1 during the first call, 2 during the second, etc. Note that callback may be called from the purchase list, using vehicle variables is not possible. Or CB_RESULT_REVERSED_VEHICLE to the returned vehicle ID to display the vehicle backwards.

For NML 0.2 and lower the vehicle ID of the articulated part must be in the range 0 .. 127.
|-
| can_attach_wagon
| Trains
| No
| String or CB_RESULT_ATTACH_XXX
| Called when a wagon is being attached, to allow or disallow attaching. This callback has to be defined at the engine. However, variables in the <code style="color:darkgreen">SELF</code> scope refer to the wagon being attached, the <code style="color:darkgreen">PARENT</code> 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.

{| class="t"
! 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
|
|-
| refit_cost
| {{ottdp|1.2|no|ottdrev=r23089}} All
| Yes
| 0 .. 16377 as refit cost. Add <code style="color:darkgreen">CB_RESULT_AUTOREFIT</code> if you want to allow autorefit.
|-
| 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
|
|-
| 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
|
|}

===Sound events===

{| class="t"
! 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
|}

Standardized Railtype Scheme

2012-05-06T17:12:23Z

FooBar: /* Axle load class [**X*] */ there are only five default classes

This railtype label scheme aims to bring order to the uncontrolled growth of railtype labels. It groups the rail types into what matters from a technical perspective. The scheme provides a standardized way of defining railtype labels, based on track gauge and type, speed class, allowable axle weight and electrification type.

It is the explicit intent of this scheme to decouple track sets from vehicle sets to facilitate easy mixing. This way the player can select a track set of choice to go with a train set of choice. It allows the player to play with or without axle load classes, or with or without speed limit classes, simply by loading a track set that does or does not provide these features. In some cases it will also be possible to combine niche track sets, for instance a standard gauge track set with a narrow gauge and a metro track set.

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

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

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

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

=== Speed limit class [*X**] ===
The second position in the railtype label defines the speed limit class. These classes do not map to a fixed numeric value, but are used to define an internal speed limit order for the track set. This means that if your track set has two different speed limits for track types that are otherwise identical, you'll use letters A and B here. In case of three different speed limits, use A, B and C. In case your track set does not employ speed limits, always use A. Train sets do not care about the speed limit, and will always set the lowest speed class, i.e. A.

This gives for instance the following options:

<div style="float:left;">
<div style="float:left;">
{|
! !!Speed limit class
|-
|A ||no speed limits
|}
</div>
<div style="float:left;">
 OR 
</div>
</div>
<div style="float:left;">
<div style="float:left;">
{|
! !!Speed limit class
|-
|A ||low speed
|-
|B ||high speed
|}
</div>
<div style="float:left;">
 OR 
</div>
</div>
<div style="float:left;">
<div style="float:left;">
{|
! !!Speed limit class
|-
|A ||low speed
|-
|B ||medium speed
|-
|C ||high speed
|}
</div>
<div style="float:left;">
 etc. 
</div>
</div>
<div style="clear:left;"></div>

The speed limit class may also be used for some advanced features of the label scheme, like specialized track types and eyecandy purposes. Be careful not to break the compatibility with other sets when using the speed limit class for these purposes.

An example of a special use is rack rail. In the French set it is used to give rack rail engines a higher speed and TE than normal rail engines when used on rack rail. When defining trains with a special speed limit class, always allow a fallback to speed limit class A via the railtype table.

An example of eyecandy use are urban tracks. These are a variation of regular tracks, but with concrete ground tiles to better match the urban environment. Train sets must not define vehicles for eyecandy classes.

The following special and eyecandy classes have been defined so far:

{|
! !!Description !!Type
|-
|A-H ||speed limits ||reserved
|-
|R ||rack rail ||special
|-
|U ||urban ||eyecandy
|}

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

A train set should set the appropriate axle weight for each train via the railtype label, as to make the set work with track sets that do provide tracks with different weight limits, even if you don't care about it for your trainset. Split all vehicles of a certain track gauge/type into five groups of similar axle weight. The group with the lowest axle weights will get class '''A''', the second lowest class '''B''', etc. up to the group with the highest axle weights which will get class '''E'''. Do the same for the other track gauge/types if your train set has those.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== Summary for track sets ==
This section summarizes the above for track sets.

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

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

== Summary for train sets ==
This section summarizes the above for train sets.

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

Be as specific as you want when selecting the railtype, it is the job of the track set to select a playable, reduced subset out of all possible type combinations.

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

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

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

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

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

Standardized Railtype Scheme

2012-04-21T15:33:39Z

FooBar: add link to forum topic

This railtype label scheme aims to bring order to the uncontrolled growth of railtype labels. It groups the rail types into what matters from a technical perspective. The scheme provides a standardized way of defining railtype labels, based on track gauge and type, speed class, allowable axle weight and electrification type.

It is the explicit intent of this scheme to decouple track sets from vehicle sets to facilitate easy mixing. This way the player can select a track set of choice to go with a train set of choice. It allows the player to play with or without axle load classes, or with or without speed limit classes, simply by loading a track set that does or does not provide these features. In some cases it will also be possible to combine niche track sets, for instance a standard gauge track set with a narrow gauge and a metro track set.

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

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

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

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

=== Speed limit class [*X**] ===
The second position in the railtype label defines the speed limit class. These classes do not map to a fixed numeric value, but are used to define an internal speed limit order for the track set. This means that if your track set has two different speed limits for track types that are otherwise identical, you'll use letters A and B here. In case of three different speed limits, use A, B and C. In case your track set does not employ speed limits, always use A. Train sets do not care about the speed limit, and will always set the lowest speed class, i.e. A.

This gives for instance the following options:

<div style="float:left;">
<div style="float:left;">
{|
! !!Speed limit class
|-
|A ||no speed limits
|}
</div>
<div style="float:left;">
 OR 
</div>
</div>
<div style="float:left;">
<div style="float:left;">
{|
! !!Speed limit class
|-
|A ||low speed
|-
|B ||high speed
|}
</div>
<div style="float:left;">
 OR 
</div>
</div>
<div style="float:left;">
<div style="float:left;">
{|
! !!Speed limit class
|-
|A ||low speed
|-
|B ||medium speed
|-
|C ||high speed
|}
</div>
<div style="float:left;">
 etc. 
</div>
</div>
<div style="clear:left;"></div>

The speed limit class may also be used for some advanced features of the label scheme, like specialized track types and eyecandy purposes. Be careful not to break the compatibility with other sets when using the speed limit class for these purposes.

An example of a special use is rack rail. In the French set it is used to give rack rail engines a higher speed and TE than normal rail engines when used on rack rail. When defining trains with a special speed limit class, always allow a fallback to speed limit class A via the railtype table.

An example of eyecandy use are urban tracks. These are a variation of regular tracks, but with concrete ground tiles to better match the urban environment. Train sets must not define vehicles for eyecandy classes.

The following special and eyecandy classes have been defined so far:

{|
! !!Description !!Type
|-
|A-H ||speed limits ||reserved
|-
|R ||rack rail ||special
|-
|U ||urban ||eyecandy
|}

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

A train set should set the appropriate axle weight for each train via the railtype label, as to make the set work with track sets that do provide tracks with different weight limits, even if you don't care about it for your trainset. Split all vehicles of a certain track gauge/type into five groups of similar axle weight. The group with the lowest axle weights will get class '''A''', the second lowest class '''B''', etc. up to the group with the highest axle weights which will get class '''E'''. Do the same for the other track gauge/types if your train set has those.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== Summary for track sets ==
This section summarizes the above for track sets.

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

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

== Summary for train sets ==
This section summarizes the above for train sets.

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

Be as specific as you want when selecting the railtype, it is the job of the track set to select a playable, reduced subset out of all possible type combinations.

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

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

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

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

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

TracktypeLabels

2012-04-21T15:32:12Z

FooBar: Add link to standardized scheme

This page lists existing railtype labels.

== Standardized railtype scheme ==
Several members of the TT-Forums came up with a railtype label scheme that allows for compatibility between train and track sets by different authors. At the same time it allows fancy stuff like axle weight limits, speed limits, different track and electrification types, etc. It is not mandatory to follow this scheme.

See [[Standardized Railtype Scheme]].

== Railtype labels defined outside the standardized scheme ==

The following railtype labels have been defined so far:

{| class="wikitable"
|-
!'''Label'''
!'''Rail Type'''
!'''Notes'''
|-
| align="center" colspan="3" | OpenTTD Default Railtypes
|-
|RAIL
|Normal rail
|
|-
|ELRL
|electrified rail
|
|-
|MONO
|Monorail tracks
|
|-
|MGLV
|Maglev tracks
|
|-
| align="center" colspan="3" | New Railtypes
|-
|_040
|speed limit 40 km/h
|Slowrails, SwedishRails
|-
|_080
|speed limit 80 km/h
|Slowrails, SwedishRails
|-
|E040
|speed limit 40 km/h, with catenary
|Slowrails, SwedishRails
|-
|E080
|speed limit 80 km/h, with catenary
|Slowrails, SwedishRails
|-
|3RDR
|Tracks with third rail
|MetroTracks, NuTracks, UK Railway Set tracks, Japanese Track Set
|-
|3RDC
|Tracks with third rail and catenary
|MetroTracks, NuTracks, UK Railway Set tracks, Japanese Track Set
|-
|RLOW
|Low speed tracks
|NuTracks, SwedishRails, Japanese Track Set
|-
|ELOW
|Low speed tracks with catenary
|NuTracks, SwedishRails, Japanese Track Set
|-
|3LOW
|Low speed tracks with 3rd rail
|NuTracks,
|-
|CLOW
|Low speed tracks, 3rd rail and catenary
|NuTracks
|-
|RMED
|Medium speed tracks
|NuTracks, SwedishRails
|-
|EMED
|Medium speed tracks with catenary
|NuTracks, SwedishRails
|-
|3MED
|Medium speed tracks with 3rd rail
|NuTracks
|-
|CMED
|Medium speed tracks, 3rd rail and catenary
|NuTracks
|-
|RHIG
|High speed tracks
|NuTracks, SwedishRails, Japanese Track Set
|-
|EHIG
|High speed tracks with catenary
|NuTracks, SwedishRails, Japanese Track Set
|-
|HSTR
|Very high speed tracks with catenary
|NuTracks, SwedishRails, Japanese Track Set
|-
|NGRL
|Narrow gauge tracks
|Narrow Gauge Track Types, Japanese Track Set
|-
|ELNG
|Narrow gauge tracks with catenary
|Narrow Gauge Track Types, Japanese Track Set
|-
|PLAN
|Planning tracks (blue dotted lines)
|NuTracks
|-
|MTRO
|Metro tracks
|NuTracks
|-
|MTRC
|Metro tracks with concrete edges
|NuTracks
|-
|MTRS
|Metro tracks with suburban buildings on top
|NuTracks
|-
|MTRU
|Metro tracks with 'downtown' buildings on top
|NuTracks
|-
|MTRT
|Metro tracks with plain landscape on top
|NuTracks
|-
|DBNN
|branch line
|DBRails
|-
|DBNE
|branch line, electrified
|DBRails
|-
|DBHN
|main line
|DBRails
|-
|DBHE
|main line, electrified
|DBRails
|-
|DBHS
|high speed line electrified (NBS)
|DBRails
|-
|TRPD
|transrapid track
|Transrapid track type
|-
|NAAN
|Narrow gauge, unelectrified
|French Set Rails
|-
|NAAE
|Narrow gauge, catenary powered
|French Set Rails
|-
|NAA3
|Narrow gauge, third-rail powered
|French Set Rails
|-
|NRAN
|Narrow gauge, unelectrified, rack rail
|French Set Rails
|-
|NRAE
|Narrow gauge, catenary powered, rack rail
|French Set Rails
|-
|NBAN
|Narrow gauge, unelectrified, high speed
|French Set Rails
|-
|NLOW
|Low speed narrow gauge tracks
|Japanese Track Set
|-
|ENLW
|Low speed narrow gauge tracks with catenary
|Japanese Track Set
|-
|ENHI
|Modern narrow gauge tracks with catenary
|Japanese Track Set
|}

User:FooBar/Railtypelabels

2012-04-21T15:25:12Z

FooBar: moved User:FooBar/Railtypelabels to Standardized Railtype Scheme: no comments were recieved in the last week, time to make this definitive.

#REDIRECT [[Standardized Railtype Scheme]]

Standardized Railtype Scheme

2012-04-21T15:25:12Z

FooBar: moved User:FooBar/Railtypelabels to Standardized Railtype Scheme: no comments were recieved in the last week, time to make this definitive.

This railtype label scheme aims to bring order to the uncontrolled growth of railtype labels. It groups the rail types into what matters from a technical perspective. The scheme provides a standardized way of defining railtype labels, based on track gauge and type, speed class, allowable axle weight and electrification type.

It is the explicit intent of this scheme to decouple track sets from vehicle sets to facilitate easy mixing. This way the player can select a track set of choice to go with a train set of choice. It allows the player to play with or without axle load classes, or with or without speed limit classes, simply by loading a track set that does or does not provide these features. In some cases it will also be possible to combine niche track sets, for instance a standard gauge track set with a narrow gauge and a metro track set.

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

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

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

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

=== Speed limit class [*X**] ===
The second position in the railtype label defines the speed limit class. These classes do not map to a fixed numeric value, but are used to define an internal speed limit order for the track set. This means that if your track set has two different speed limits for track types that are otherwise identical, you'll use letters A and B here. In case of three different speed limits, use A, B and C. In case your track set does not employ speed limits, always use A. Train sets do not care about the speed limit, and will always set the lowest speed class, i.e. A.

This gives for instance the following options:

<div style="float:left;">
<div style="float:left;">
{|
! !!Speed limit class
|-
|A ||no speed limits
|}
</div>
<div style="float:left;">
 OR 
</div>
</div>
<div style="float:left;">
<div style="float:left;">
{|
! !!Speed limit class
|-
|A ||low speed
|-
|B ||high speed
|}
</div>
<div style="float:left;">
 OR 
</div>
</div>
<div style="float:left;">
<div style="float:left;">
{|
! !!Speed limit class
|-
|A ||low speed
|-
|B ||medium speed
|-
|C ||high speed
|}
</div>
<div style="float:left;">
 etc. 
</div>
</div>
<div style="clear:left;"></div>

The speed limit class may also be used for some advanced features of the label scheme, like specialized track types and eyecandy purposes. Be careful not to break the compatibility with other sets when using the speed limit class for these purposes.

An example of a special use is rack rail. In the French set it is used to give rack rail engines a higher speed and TE than normal rail engines when used on rack rail. When defining trains with a special speed limit class, always allow a fallback to speed limit class A via the railtype table.

An example of eyecandy use are urban tracks. These are a variation of regular tracks, but with concrete ground tiles to better match the urban environment. Train sets must not define vehicles for eyecandy classes.

The following special and eyecandy classes have been defined so far:

{|
! !!Description !!Type
|-
|A-H ||speed limits ||reserved
|-
|R ||rack rail ||special
|-
|U ||urban ||eyecandy
|}

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

A train set should set the appropriate axle weight for each train via the railtype label, as to make the set work with track sets that do provide tracks with different weight limits, even if you don't care about it for your trainset. Split all vehicles of a certain track gauge/type into five groups of similar axle weight. The group with the lowest axle weights will get class '''A''', the second lowest class '''B''', etc. up to the group with the highest axle weights which will get class '''E'''. Do the same for the other track gauge/types if your train set has those.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== Summary for track sets ==
This section summarizes the above for track sets.

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

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

== Summary for train sets ==
This section summarizes the above for train sets.

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

Be as specific as you want when selecting the railtype, it is the job of the track set to select a playable, reduced subset out of all possible type combinations.

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

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

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

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

Standardized Railtype Scheme

2012-04-07T17:48:46Z

FooBar: update axle load classes

This railtype label scheme aims to bring order to the uncontrolled growth of railtype labels. It groups the rail types into what matters from a technical perspective. The scheme provides a standardized way of defining railtype labels, based on track gauge and type, speed class, allowable axle weight and electrification type.

It is the explicit intent of this scheme to decouple track sets from vehicle sets to facilitate easy mixing. This way the player can select a track set of choice to go with a train set of choice. It allows the player to play with or without axle load classes, or with or without speed limit classes, simply by loading a track set that does or does not provide these features. In some cases it will also be possible to combine niche track sets, for instance a standard gauge track set with a narrow gauge and a metro track set.

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

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

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

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

=== Speed limit class [*X**] ===
The second position in the railtype label defines the speed limit class. These classes do not map to a fixed numeric value, but are used to define an internal speed limit order for the track set. This means that if your track set has two different speed limits for track types that are otherwise identical, you'll use letters A and B here. In case of three different speed limits, use A, B and C. In case your track set does not employ speed limits, always use A. Train sets do not care about the speed limit, and will always set the lowest speed class, i.e. A.

This gives for instance the following options:

<div style="float:left;">
<div style="float:left;">
{|
! !!Speed limit class
|-
|A ||no speed limits
|}
</div>
<div style="float:left;">
 OR 
</div>
</div>
<div style="float:left;">
<div style="float:left;">
{|
! !!Speed limit class
|-
|A ||low speed
|-
|B ||high speed
|}
</div>
<div style="float:left;">
 OR 
</div>
</div>
<div style="float:left;">
<div style="float:left;">
{|
! !!Speed limit class
|-
|A ||low speed
|-
|B ||medium speed
|-
|C ||high speed
|}
</div>
<div style="float:left;">
 etc. 
</div>
</div>
<div style="clear:left;"></div>

The speed limit class may also be used for some advanced features of the label scheme, like specialized track types and eyecandy purposes. Be careful not to break the compatibility with other sets when using the speed limit class for these purposes.

An example of a special use is rack rail. In the French set it is used to give rack rail engines a higher speed and TE than normal rail engines when used on rack rail. When defining trains with a special speed limit class, always allow a fallback to speed limit class A via the railtype table.

An example of eyecandy use are urban tracks. These are a variation of regular tracks, but with concrete ground tiles to better match the urban environment. Train sets must not define vehicles for eyecandy classes.

The following special and eyecandy classes have been defined so far:

{|
! !!Description !!Type
|-
|A-H ||speed limits ||reserved
|-
|R ||rack rail ||special
|-
|U ||urban ||eyecandy
|}

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

A train set should set the appropriate axle weight for each train via the railtype label, as to make the set work with track sets that do provide tracks with different weight limits, even if you don't care about it for your trainset. Split all vehicles of a certain track gauge/type into five groups of similar axle weight. The group with the lowest axle weights will get class '''A''', the second lowest class '''B''', etc. up to the group with the highest axle weights which will get class '''E'''. Do the same for the other track gauge/types if your train set has those.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

== Summary for track sets ==
This section summarizes the above for track sets.

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

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

== Summary for train sets ==
This section summarizes the above for train sets.

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

Be as specific as you want when selecting the railtype, it is the job of the track set to select a playable, reduced subset out of all possible type combinations.

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

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

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

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

Standardized Railtype Scheme

2012-04-07T11:56:20Z

FooBar: Reduced axle load classes to 5 and dropped the reference to numeric axle weights: all classes are relative

This railtype label scheme aims to bring order to the uncontrolled growth of railtype labels. It groups the rail types into what matters from a technical perspective. The scheme provides a standardized way of defining railtype labels, based on track gauge and type, speed class, allowable axle weight and electrification type.

It is the explicit intent of this scheme to decouple track sets from vehicle sets to facilitate easy mixing. This way the player can select a track set of choice to go with a train set of choice. It allows the player to play with or without axle load classes, or with or without speed limit classes, simply by loading a track set that does or does not provide these features. In some cases it will also be possible to combine niche track sets, for instance a standard gauge track set with a narrow gauge and a metro track set.

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

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

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

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

=== Speed limit class [*X**] ===
The second position in the railtype label defines the speed limit class. These classes do not map to a fixed numeric value, but are used to define an internal speed limit order for the track set. This means that if your track set has two different speed limits for track types that are otherwise identical, you'll use letters A and B here. In case of three different speed limits, use A, B and C. In case your track set does not employ speed limits, always use A. Train sets do not care about the speed limit, and will always set the lowest speed class, i.e. A.

This gives for instance the following options:

<div style="float:left;">
<div style="float:left;">
{|
! !!Speed limit class
|-
|A ||no speed limits
|}
</div>
<div style="float:left;">
 OR 
</div>
</div>
<div style="float:left;">
<div style="float:left;">
{|
! !!Speed limit class
|-
|A ||low speed
|-
|B ||high speed
|}
</div>
<div style="float:left;">
 OR 
</div>
</div>
<div style="float:left;">
<div style="float:left;">
{|
! !!Speed limit class
|-
|A ||low speed
|-
|B ||medium speed
|-
|C ||high speed
|}
</div>
<div style="float:left;">
 etc. 
</div>
</div>
<div style="clear:left;"></div>

The speed limit class may also be used for some advanced features of the label scheme, like specialized track types and eyecandy purposes. Be careful not to break the compatibility with other sets when using the speed limit class for these purposes.

An example of a special use is rack rail. In the French set it is used to give rack rail engines a higher speed and TE than normal rail engines when used on rack rail. When defining trains with a special speed limit class, always allow a fallback to speed limit class A via the railtype table.

An example of eyecandy use are urban tracks. These are a variation of regular tracks, but with concrete ground tiles to better match the urban environment. Train sets must not define vehicles for eyecandy classes.

The following special and eyecandy classes have been defined so far:

{|
! !!Description !!Type
|-
|A-H ||speed limits ||reserved
|-
|R ||rack rail ||special
|-
|U ||urban ||eyecandy
|}

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

A train set should set the appropriate axle weight for each train via the railtype label, as to make the set work with track sets that do provide tracks with different weight limits, even if you don't care about it for your trainset. Split all vehicles of a certain track gauge/type into five groups of similar axle weight. The group with the lowest axle weights will get class '''A''', the second lowest class '''B''', etc. up to the group with the highest axle weights which will get class '''E'''. Do the same for the other track gauge/types if your train set has those.

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

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

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

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

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

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

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

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

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

{|
! !!Specialized energy type classes !!Vehicle set fallback
|-
|4 ||4th rail electrification || 3
|-
|Z ||3rd rail and catenary electrification || 3 or E
|-
|D ||DC catenary electrification || E
|-
|d ||low voltage DC catenary electrification (only when D also used in set) || E
|-
|A ||AC catenary electrification || E
|-
|a ||low voltage AC catenary electrification (only when A also used in set) || E
|-
|C ||two phase catenary electrification || E
|-
|T ||three phase catenary electrification || E
|}

Some specialized energy type classes (like '''C''', '''T''' and '''Z''') are meant for multi-current or multi-system vehicles. These are only necessary if you set has more than one type of multi-current/system. If your set only has one type of multi-current/system, the generic E class can be used for that. Note that if you want more than one type of multi-current/system, you'll quickly get a combinatory explosion of railtype labels, so plan carefully or do not attempt it. For every different multi-current/system type a dedicated railtype is needed (even though you may not want them in your track set).

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

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

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

== Summary for track sets ==
This section summarizes the above for track sets.

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

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

== Summary for train sets ==
This section summarizes the above for train sets.

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

Be as specific as you want when selecting the railtype, it is the job of the track set to select a playable, reduced subset out of all possible type combinations.

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

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

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

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

Standardized Railtype Scheme

2012-04-07T11:28:29Z

FooBar: multi-system sets

This railtype label scheme aims to bring order to the uncontrolled growth of railtype labels. It groups the rail types into what matters from a technical perspective. The scheme provides a standardized way of defining railtype labels, based on track gauge and type, speed class, allowable axle weight and electrification type.

It is the explicit intent of this scheme to decouple track sets from vehicle sets to facilitate easy mixing. This way the player can select a track set of choice to go with a train set of choice. It allows the player to play with or without axle load classes, or with or without speed limit classes, simply by loading a track set that does or does not provide these features. In some cases it will also be possible to combine niche track sets, for instance a standard gauge track set with a narrow gauge and a metro track set.

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

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

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

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

=== Speed limit class [*X**] ===
The second position in the railtype label defines the speed limit class. These classes do not map to a fixed numeric value, but are used to define an internal speed limit order for the track set. This means that if your track set has two different speed limits for track types that are otherwise identical, you'll use letters A and B here. In case of three different speed limits, use A, B and C. In case your track set does not employ speed limits, always use A. Train sets do not care about the speed limit, and will always set the lowest speed class, i.e. A.

This gives for instance the following options:

<div style="float:left;">
<div style="float:left;">
{|
! !!Speed limit class
|-
|A ||no speed limits
|}
</div>
<div style="float:left;">
 OR 
</div>
</div>
<div style="float:left;">
<div style="float:left;">
{|
! !!Speed limit class
|-
|A ||low speed
|-
|B ||high speed
|}
</div>
<div style="float:left;">
 OR 
</div>
</div>
<div style="float:left;">
<div style="float:left;">
{|
! !!Speed limit class
|-
|A ||low speed
|-
|B ||medium speed
|-
|C ||high speed
|}
</div>
<div style="float:left;">
 etc. 
</div>
</div>
<div style="clear:left;"></div>

The speed limit class may also be used for some advanced features of the label scheme, like specialized track types and eyecandy purposes. Be careful not to break the compatibility with other sets when using the speed limit class for these purposes.

An example of a special use is rack rail. In the French set it is used to give rack rail engines a higher speed and TE than normal rail engines when used on rack rail. When defining trains with a special speed limit class, always allow a fallback to speed limit class A via the railtype table.

An example of eyecandy use are urban tracks. These are a variation of regular tracks, but with concrete ground tiles to better match the urban environment. Train sets must not define vehicles for eyecandy classes.

The following special and eyecandy classes have been defined so far:

{|
! !!Description !!Type
|-
|A-H ||speed limits ||reserved
|-
|R ||rack rail ||special
|-
|U ||urban ||eyecandy
|}

=== Axle load class [**X*] ===
The third position defines the axle weight limit. Heavy trains cannot run on tracks with a low axle weight limit; these trains need more expensive tracks with a heigher weight limit. A track set does not have to provide a dedicated track type for each axle weight limit. A train set should set the appropriate axle weight for each train via the railtype label, as to make the set work with track sets that do provide tracks with different weight limits.

The naming scheme followed here is derived from the European Standard [http://de.wikipedia.org/wiki/Streckenklasse EN 15528]. Note that the limits in the table below are not set in stone. If for your train set it makes more sense to deviate slightly from it, then you may do so. Example: you have engines with axle loads 15 t, 17 t, 18 t and 21 t. According to EN 15528 you would get classes A, B and D, but for gameplay reasons it may be more interesting to put the 18 t engines in class C.

{|
! !!Axle load limit
|-
|A ||16 t
|-
|B ||18 t
|-
|C ||20 t
|-
|D ||22.5 t
|-
|E ||25 t
|-
|F ||27.5 t
|-
|G ||30 t
|}

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

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

If you want a axle load class lower than 16 t, you may use lowercase letter a for that, or a and b if you want to split it even further (b is a lower limit than a, so for increasing axle load limits: b < a < A < B < C etc.). Be advised that your train set may not assume the existance of any other class than listed above, so when using lowercase class letters make sure to program your railtype table such that trains with such a class will fall back to class A if the lowercase class is not defined. If you make a track set with very low axle load limits, be aware that not all train sets will define trains for these tracks. In general: only do this in case of a train set with a matching track set.

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

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

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

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

{|
! !!Specialized energy type classes !!Vehicle set fallback
|-
|4 ||4th rail electrification || 3
|-
|Z ||3rd rail and catenary electrification || 3 or E
|-
|D ||DC catenary electrification || E
|-
|d ||low voltage DC catenary electrification (only when D also used in set) || E
|-
|A ||AC catenary electrification || E
|-
|a ||low voltage AC catenary electrification (only when A also used in set) || E
|-
|C ||two phase catenary electrification || E
|-
|T ||three phase catenary electrification || E
|}

Some specialized energy type classes (like '''C''', '''T''' and '''Z''') are meant for multi-current or multi-system vehicles. These are only necessary if you set has more than one type of multi-current/system. If your set only has one type of multi-current/system, the generic E class can be used for that. Note that if you want more than one type of multi-current/system, you'll quickly get a combinatory explosion of railtype labels, so plan carefully or do not attempt it. For every different multi-current/system type a dedicated railtype is needed (even though you may not want them in your track set).

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

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

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

== Summary for track sets ==
This section summarizes the above for track sets.

; [X***] Track gauge and type class
* Define at least one track type for every track gauge/type class you want in your set.
* If you only provide tracks for one gauge/type, consider leaving some free railtypes so a player can load an additional set for some other type.
; [*X**] Speed limit class
* Make sure class A is always available, either directly or via an alternate label.
* Use only class A if you don't want speed limits;
* With speed limits, A is the lowest speed limit. Continue with B, C, etc. for increasing speed limits;
* The speed class can also be used to implement additional eye-candy track types, use letters higher in the alphabet for this.
; [**X*] Axle load class
* Always define all classes A through G for every track type class / electrification combination, either:
** Directly via a real railtype definition;
** Indirectly via the alternate rail type label list, property [[Action0/Railtypes#Alternate_rail_type_labels_.281D.29|1D (NFO)]] or [[NML:Railtypes#Railtype_properties|alternative_railtype_list (NML)]].
* Extend the predefined classes only if you also provide a train set that makes use of these.
; [***X] Energy source type class
* If your set only uses specialized classes, always map the generic classes to the closest matching specialized type via property 1D.
; Standard labels [RAIL, ELRL, MONO, MGLV]
* Always define the standard labels when possible, instead of what would be the equivalent of the standard label in this scheme.
* Map the equivalent labels from this scheme to the standard labels using property [[Action0/Railtypes#Alternate_rail_type_labels_.281D.29|1D (NFO)]] or [[NML:Railtypes#Railtype_properties|alternative_railtype_list (NML)]].

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

== Summary for train sets ==
This section summarizes the above for train sets.

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

Be as specific as you want when selecting the railtype, it is the job of the track set to select a playable, reduced subset out of all possible type combinations.

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

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

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

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

Standardized Railtype Scheme

2012-04-07T11:09:10Z

FooBar: fallback via railtype table

This railtype label scheme aims to bring order to the uncontrolled growth of railtype labels. It groups the rail types into what matters from a technical perspective. The scheme provides a standardized way of defining railtype labels, based on track gauge and type, speed class, allowable axle weight and electrification type.

It is the explicit intent of this scheme to decouple track sets from vehicle sets to facilitate easy mixing. This way the player can select a track set of choice to go with a train set of choice. It allows the player to play with or without axle load classes, or with or without speed limit classes, simply by loading a track set that does or does not provide these features. In some cases it will also be possible to combine niche track sets, for instance a standard gauge track set with a narrow gauge and a metro track set.

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

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

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

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

=== Speed limit class [*X**] ===
The second position in the railtype label defines the speed limit class. These classes do not map to a fixed numeric value, but are used to define an internal speed limit order for the track set. This means that if your track set has two different speed limits for track types that are otherwise identical, you'll use letters A and B here. In case of three different speed limits, use A, B and C. In case your track set does not employ speed limits, always use A. Train sets do not care about the speed limit, and will always set the lowest speed class, i.e. A.

This gives for instance the following options:

<div style="float:left;">
<div style="float:left;">
{|
! !!Speed limit class
|-
|A ||no speed limits
|}
</div>
<div style="float:left;">
 OR 
</div>
</div>
<div style="float:left;">
<div style="float:left;">
{|
! !!Speed limit class
|-
|A ||low speed
|-
|B ||high speed
|}
</div>
<div style="float:left;">
 OR 
</div>
</div>
<div style="float:left;">
<div style="float:left;">
{|
! !!Speed limit class
|-
|A ||low speed
|-
|B ||medium speed
|-
|C ||high speed
|}
</div>
<div style="float:left;">
 etc. 
</div>
</div>
<div style="clear:left;"></div>

The speed limit class may also be used for some advanced features of the label scheme, like specialized track types and eyecandy purposes. Be careful not to break the compatibility with other sets when using the speed limit class for these purposes.

An example of a special use is rack rail. In the French set it is used to give rack rail engines a higher speed and TE than normal rail engines when used on rack rail. When defining trains with a special speed limit class, always allow a fallback to speed limit class A via the railtype table.

An example of eyecandy use are urban tracks. These are a variation of regular tracks, but with concrete ground tiles to better match the urban environment. Train sets must not define vehicles for eyecandy classes.

The following special and eyecandy classes have been defined so far:

{|
! !!Description !!Type
|-
|A-H ||speed limits ||reserved
|-
|R ||rack rail ||special
|-
|U ||urban ||eyecandy
|}

=== Axle load class [**X*] ===
The third position defines the axle weight limit. Heavy trains cannot run on tracks with a low axle weight limit; these trains need more expensive tracks with a heigher weight limit. A track set does not have to provide a dedicated track type for each axle weight limit. A train set should set the appropriate axle weight for each train via the railtype label, as to make the set work with track sets that do provide tracks with different weight limits.

The naming scheme followed here is derived from the European Standard [http://de.wikipedia.org/wiki/Streckenklasse EN 15528]. Note that the limits in the table below are not set in stone. If for your train set it makes more sense to deviate slightly from it, then you may do so. Example: you have engines with axle loads 15 t, 17 t, 18 t and 21 t. According to EN 15528 you would get classes A, B and D, but for gameplay reasons it may be more interesting to put the 18 t engines in class C.

{|
! !!Axle load limit
|-
|A ||16 t
|-
|B ||18 t
|-
|C ||20 t
|-
|D ||22.5 t
|-
|E ||25 t
|-
|F ||27.5 t
|-
|G ||30 t
|}

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

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

If you want a axle load class lower than 16 t, you may use lowercase letter a for that, or a and b if you want to split it even further (b is a lower limit than a, so for increasing axle load limits: b < a < A < B < C etc.). Be advised that your train set may not assume the existance of any other class than listed above, so when using lowercase class letters make sure to program your railtype table such that trains with such a class will fall back to class A if the lowercase class is not defined. If you make a track set with very low axle load limits, be aware that not all train sets will define trains for these tracks. In general: only do this in case of a train set with a matching track set.

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

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

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

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

{|
! !!Specialized energy type classes !!Vehicle set fallback
|-
|4 ||4th rail electrification || 3
|-
|Z ||3rd rail and catenary electrification || 3 or E
|-
|D ||DC catenary electrification || E
|-
|d ||low voltage DC catenary electrification (only when D also used in set) || E
|-
|A ||AC catenary electrification || E
|-
|a ||low voltage AC catenary electrification (only when A also used in set) || E
|-
|C ||two phase catenary electrification || E
|-
|T ||three phase catenary electrification || E
|}

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

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

== Summary for track sets ==
This section summarizes the above for track sets.

; [X***] Track gauge and type class
* Define at least one track type for every track gauge/type class you want in your set.
* If you only provide tracks for one gauge/type, consider leaving some free railtypes so a player can load an additional set for some other type.
; [*X**] Speed limit class
* Make sure class A is always available, either directly or via an alternate label.
* Use only class A if you don't want speed limits;
* With speed limits, A is the lowest speed limit. Continue with B, C, etc. for increasing speed limits;
* The speed class can also be used to implement additional eye-candy track types, use letters higher in the alphabet for this.
; [**X*] Axle load class
* Always define all classes A through G for every track type class / electrification combination, either:
** Directly via a real railtype definition;
** Indirectly via the alternate rail type label list, property [[Action0/Railtypes#Alternate_rail_type_labels_.281D.29|1D (NFO)]] or [[NML:Railtypes#Railtype_properties|alternative_railtype_list (NML)]].
* Extend the predefined classes only if you also provide a train set that makes use of these.
; [***X] Energy source type class
* If your set only uses specialized classes, always map the generic classes to the closest matching specialized type via property 1D.
; Standard labels [RAIL, ELRL, MONO, MGLV]
* Always define the standard labels when possible, instead of what would be the equivalent of the standard label in this scheme.
* Map the equivalent labels from this scheme to the standard labels using property [[Action0/Railtypes#Alternate_rail_type_labels_.281D.29|1D (NFO)]] or [[NML:Railtypes#Railtype_properties|alternative_railtype_list (NML)]].

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

== Summary for train sets ==
This section summarizes the above for train sets.

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

Be as specific as you want when selecting the railtype, it is the job of the track set to select a playable, reduced subset out of all possible type combinations.

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

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

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

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

Standardized Railtype Scheme

2012-04-07T11:07:42Z

FooBar: /* Speed limit class [*X**] */ special speed limit classes: the case of rack rail

This railtype label scheme aims to bring order to the uncontrolled growth of railtype labels. It groups the rail types into what matters from a technical perspective. The scheme provides a standardized way of defining railtype labels, based on track gauge and type, speed class, allowable axle weight and electrification type.

It is the explicit intent of this scheme to decouple track sets from vehicle sets to facilitate easy mixing. This way the player can select a track set of choice to go with a train set of choice. It allows the player to play with or without axle load classes, or with or without speed limit classes, simply by loading a track set that does or does not provide these features. In some cases it will also be possible to combine niche track sets, for instance a standard gauge track set with a narrow gauge and a metro track set.

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

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

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

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

=== Speed limit class [*X**] ===
The second position in the railtype label defines the speed limit class. These classes do not map to a fixed numeric value, but are used to define an internal speed limit order for the track set. This means that if your track set has two different speed limits for track types that are otherwise identical, you'll use letters A and B here. In case of three different speed limits, use A, B and C. In case your track set does not employ speed limits, always use A. Train sets do not care about the speed limit, and will always set the lowest speed class, i.e. A.

This gives for instance the following options:

<div style="float:left;">
<div style="float:left;">
{|
! !!Speed limit class
|-
|A ||no speed limits
|}
</div>
<div style="float:left;">
 OR 
</div>
</div>
<div style="float:left;">
<div style="float:left;">
{|
! !!Speed limit class
|-
|A ||low speed
|-
|B ||high speed
|}
</div>
<div style="float:left;">
 OR 
</div>
</div>
<div style="float:left;">
<div style="float:left;">
{|
! !!Speed limit class
|-
|A ||low speed
|-
|B ||medium speed
|-
|C ||high speed
|}
</div>
<div style="float:left;">
 etc. 
</div>
</div>
<div style="clear:left;"></div>

The speed limit class may also be used for some advanced features of the label scheme, like specialized track types and eyecandy purposes. Be careful not to break the compatibility with other sets when using the speed limit class for these purposes.

An example of a special use is rack rail. In the French set it is used to give rack rail engines a higher speed and TE than normal rail engines when used on rack rail. When defining trains with a special speed limit class, always allow a fallback to speed limit class A.

An example of eyecandy use are urban tracks. These are a variation of regular tracks, but with concrete ground tiles to better match the urban environment. Train sets must not define vehicles for eyecandy classes.

The following special and eyecandy classes have been defined so far:

{|
! !!Description !!Type
|-
|A-H ||speed limits ||reserved
|-
|R ||rack rail ||special
|-
|U ||urban ||eyecandy
|}

=== Axle load class [**X*] ===
The third position defines the axle weight limit. Heavy trains cannot run on tracks with a low axle weight limit; these trains need more expensive tracks with a heigher weight limit. A track set does not have to provide a dedicated track type for each axle weight limit. A train set should set the appropriate axle weight for each train via the railtype label, as to make the set work with track sets that do provide tracks with different weight limits.

The naming scheme followed here is derived from the European Standard [http://de.wikipedia.org/wiki/Streckenklasse EN 15528]. Note that the limits in the table below are not set in stone. If for your train set it makes more sense to deviate slightly from it, then you may do so. Example: you have engines with axle loads 15 t, 17 t, 18 t and 21 t. According to EN 15528 you would get classes A, B and D, but for gameplay reasons it may be more interesting to put the 18 t engines in class C.

{|
! !!Axle load limit
|-
|A ||16 t
|-
|B ||18 t
|-
|C ||20 t
|-
|D ||22.5 t
|-
|E ||25 t
|-
|F ||27.5 t
|-
|G ||30 t
|}

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

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

If you want a axle load class lower than 16 t, you may use lowercase letter a for that, or a and b if you want to split it even further (b is a lower limit than a, so for increasing axle load limits: b < a < A < B < C etc.). Be advised that your train set may not assume the existance of any other class than listed above, so when using lowercase class letters make sure to program your railtype table such that trains with such a class will fall back to class A if the lowercase class is not defined. If you make a track set with very low axle load limits, be aware that not all train sets will define trains for these tracks. In general: only do this in case of a train set with a matching track set.

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

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

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

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

{|
! !!Specialized energy type classes !!Vehicle set fallback
|-
|4 ||4th rail electrification || 3
|-
|Z ||3rd rail and catenary electrification || 3 or E
|-
|D ||DC catenary electrification || E
|-
|d ||low voltage DC catenary electrification (only when D also used in set) || E
|-
|A ||AC catenary electrification || E
|-
|a ||low voltage AC catenary electrification (only when A also used in set) || E
|-
|C ||two phase catenary electrification || E
|-
|T ||three phase catenary electrification || E
|}

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

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

== Summary for track sets ==
This section summarizes the above for track sets.

; [X***] Track gauge and type class
* Define at least one track type for every track gauge/type class you want in your set.
* If you only provide tracks for one gauge/type, consider leaving some free railtypes so a player can load an additional set for some other type.
; [*X**] Speed limit class
* Make sure class A is always available, either directly or via an alternate label.
* Use only class A if you don't want speed limits;
* With speed limits, A is the lowest speed limit. Continue with B, C, etc. for increasing speed limits;
* The speed class can also be used to implement additional eye-candy track types, use letters higher in the alphabet for this.
; [**X*] Axle load class
* Always define all classes A through G for every track type class / electrification combination, either:
** Directly via a real railtype definition;
** Indirectly via the alternate rail type label list, property [[Action0/Railtypes#Alternate_rail_type_labels_.281D.29|1D (NFO)]] or [[NML:Railtypes#Railtype_properties|alternative_railtype_list (NML)]].
* Extend the predefined classes only if you also provide a train set that makes use of these.
; [***X] Energy source type class
* If your set only uses specialized classes, always map the generic classes to the closest matching specialized type via property 1D.
; Standard labels [RAIL, ELRL, MONO, MGLV]
* Always define the standard labels when possible, instead of what would be the equivalent of the standard label in this scheme.
* Map the equivalent labels from this scheme to the standard labels using property [[Action0/Railtypes#Alternate_rail_type_labels_.281D.29|1D (NFO)]] or [[NML:Railtypes#Railtype_properties|alternative_railtype_list (NML)]].

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

== Summary for train sets ==
This section summarizes the above for train sets.

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

Be as specific as you want when selecting the railtype, it is the job of the track set to select a playable, reduced subset out of all possible type combinations.

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

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

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

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

Standardized Railtype Scheme

2012-04-03T16:18:37Z

FooBar: save (final for now)

This railtype label scheme aims to bring order to the uncontrollable growth of railtype labels. It groups the rail types into what matters from a technical perspective. The scheme provides a standardized way of defining railtype labels, based on track gauge and type, speed class, allowable axle weight and electrification type. Train sets that follow the scheme will be compatible with a large selection of track sets that also follow the scheme. That way the player can select a track set of choice to go with a train set of choice. It allows the player to play with or without axle load classes, or with or without speed limit classes, simply by loading a track set that does or does not provide these features. In some cases it will also be possible to combine niche track sets, for instance a standard gauge track set with a narrow gauge and a metro track set.

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

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

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

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

=== Speed limit class [*X**] ===
The second position in the railtype label defines the speed limit class. These classes do not map to a fixed numeric value, but are used to define an internal speed limit order for the track set. This means that if your track set has two different speed limits for track types that are otherwise identical, you'll use letters A and B here. In case of three different speed limits, use A, B and C. In case your track set does not employ speed limits, always use A. Train sets do not care about the speed limit, and will always set the lowest speed class, i.e. A.

This gives for instance the following options:

<div style="float:left;">
<div style="float:left;">
{|
! !!Speed limit class
|-
|A ||no speed limits
|}
</div>
<div style="float:left;">
 OR 
</div>
</div>
<div style="float:left;">
<div style="float:left;">
{|
! !!Speed limit class
|-
|A ||low speed
|-
|B ||high speed
|}
</div>
<div style="float:left;">
 OR 
</div>
</div>
<div style="float:left;">
<div style="float:left;">
{|
! !!Speed limit class
|-
|A ||low speed
|-
|B ||medium speed
|-
|C ||high speed
|}
</div>
<div style="float:left;">
 etc. 
</div>
</div>
<div style="clear:left;"></div>

A track set may also use the speed limit class for eyecandy purposes, for instance when providing an urban track type with concrete gound tiles. The following eyecandy classes have been defined so far:

{|
! !!Eyecandy class
|-
|A-H ||reserved for speed limits
|-
|U ||urban
|-
|R ||rack rail
|}

=== Axle load class [**X*] ===
The third position defines the axle weight limit. Heavy trains cannot run on tracks with a low axle weight limit; these trains need more expensive tracks with a heigher weight limit. A track set does not have to provide a dedicated track type for each axle weight limit. A train set should set the appropriate axle weight for each train via the railtype label, as to make the set work with track sets that do provide tracks with different weight limits.

The naming scheme followed here is derived from the European Standard [http://de.wikipedia.org/wiki/Streckenklasse EN 15528]. Note that the limits in the table below are not set in stone. If for your train set it makes more sense to deviate slightly from it, then you may do so. Example: you have engines with axle loads 15 t, 17 t, 18 t and 21 t. According to EN 15528 you would get classes A, B and D, but for gameplay reasons it may be more interesting to put the 18 t engines in class C.

{|
! !!Axle load limit
|-
|A ||16 t
|-
|B ||18 t
|-
|C ||20 t
|-
|D ||22.5 t
|-
|E ||25 t
|-
|F ||27.5 t
|-
|G ||30 t
|}

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

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

If you want a axle load class lower than 16 t, you may use lowercase letter a for that, or a and b if you want to split it even further (b is a lower limit than a, so for increasing axle load limits: b < a < A < B < C etc.). Be advised that your train set may not assume the existance of any other class than listed above, so when using lowercase class letters make sure to program your railtype table such that trains with such a class will fall back to class A if the lowercase class is not defined. If you make a track set with very low axle load limits, be aware that not all train sets will define trains for these tracks. In general: only do this in case of a train set with a matching track set.

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

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

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

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

{|
! !!Specialized energy type classes !!Vehicle set fallback
|-
|4 ||4th rail electrification || 3
|-
|Z ||3rd rail and catenary electrification || 3 or E
|-
|D ||DC catenary electrification || E
|-
|d ||low voltage DC catenary electrification (only when D also used in set) || E
|-
|A ||AC catenary electrification || E
|-
|a ||low voltage AC catenary electrification (only when A also used in set) || E
|-
|C ||two phase catenary electrification || E
|-
|T ||three phase catenary electrification || E
|}

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

So in practice this means that you should RAIL instead of SAAN and ELRL instead of SAAE.

== Summary for track sets ==
This section summarizes the above for track sets.

; [X***] Track gauge and type class
* Define at least one track type for every track gauge/type class you want in your set.
; [*X**] Speed limit class
* Always define at least class A for every track type class / electrification combination;
* Only use class A if you don't want speed limits;
* With speed limits, A is the lowest speed limit. Continue with B, C, etc. for increasing speed limits;
* Use a letter high in the alphabet for additional eye-candy track types for this type class / electrification combination.
; [**X*] Axle load class
* Always define all classes A through G for every track type class / electrification combination, either:
** Directly via a real railtype definition;
** Indirectly via the alternate rail type label list, property [[Action0/Railtypes#Alternate_rail_type_labels_.281D.29|1D (NFO)]] or [[NML:Railtypes#Railtype_properties|alternative_railtype_list (NML)]].
* Extend the predefined classes only if you also provide a train set that makes use of these.
; [***X] Energy source type class
* If your set only uses specialized classes, always map the generic classes to the closest matching specialized type via property 1D.
; Standard labels [RAIL, ELRL, MONO, MGLV]
* Always define the standard labels when possible, instead of what would be the equivalent of the standard label in this scheme.
* Map the equivalent labels from this scheme to the standard labels using property [[Action0/Railtypes#Alternate_rail_type_labels_.281D.29|1D (NFO)]] or [[NML:Railtypes#Railtype_properties|alternative_railtype_list (NML)]].

== Summary for train sets ==
This section summarizes the above for train sets.

; [X***] Track gauge and type class
* Use the track type class that matches the vehicle;
* Define a fallback type via the railtype table in case you want the vehicle to be available on a different track if no matching track set is loaded.
; [*X**] Speed limit class
* Always use class A for every vehicle.
; [**X*] Axle load class
* Use all classes A through G according to the maximum axle weight of the vehicle.
* Extend the predefined classes only if you also provide a track set that makes use of these;
** When extending the predefined classes A through G, define a fallback type via the railtype table in case you want the vehicle to be available if no matching track set is loaded.
; [***X] Energy source type class
* Use the energy source type class that matches the vehicle;
* When using specialized classes, define a fallback type via the railtype table in case you want the vehicle to be available if no matching track set is loaded.
; Standard labels [RAIL, ELRL, MONO, MGLV]
* Define a fallback type to the standard labels via the railtype table in case you want the vehicle to be available on the standard tracks if no matching track set is loaded.

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

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

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

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

Standardized Railtype Scheme

2012-04-02T20:24:45Z

FooBar: save

Standardized Railtype Scheme

2012-04-02T20:22:15Z

FooBar: save

Standardized Railtype Scheme

2012-04-02T18:09:01Z

FooBar: save

Standardized Railtype Scheme

2012-04-02T17:32:11Z

FooBar: save

User:FooBar

2012-04-02T17:03:02Z

FooBar: Created page with "User:FooBar/Railtypelabels"

[[User:FooBar/Railtypelabels]]

NML:Vehicles

2012-03-25T12:28:16Z

FooBar: /* Vehicle callbacks */ details on purchase menu sprite for dual-headed trains

{{NMLNavPropVarCB}}

==Properties common to all vehicle types==

{| class="t"
! property
! value range
! available for<br />articulated<br />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>
| XXX = [TEMPERATE <nowiki>|</nowiki> ARCTIC <nowiki>|</nowiki> TROPICAL <nowiki>|</nowiki> TOYLAND], alternatively <code style="color:green">NO_CLIMATE</code> or <code style="color:green">ALL_CLIMATES</code>. 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 tick. Default vehicles use 5 for trains and road vehicles, 10 for ships and 20 for aircraft
|-
| <code style="color:green">cost_factor</code>
| 0 ... 255
| =0
| multiplier to the base purchase cost
|-
| <code style="color:green">running_cost_factor</code>
| 0 ... 255
| =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.
|}

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

{| 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
| stays constant at peak, 75-100%
|-
| 3
| 10 to 20.5 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.

==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 <code style="color:darkgreen">sort(FEAT_TRAINS, [D, B, A]);</code> the final sorting will be this: C D B A E

==Train properties==

{| class="t"
! property
! value range
! available for<br />articulated<br />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 the same value
| XXX=[TILT <nowiki>|</nowiki> 2CC <nowiki>|</nowiki> MU <nowiki>|</nowiki> FLIP <nowiki>|</nowiki> 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
|-
| <code style="color:green">refit_cost</code>
| 0 ... 255
| yes
| in 50% units of the purchase price cost base
|-
| <code style="color:green">callback_flags</code>
| bitmask(VEH_CBF_XXX, ...)
| yes
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| <code style="color:green">track_type</code>
| item from railtypetable
| must be the same as front
| Default railtype table: RAIL, MONO, MGLV. If you install a railtypetable yourself you'll always get the railtype you specified. If you want a vehicle to run on electric rail and you don't have a railtypetable, set <code style="color:green">track_type</code> to RAIL and make sure that you set <code style="color:green">engine_class</code> to <code style="color:green">ENGINE_CLASS_ELECTRIC</code>.
|-
| <code style="color:green">ai_special_flag</code>
| [<code style="color:green">AI_FLAG_PASSENGER</code> <nowiki>|</nowiki> <code style="color:green">AI_FLAG_CARGO</code>]
| no
| Set to <code style="color:green">AI_FLAG_PASSENGER</code> to 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)
| =0
|
|-
| <code style="color:green">running_cost_base</code>
| RUNNING_COST_XXX
| =0
| XXX = [STEAM <nowiki>|</nowiki> DIESEL <nowiki>|</nowiki> ELECTRIC <nowiki>|</nowiki> ROADVEH <nowiki>|</nowiki> NONE]
|-
| <code style="color:green">dual_headed</code>
| [0 <nowiki>|</nowiki> 1]
| =0 for both parts
| 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)
| =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
| XXX=[STEAM <nowiki>|</nowiki> DIESEL <nowiki>|</nowiki> ELECTRIC <nowiki>|</nowiki> MONORAIL <nowiki>|</nowiki> MAGLEV]
|-
| <code style="color:green">extra_power_per_wagon</code>
| 0 ... 65000 hp (float, power units)
| =0
| Only wagons with a livery override for this engine will add power
|-
| <code style="color:green">tractive_effort_coefficient</code>
| 0 ... 1 (float)
| =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.
|-
| <code style="color:green">air_drag_coefficient</code>
| 0 ... 1 (float)
| =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
| 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 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.
|-
| <code style="color:green">extra_weight_per_wagon</code>
| 0 ... 255 ton (float, mass units)
| =0
| Adds extra weight for powered wagons, see <code style="color:green">extra_power_per_wagon</code>
|-
| <span #id="bitmask_vehicle_info"></span><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>]]
|}

==Road vehicle properties==

{| class="t"
! property
! value range
! available for<br />articulated<br />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 [[NML:Old style callbacks|old-style callbacks]].
|-
| running_cost_base
| RUNNING_COST_XXX
| set to RUNNING_COST_NONE
| XXX = [STEAM <nowiki>|</nowiki> DIESEL <nowiki>|</nowiki> ELECTRIC <nowiki>|</nowiki> ROADVEH <nowiki>|</nowiki> NONE]
|-
| power
| 0 ... 2550hp (float, power units)
| =0
|
|-
| weight
| 0 ... 63.75ton (float, mass units)
| =0
|
|-
| tractive_effort_coefficient
| 0 ... 1 (float)
| =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)
| =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]].
|-
| visual_effect
| visual_effect(VISUAL_EFFECT_XXX, offset)
| yes
| 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 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==

{| class="t"
! 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 [[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
| 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
| 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]].
|-
| 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)
| 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.
|}

==Aircraft properties==

{| class="t"
! 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 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 [[NML:Old style callbacks|old-style callbacks]].
|-
| is_helicopter
| AIRCRAFT_TYPE_XXX
| XXX=[NORMAL <nowiki>|</nowiki> HELICOPTER]
|-
| is_large
| AIRCRAFT_SIZE_XXX
| XXX=[SMALL <nowiki>|</nowiki> 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 <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]].
|}

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

{| class="t"
! name
! value range
! available in<br />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
|
[[NML:Cargos#Cargo classes|cargo classes]]
|-
| most_common_refit
|
[[NML:Cargos#Cargo properties|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|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 [[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 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 <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 ... 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 [[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_reversed
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle has reversed an odd number of times
|-
| built_during_preview
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle was built during the exclusive preview stage
|-
| current_railtype
| 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 [[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
| 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
|-
| vehicle_is_in_depot
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle is inside a depot
|}

===Variables that require an argument===

{| class="t"
! name
! Argument
! value range
! available in<br />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 [[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="t"
! 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.
|-
| 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. )
|-
| 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
| 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 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 <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">extra_callback_info1</code> contains 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">extra_callback_info1</code> contains 1 during the first call, 2 during the second, etc. Note that callback may be called from the purchase list, using vehicle variables is not possible. Or CB_RESULT_REVERSED_VEHICLE to the returned vehicle ID to display the vehicle backwards.

For NML 0.2 and lower the vehicle ID of the articulated part must be in the range 0 .. 127.
|-
| can_attach_wagon
| Trains
| No
| String or CB_RESULT_ATTACH_XXX
| Called when a wagon is being attached, to allow or disallow attaching. This callback has to be defined at the engine. However, variables in the <code style="color:darkgreen">SELF</code> scope refer to the wagon being attached, the <code style="color:darkgreen">PARENT</code> 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.

{| class="t"
! 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
|
|-
| refit_cost
| {{ottdp|1.2|no|ottdrev=r23089}} All
| Yes
| 0 .. 16377 as refit cost. Add <code style="color:darkgreen">CB_RESULT_AUTOREFIT</code> if you want to allow autorefit.
|-
| 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
|
|-
| 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
|
|}

===Sound events===

{| class="t"
! 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
|}

Action3

2012-03-25T12:22:23Z

FooBar: /* cargo-type */ clarification on purchase menu sprite for dual-headed trains, thanks to Pikka (http://www.tt-forums.net/viewtopic.php?p=1003439#p1003439)

== Introduction ==

Action 3 assigns graphics sets (referenced to by (chains of) [[Action2|action 2(s]]) to feature IDs (vehicles, stations, houses, industries, ...).

== Format ==

The format of the data is feature-dependent.

The data is:

<pre> <Sprite-number> * <Length> 03 <feature> <n-id> <ids...> <num-cid> (<cargo-type> <set-ID>)... <default set-ID></pre>

{| class="wikitable"
|-
!'''Element'''
![[GRFActionsDetailed|'''Size''']]
!'''Description'''
|-
|<Sprite-number>
|dec
|A sequential sprite number
|-
|<length>
|dec
|The total number of bytes used in this action
|-
|03
|B
|Defines action 03
|-
|<feature>
|B
|What type of feature the IDs refer to
|-
|<n-id>
|B
|Number of IDs this action 3 associates graphics with
|-
|<ids...>
|B/B*
|IDs of the current feature this action 3 associates graphics with. There must be as many IDs as <n-id> specifies
|-
|<num-cid>
|B
|Number of different cargo types to support
|-
|<cargo-type>
|B
|Cargo type for which to use the following set-ID
|-
|<set-ID>
|W
|Set-ID (from action 2 or from a varaction2 chain) to use for this cargo type
|-
|<default set-ID>
|W
|Default set-ID to use if none of the above matches
|}

== Description ==

=== Sprite-number ===

This is just the number you are at.

=== Length ===

Count the number of bytes in this action.

=== Feature ===

This sets the type of [[Features|feature]] that you wish to change. Set it to:

{|- |
!Value!![[Features|Feature]]
|-
|00||Trains
|-
|01||Road Vehicles
|-
|02||Ships
|-
|03||Aircraft
|-
|04||Stations
|-
|05||[[Action3/Canals|Canals/Rivers]]
|-
|07||Houses
|-
|09||Industry Tiles
|-
|0A||Industries
|-
|0B||Cargos
|-
|0C||Sound Effects (generic callback only)
|-
|0D||Airports
|-
|0E||Signals (generic callback only)
|-
|0F||Objects
|-
|10||[[Action3/Railtypes|Railtypes]]
|-
|11||Airport Tiles
|}

=== n-id ===

How many items of the current feature this action 3 defines new graphics for. If this is more than one, all items listed will get the same graphics. If this value has bit 7 set (i.e. 80 added), it is a wagon override. See [[Action3LiveryOverride|Action 3 - Livery Override]] for more info on this feature.

You can make a definition with n-id equal to zero (and thus no ids that follow).  This creates a generic feature-specific definition not associated with any particular item.  At the moment, this is used for generic callbacks, but might be extended to other functions eventually.

=== ids ===

Feature IDs to use this action 3 for. All IDs are counted from the first of their class, i.e. the first road vehicle has 00, as does the first plane, the first ship, and the first train vehicle.

In OpenTTD since r13482, each ID is an extended byte for vehicles, otherwise the ID is a regular byte.

For canals and rivers the id has a special meaning, see its [[Action3/Canals|own Action 3 page]]

For town buildings, the IDs are the house IDs, and specifying a house ID that haven't been defined before (by setting its property 08) doesn't do anything, but doesn't cause an error, either. Note that you don't necessarily have to assign a set-ID to a house ID, the old TTD sprite of the substitute type will be used if you don't do so.  Industry tile IDs work in the same manner.

=== num-cid ===

Number of cargo type definitions that follow. Can be zero if only the default follows.

For features 05 (canals/rivers), 07 (houses), 09 (industry tiles), 0A (industries), and 0B (cargoes) this must always be zero.

=== cargo-type ===

<u>For vehicles (features 00 .. 03) and stations (feature 04)</u>

The cargo-type for which the set-ID applies.  If the item is built to use this type of cargo, or if it is refitted for it, the given set-ID is used as its graphics.  See column "type A" in the table at [[CargoTypes]] for a list of cargo-type values.

If the grf file has installed a [[Action0/Global Settings#Cargo translation table 09|cargo translation table]], the cargo type here refers to the cargo with the label in the given slot of the translation table, e.g. if you use cargo-type=08, it refers to the cargo that has the label in the ninth slot (numbered 08) in the translation table.

If defined, cargo-type FF is used for graphics shown in the purchase or construction window.
: Note that for dual-headed trains (prop 13) 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.

For stations, you can additionally define a special cargo-type of FE which prevents the default from being used (which would show the sum of all cargo).  Instead, the given set-ID is displayed with no cargo at all.

<u>Railtypes are available only in OpenTTD > r19056 and its action 3 re-uses the 'cargo'-type definition.</u>

For details see its [[Action3/Railtypes|own Action 3 page]]

<u>For canals/rivers, houses, industry tiles, industries and cargoes (features 05, 07, 09, 0A and 0B)</u>

As <num-cid> is zero for features 05 (canals/rivers), 07 (houses), 09 (industry tiles), 0A (industries), and 0B (cargoes), <cargo-type> and <set-ID> need to be skipped and you only have to set <default set-ID>.

<u>For objects (feature 0F)</u>

Objects support a buy menu sprite similar to vehicles (cargo-type FF).

=== default set-ID ===

Default set-ID if no entry from the cargo-type list above matches, or if there are no special cargo-types listed at all.

== Example ==

Below is an example of what a real action 3 pseudo-sprite could look like for a train engine.

<pre> 13 * 7   03 00 01 02 00 00 00</pre>

{| class="wikitable"
|-
!'''Byte'''
!'''Meaning'''
|-
|13
|<sprite-number>
|-
|7
|<length> of the action in bytes; start counting at 03 (<action>)
|-
|03
|<action>: sets this pseudo-sprite to function as action 3
|-
|00
|<feature>: 00 for trains
|-
|01
|<n-id>: One ID to change in this case
|-
|02
|<ids...>: vehicle ID (02 - Ploddyphut Choo-Choo)
|-
|00
|<num-cid>: this engine doesn't have cargo-specific graphics
|-
|00 00
|<default set-ID>: Use action 2 ID 00, because it is a word value you add 00
|}

CargoTypes

2012-03-18T13:20:53Z

FooBar: /* Cargo Labels */ Update FIRS definitions to r2712

'''Cargo labels in OpenTTD'''

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

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

== Cargo Labels ==

The following cargo labels have been defined so far:

{| class="wikitable
|-
! Label
! Cargo Description
! [[Action0Cargos#Cargo classes 16|Cargo classes]]
! colspan="3" | Notes
|-
| align="center" colspan="2" | '''TTD Default Cargos'''
| align="center" colspan="4" | These cargos are present when no NewGRF is used
|-
| PASS
| Passengers
| 0001 Passengers
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|-
| COAL
| Coal
| 0010 Bulk
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|-
| MAIL
| Mail
| 0002 Mail
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|-
|OIL_
| Oil
| 0040 Liquid
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|-
| LVST
| Livestock
| 0020 Piece goods
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|-
| GOOD
| Goods
| 0004 Express
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|-
| GRAI
| Grain
| 0010 Bulk
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
| Temperate; see also WHEA, MAIZ, CERE
|-
| WOOD
| Wood
| 0020 Piece goods
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|-
| IORE
| Iron Ore
| 0010 Bulk
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|-
| STEL
| Steel
| 0020 Piece goods
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
| Renamed "Metal" in FIRS.
|-
| VALU
| Valuables
| 0008 Armoured
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
| Temperate; see also GOLD, DIAM
|-
| PAPR
| Paper
| 0020 Piece goods
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|-
| WHEA
| Wheat
| 0010 Bulk
|
|
| Arctic; see also GRAI, MAIZ, CERE
|-
| FOOD
| Food
| 0084 Express, refrigerated
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|-
| GOLD
| Gold
| 0008 Armoured
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
| Arctic; see also VALU, DIAM
|-
| RUBR
|Rubber
|0040 Liquid
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|-
| FRUT
| Fruit
| 0090 Bulk, refrigerated
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|-
| MAIZ
| Maize
| 0010 Bulk
|
|
| Tropic; see also GRAI, WHEA, CERE
|-
| CORE
| Copper Ore
| 0010 Bulk
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|-
| WATR
| Water
| 0040 Liquid
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|-
| DIAM
| Diamonds
| 0008 Armoured
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
| Tropic; see also VALU, GOLD
|-
| SUGR
| Sugar
| 0010 Bulk
|
|
| Toyland
|-
| TOYS
| Toys
| 0020 Piece goods
|
|
| Toyland
|-
| BATT
| Batteries
| 0020 Piece goods
|
|
| Toyland
|-
| SWET
|Sweets (Candy)
|0004 Express
|
|
| Toyland
|-
| TOFF
|Toffee
|0010 Bulk
|
|
| Toyland
|-
| COLA
|Cola
|0040 Liquid
|
|
| Toyland
|-
| CTCD
|Cotton Candy (Candyfloss)
|0010 Bulk
|
|
| Toyland
|-
| BUBL
|Bubbles
|0020 Piece goods
|
|
| Toyland
|-
| PLST
|Plastic
|0040 Liquid
|
|
| Toyland; see also PLAS
|-
| FZDR
|Fizzy Drinks
|0020 Piece goods
|
|
| Toyland
|-
| align="center" colspan="2" | '''New Cargos'''
| align="center" colspan="4" | these cargos are only present when NewGRF industry sets are used
|-
| AORE
|Bauxite (Aluminium ore)
|0010 Bulk
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|-
| BEER
|Alcohol
|0064 Express, piece goods, liquids
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|-
| BDMT
|Building Materials
|0220 Piece goods, covered/sheltered
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
| In FIRS: 0030 Bulk, piece goods
|-
| BRCK
|Bricks
| 0020 Piece goods
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|-
| CERA
|Ceramics
| 0020 Piece goods
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|-
| CERE
|Cereals
| 0210 Bulk, covered/sheltered
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|<ref name="ecs_cargo_change" />
|-
| CLAY
|Clay
|0210 Bulk covered/sheltered
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
| In FIRS: 0010 Bulk
|-
| CMNT
|Cement
| 0210 Bulk covered/sheltered
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|-
| COPR
|Copper
|0020 Piece goods
|
|
|
|-
| DYES
|Dyes
| 0060 Piece goods, liquids
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|-
| ENSP
|Engineering Supplies
|0024 Express, piece goods
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|-
| FERT
|Fertiliser
| 0030 Bulk, piece goods
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|<ref name="ecs_cargo_change" />
|-
| FICR
|Fibre crops
| 0030 Bulk, piece goods
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|-
| FISH
|Fish
| 0084 Express, refrigerated
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|-
| FMSP
|Farm Supplies
|0024 Express, piece goods
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|-
| FRVG
|Fruit (and optionally Vegetables)
|00A4 Express, piece goods, refrigerated
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|-
| GLAS
|Glass
| 0420 Piece goods, oversized
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|-
| GRVL
|Gravel / Ballast
|0010 Bulk
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|-
| LIME
|Lime stone
| 0010 Bulk
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|-
| MILK
|Milk
|00C4 Express, liquid, refrigerated
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|-
| MNSP
|Manufacturing Supplies
|0024 Piece Goods, express
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|-
| OLSD
|Oil seed
| 0210 Bulk, covered/sheltered
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|<ref name="ecs_cargo_change" />
|-
| PETR
|Petrol / Fuel Oil
| 0040 Liquid
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|-
| PLAS
|Plastic
| 0060 Piece goods, liquid
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|-
| POTA
|Potash
| 0210 Bulk, covered/sheltered
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|<ref name="ecs_cargo_change" />
|-
| RCYC
|Recyclables
|0220 Piece Goods, covered
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|-
| RFPR
|Refined products
| 0040 Liquid
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|-
| SAND
|Sand
| 0010 Bulk
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|-
| SCMT
|Scrap Metal
|1010 Bulk, non-pourable
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|-
| SGBT
|Sugar beet
|0010 Bulk
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
| not in tropical
|-
| SGCN
|Sugarcane
|1010 Bulk, non-pourable
|
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
| only tropical
|-
| SULP
|Sulphur
| 0210 Bulk, covered/sheltered
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|<ref name="ecs_cargo_change">ECS cargo classes changed as of Dec 31, 2010</ref>
|-
| TOUR
|Tourists
| 0005 Passengers, express
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|-
| VEHI
|Vehicles
| 0420 Piece goods, oversized
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
|
|
|-
| WDPR
|Wood Products
| 0030 Bulk, piece goods
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|
|-
| WOOL
|Wool
| 0220 Piece goods, covered/sheltered
| style="background: #FFCC00; color: black" | [[ttwiki:ECS|ECS]]
| style="background: #1AD74C; color: white" | [[ttwiki:FIRS|FIRS]]
|<ref name="ecs_cargo_change" />
|-
| align="center" colspan="2" |'''Special Cargos'''
| align="center" colspan="4" | these cargos are for use outside industry sets and do not represent transporting anything
|-
| GEAR
|Locomotive regearing
|8000 Special
|
|
| Using this cargo may make your vehicle set incompatible with some industry sets

use CB36 instead to set capacity to 0
|-
| align="center" colspan="2" |'''Deprecated Cargos'''
| align="center" colspan="4" | these cargos are not used by any current industry set, and are listed here for backwards compatibility
|-
| FUEL
|Fuel
|0040 Liquid
|
|
|Use PETR for refined-oil fuel
|-
| RSGR
|Raw Sugar
|0010 Bulk
|
|
| Deprecated in FIRS. See SGBT and SGCN
|-
| SCRP
|Scrap Metal
|0010 Piece Goods
|
|
| Deprecated in FIRS, use SCMT instead
|-
| TWOD
|Tropic Wood
|0020 Piece goods
|
|
| formerly intended as a default cargo
|-
| WSTE
|Waste
|0010 Bulk
|
|
| Deprecated in FIRS.
|}

<references />

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

GRFResourceManagement

2012-02-13T13:45:42Z

FooBar: /* Description of GRM-ops */ note on not splitting blocks for OpenTTD

== Introduction ==

Preventing conflicts with limited resources

Since TTDPatch 2.0.1 alpha 51, it has been possible to use action D to participate in cooperative resource management.

This feature is useful for avoiding resource conflicts between grf files. A file may query the available resources, check whether certain IDs are available, and/or mark them as reserved. Then, an action 6 will enter the actual values in the appropriate action entries, for example action 0 or 3 for vehicles, and action A for sprites. Alternatively, one can use another action D to set variable 99 and have it adjust the IDs of the relevant actions appropriately.

If the requested resources are not available, the grf file will be deactivated and be shown with an orange colour in the GRF Status Window, as well as a message indicating the type of resource that was not available. Note that previously allocated resources will not be freed if this happens, therefore you must first ''check'' that ''all'' of the resources are available before reserving ''any'' of them. This means if you have more than one type of resource that is required, you need two action D entries for each type, first one action D for each type using the "check" or "find" operation, after all of which follow the action D entries for each type using the "reserve" or "mark" operation.

This type of action D is ignored during initialisation (because the resources are not initialised yet either), and the target parameter will be set to 0 in that case.

'''Please note:''' This resource management is cooperative. That means that grf files that do not use it can still access all IDs, and the patch will never know about it. Only those grf files that use this resource management will "know" of each other and can be sure not to use conflicting resources. If another grf file then uses a "reserved" ID without telling the patch via an action D, there is nothing that will prevent it from doing so.

== Syntax ==

<Sprite-number> * <Length> 0D <target> 00 <GRM-op> FE FF <feature> <count>

{|
!Element!![[GRFActionsDetailed|Size]]!!Description

|-
|0D||B||Defines action 0D

|-
|<target>||B||Target parameter. See also below.

|-
|00||B||Assignment

|-
|<GRM-op>||B||Resource operation to perform. See below.

|-
|FE||B||Defines a special variable access

|-
|FF||B||Prevent conflicts with ReadingOtherGRFParameters

|-
|<feature>||B||Feature to operate on. See below.

|-
|<count>||W||Number of IDs to operate on.
|}

For the check, mark, no-fail check, and get-owner operations, <target> must contain the first ID to be operated on.

== Description of GRM-ops ==

The following operations are available:

Each operation also has a corresponding escape sequence, as listed. See [[GRFActionsDetailed#Byte order|the discussion of escape sequences]] for further information on escape sequences in general.

{|
!Number!!Escape!!Operation!!Result!!Meaning

|-
|00||\DR||Reserve||First found ID||find available resource ID and mark as in use

|-
|01||\DF||Find||First found ID||find available resource ID but do not mark

|-
|02||\DC||Check||(none)||check whether given resources (ID stored in the <target> variable) are available

|-
|03||\DM||Mark||(none)||check that the given resources are available, and if so mark as in use

|-
|04||\DnF||No-fail Find||(see below)||like "Find", but does not deactive the grf if no IDs found

|-
|05||\DnC||No-fail Check||(see below)||like "Check", but does not deactive the grf if there is a conflict

|-
|06||\DO||Get Owner||GRF-ID of owner||Retrieve GRFID that has reserved the given ID (or 0 if not reserved)
|}

Action D returns its result (if any) in the given <target> parameter. If the result is marked as "(none)" in the above table, the <target> parameter is not modified.

The "reserve" and "find" operations will try to find a contiguous block of <count> entries, and store the first number in the target parameter of the action D. If not enough entries can be found, the grf file is deactivated. For OpenTTD it's not useful to split large blocks into multiple smaller blocks, as it is unlikely that even a large block can't be found in the 16777216 allocatable sprites.

The "check" and "mark" operations use the value stored in the ''target'' parameter of the action D, and check/mark the block of <count> entries starting from that number. If not all entries are available, the grf file is deactivated.

The no-fail versions work exactly like their regular counterparts, but they set the <target> parameter to -1 (FFFFFFFF) if the resources are unavailable, which can be checked with action 7 afterwards. They do not deactivate the grf file. If successful, they do nothing. They are useful if the file wants to voluntarily skip certain modifications in case other files have changed them already.

Typically, the "reserve" or "find" operations will be used for files that modify only a few vehicles. For (mostly) complete sets, the "check" and "mark" operations are more useful, because it is often not feasible to remap the IDs of an entire set, so these operations will simply make sure that all needed IDs are available.

For each feature, multiple "find" operations will check for different size blocks, but will always return the same base entry number, so "find" should only be called once for each feature.

== Support for features ==

The following features and feature/GRM-op combinations are supported:

{|
!Feature!!Reserve!!Find!!Check!!Mark!!Get!!Notes

|-
|00 (trains)||<center>0</center>||<center>0</center>||<center>X</center>||<center>X</center>||<center>X</center>||

|-
|01 (road vehicles)||<center>0</center>||<center>0</center>||<center>X</center>||<center>X</center>||<center>X</center>||

|-
|02 (ships)||<center>0</center>||<center>0</center>||<center>X</center>||<center>X</center>||<center>X</center>||

|-
|03 (aircraft)||<center>0</center>||<center>0</center>||<center>X</center>||<center>X</center>||<center>X</center>||

|-
|08 (general sprites)||<center>X</center>||<center>X</center>||<center>*</center>||<center>*</center>||<center>-</center>||

|-
|0B (cargos)||<center>-</center>||<center>-</center>||<center>X</center>||<center>X</center>||<center>X</center>||see below
|}

0 = unsafe, the IDs may change when loading game

X = safe to use

<nowiki>*</nowiki> = safe but useless

- = do not use

For newcargos, IDs 00..1F refer to the cargo IDs themselves (e.g. ID 0B is available in the temperate climate, and 0C..1F in all climates), whereas IDs 20..3F refer to the bit number from prop. 08 plus 20 (e.g. ID 2D, being bit number 0D=fruit, is available in all climates except tropical). You need to check and mark both ID types for correct operation.

NML:Vehicles

2012-01-29T16:01:24Z

FooBar: /* Variables without parameter */ note that cargo_classes requires a bitmask

{{NMLNavPropVarCB}}

==Properties common to all vehicle types==

{| class="t"
! property
! value range
! available for<br />articulated<br />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>
| XXX = [TEMPERATE <nowiki>|</nowiki> ARCTIC <nowiki>|</nowiki> TROPICAL <nowiki>|</nowiki> TOYLAND], alternatively <code style="color:green">NO_CLIMATE</code> or <code style="color:green">ALL_CLIMATES</code>. 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
| example: <code style="color:darkgreen">bitmask(PASS, MAIL, GOOD)</code>
|-
| <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 tick. Default vehicles use 5 for trains and road vehicles, 10 for ships and 20 for aircraft
|-
| <code style="color:green">cost_factor</code>
| 0 ... 255
| =0
| multiplier to the base purchase cost
|-
| <code style="color:green">running_cost_factor</code>
| 0 ... 255
| =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.
|}

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

The results from the above table are always overriden by cargo_allow_refit and cargo_disallow_refit. Whatever the table says, if the cargo is in cargo_allow_refit the vehicle will always be refitable to that cargo.

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.

===Engine life cycle===

The life cycle of a vehicle model consists of three phases, as outlined in the following table.

{| 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
| stays constant at peak, 75-100%
|-
| 3
| 10 to 20.5 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.

==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 <code style="color:darkgreen">sort(FEAT_TRAINS, [D, B, A]);</code> the final sorting will be this: C D B A E

==Train properties==

{| class="t"
! property
! value range
! available for<br />articulated<br />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 the same value
| XXX=[TILT <nowiki>|</nowiki> 2CC <nowiki>|</nowiki> MU <nowiki>|</nowiki> FLIP <nowiki>|</nowiki> 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
|-
| <code style="color:green">refit_cost</code>
| 0 ... 255
| yes
| in 50% units of the purchase price cost base
|-
| <code style="color:green">callback_flags</code>
| bitmask(VEH_CBF_XXX, ...)
| yes
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| <code style="color:green">track_type</code>
| item from railtypetable
| must be the same as front
| Default railtype table: RAIL, MONO, MGLV. If you install a railtypetable yourself you'll always get the railtype you specified. If you want a vehicle to run on electric rail and you don't have a railtypetable, set <code style="color:green">track_type</code> to RAIL and make sure that you set <code style="color:green">engine_class</code> to <code style="color:green">ENGINE_CLASS_ELECTRIC</code>.
|-
| <code style="color:green">ai_special_flag</code>
| [<code style="color:green">AI_FLAG_PASSENGER</code> <nowiki>|</nowiki> <code style="color:green">AI_FLAG_CARGO</code>]
| no
| Set to <code style="color:green">AI_FLAG_PASSENGER</code> to 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)
| =0
|
|-
| <code style="color:green">running_cost_base</code>
| RUNNING_COST_XXX
| =0
| XXX = [STEAM <nowiki>|</nowiki> DIESEL <nowiki>|</nowiki> ELECTRIC <nowiki>|</nowiki> ROADVEH <nowiki>|</nowiki> NONE]
|-
| <code style="color:green">dual_headed</code>
| [0 <nowiki>|</nowiki> 1]
| =0 for both parts
| 1 = dual_headed, otherwise normal engine
|-
| <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)
| =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
| XXX=[STEAM <nowiki>|</nowiki> DIESEL <nowiki>|</nowiki> ELECTRIC <nowiki>|</nowiki> MONORAIL <nowiki>|</nowiki> MAGLEV]
|-
| <code style="color:green">extra_power_per_wagon</code>
| 0 ... 65000 hp (float, power units)
| =0
| Only wagons with a livery override for this engine will add power
|-
| <code style="color:green">tractive_effort_coefficient</code>
| 0 ... 1 (float)
| =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.
|-
| <code style="color:green">air_drag_coefficient</code>
| 0 ... 1 (float)
| =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">shorten_vehicle</code>
| SHORTEN_TO_XXX
| yes
| XXX=[8_8 <nowiki>|</nowiki> 7_8 <nowiki>|</nowiki> ... <nowiki>|</nowiki> 1_8]
|-
| <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
| 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 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.
|-
| <code style="color:green">extra_weight_per_wagon</code>
| 0 ... 255 ton (float, mass units)
| =0
| Adds extra weight for powered wagons, see <code style="color:green">extra_power_per_wagon</code>
|-
| <span #id="bitmask_vehicle_info"></span><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>]]
|}

==Road vehicle properties==

{| class="t"
! property
! value range
! available for<br />articulated<br />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 [[NML:Old style callbacks|old-style callbacks]].
|-
| running_cost_base
| RUNNING_COST_XXX
| set to RUNNING_COST_NONE
| XXX = [STEAM <nowiki>|</nowiki> DIESEL <nowiki>|</nowiki> ELECTRIC <nowiki>|</nowiki> ROADVEH <nowiki>|</nowiki> NONE]
|-
| power
| 0 ... 2550hp (float, power units)
| =0
|
|-
| weight
| 0 ... 63.75ton (float, mass units)
| =0
|
|-
| tractive_effort_coefficient
| 0 ... 1 (float)
| =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)
| =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.
|-
| 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]].
|-
| visual_effect
| visual_effect(VISUAL_EFFECT_XXX, offset)
| yes
| 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 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==

{| class="t"
! 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 [[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.
|-
| 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]].
|-
| 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)
| 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.
|}

==Aircraft properties==

{| class="t"
! 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 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 [[NML:Old style callbacks|old-style callbacks]].
|-
| is_helicopter
| AIRCRAFT_TYPE_XXX
| XXX=[NORMAL <nowiki>|</nowiki> HELICOPTER]
|-
| is_large
| AIRCRAFT_SIZE_XXX
| XXX=[SMALL <nowiki>|</nowiki> 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 <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]].
|}

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

{| class="t"
! name
! value range
! available in<br />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
|
[[NML:Cargos#Cargo classes|cargo classes]]
|-
| most_common_refit
|
[[NML:Cargos#Cargo properties|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|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 [[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 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 <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 ... 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 [[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_reversed
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle has reversed an odd number of times
|-
| built_during_preview
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle was built during the exclusive preview stage
|-
| current_railtype
| 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 [[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
| 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
|-
| vehicle_is_in_depot
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle is inside a depot
|}

===Variables that require an argument===

{| class="t"
! name
! Argument
! value range
! available in<br />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 [[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="t"
! 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.
|-
| purchase
| All
| Yes, only
| Sprite group
| Graphics to show in the buy menu (only the horizontal view is needed)
|-
| 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
| 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 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 <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">extra_callback_info1</code> contains 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">extra_callback_info1</code> contains 1 during the first call, 2 during the second, etc. Note that callback may be called from the purchase list, using vehicle variables is not possible. Or CB_RESULT_REVERSED_VEHICLE to the returned vehicle ID to display the vehicle backwards.

For NML 0.2 and lower the vehicle ID of the articulated part must be in the range 0 .. 127.
|-
| can_attach_wagon
| Trains
| No
| String or CB_RESULT_ATTACH_XXX
| Called when a wagon is being attached, to allow or disallow attaching. This callback has to be defined at the engine. However, variables in the <code style="color:darkgreen">SELF</code> scope refer to the wagon being attached, the <code style="color:darkgreen">PARENT</code> 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.

{| class="t"
! 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
|
|-
| refit_cost
| {{ottdp|1.2|no|ottdrev=r23089}} All
| Yes
| 0 .. 16377 as refit cost. Add <code style="color:darkgreen">CB_RESULT_AUTOREFIT</code> if you want to allow autorefit.
|-
| 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
|
|-
| 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
|-
| shorten_vehicle
| 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
|
|}

===Sound events===

{| class="t"
! 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
|}

ObjectLabels

2012-01-14T19:40:22Z

FooBar: add new Dutch Road Furniture sublabels

=Object labels=

Defining Object Class Label Recommendations

== Recommendations - Predefined ==

# Predefined labels are best used for single objects that are not part of a comprehensive set
# It is possible to have a label for each object. This would make for a very ungainly menu.
# A labeling system allows a coder/author to make their works much more user friendly.
# To keep the numbers more manageable, the classes are as generic as possible.
# While being generic, assigning objects to a label should be intuitive.
# Assuming that there will be special circumstances where a coder/author needs to deviate from the norm, '''the Recommendation is not mandatory'''.

{| |-
!colspan=3|PREDEFINED RECOMMENDATIONS
|-
!Label!!Action4 Text!!Description
|-
|STRU||Structures||Multitile engineered objects that don't quite fit in as industries, houses or stations - dams etc.
|-
|INFR||Infrastructure||light poles, communication towers, transmission towers, road signs, etc.
|-
|BLDG||Buildings||Normally accommodated by industries, houses or stations but the author feels there are limiting circumstances.
|-
|NATR||Natural objects||caves, coral reefs, swamps, etc.
|-
|PARK||Public areas||Normally accommodated by towns or industries (tourist stuff ...) but the author feels there are limiting circumstances - Parks, statues, etc.
|-
|ARTF||Artifacts||They really don't fit under any of the above - shipwrecks, etc.
|-
|MISC||Miscellaneous||For the author who is unable to accommodate his/her object under any of the previous labels.
|}

== Recommendations - Author defined ==

# Author defined labels are best used for comprehensive object sets that consist of several obviously related objects.
# Each label must consist of four (4) alphanumeric characters.
# To prevent menu confusion, new labels should be unique and should not duplicate predefined labels (see chart above) nor previously selected author defined labels (see chart below).
# The author should add their label(s) to the following chart in alphanumeric order.
# If an author is uncomfortable with adding a label to the chart, they can PM their request to [http://www.tt-forums.net/ucp.php?i=pm&mode;=compose&action; wallyweb].
# The chart will be regularly reviewed for duplications.
# The chart will be regularly edited for alphanumeric sequence.

{| |-
!colspan=5|AUTHOR DEFINED RECOMMENDATIONS
|-
!Label!!Action4 Text!!Description!!Author!!TT-Forums link
|-
|EXM1||Example 1||An example label listing||your name here||Forum link goes here
|-
|NLRA||Dutch Road Furniture: Matrix Activators||Activators for matrix signs for Dutch Road Furniture||FooBar||http://www.tt-forums.net/viewtopic.php?t=56316
|-
|NLRF||Dutch Road Furniture||For Dutch road related objects (generic label)||FooBar||http://www.tt-forums.net/viewtopic.php?t=56316
|-
|NLRM||Dutch Road Furniture: Motorways||Motorway related objects for Dutch Road Furniture||FooBar||http://www.tt-forums.net/viewtopic.php?t=56316
|-
|NLRS||Dutch Road Furniture: Signs and Fingerposts||Road signs and fingerposts for Dutch Road Furniture||FooBar||http://www.tt-forums.net/viewtopic.php?t=56316
|}

File:Dospal.png

2011-12-04T13:18:49Z

FooBar: uploaded a new version of "File:Dospal.png": File actually had WIN palette applied and as a result some colours were missing. Now fixed.

DOS palette (=OpenTTD default)

File:TTD Palettes.png

2011-12-04T13:07:47Z

FooBar: uploaded a new version of "File:TTD Palettes.png": A number of colours in the DOS image were incorrect, most notably the water cycles. Colours in both palettes are now correct, except magic pink. DOS palette applied to PNG file.

palettes and indices

NML:Realsprites

2011-09-08T18:54:35Z

FooBar: When there's only one flag, there's nothing to combine with OR

{{NMLNavBlocksyntax}}

Several features will need to reference actual graphics from files you created. You can provide real sprites in many different formats, all detailed below. There is a lot of information you'll need to provide. Most important are the filename and the location of the sprite in that file. Since most blocks that reference realsprites will allow you to specify a default filename, you don't often need to give a filename for every separate sprite.

Allowed formats:

[left_x, upper_y, width, height, offset_x, offset_y]
[left_x, upper_y, width, height, offset_x, offset_y, compression]
[left_x, upper_y, width, height, offset_x, offset_y, filename]
[left_x, upper_y, width, height, offset_x, offset_y, compression, filename]
[offset_x, offset_y]
[offset_x, offset_y, compression]
[offset_x, offset_y, filename]
[offset_x, offset_y, compression, filename]

If you don't specify left_x, upper_y, width and height it'll default to the complete file. If you don't specify the filename it'll take the filename from the block containing this realsprite. It's a fatal error not to specify a filename for either the block containing a realsprite or the realsprite itself. For possible values of compression, see the table below.

For all parameters you can use expressions as complex as you want as long as they can be resolved at compile time.

As of NML r1654 the compression bit has only two possible values. When ommitted it will take the default value.

{| class="t"
! Name
! Description
|-
| CROP (default) or NOCROP
| Whether to crop the sprites when the -c command line option is set.
|}

Example:

<pre style="color:blue">
[0, 0, 64, 31, -31, 0, TILE]
</pre>

NML:List of tile slopes

2011-09-06T13:58:35Z

FooBar: added slope sprites to slope constant table

{{NMLNavAdditionalreferences}}

Tiles in TTD can have various slopes. The slope is a bitmask that may contain the following bits:

{| class="t"
! bit flag
! meaning
|-
| CORNER_W
| west corner is above the lowest corner.
|-
| CORNER_S
| south corner is above the lowest corner.
|-
| CORNER_E
| east corner is above the lowest corner.
|-
| CORNER_N
| north corner is above the lowest corner.
|-
| IS_STEEP_SLOPE
| this tile is a steep slope (the corner opposite to the lowest corner is 2 units higher).
|}

The resulting, possible values of this bitmask are given in the following table. The image below that illustrates them graphically. See also the [[NML:Builtin functions|builtin function]] <code style="color:darkgreen">num_corners_raised(''slope'')</code>.

Sprites for slopes are always in the same order in TTD. For example, <code style="color:darkgreen">GROUND_SPRITE_NORMAL</code> is the sprite number of a flat grass tile. It is followed by 18 other sprites, that display a flat grass tile for each possible slope. The order of these sprites is given in the last column of the table. The [[NML:Builtin functions|builtin function]] <code style="color:darkgreen">slope_to_sprite_offset(''slope'')</code> can be used to determine the sprite offset of a given slope.

{| class="t"
! Sprite
! Named constant
! Equivalent bitmask
! Numerical value
! Sprite offset
|-
| [[Image:Sprite3981.png]]
| SLOPE_FLAT
| <code style="color:darkgreen">bitmask()</code>
| 0
| 0
|-
| [[Image:Sprite3982.png]]
| SLOPE_W
| <code style="color:darkgreen">bitmask(CORNER_W)</code>
| 1
| 1
|-
| [[Image:Sprite3983.png]]
| SLOPE_S
| <code style="color:darkgreen">bitmask(CORNER_S)</code>
| 2
| 2
|-
| [[Image:Sprite3985.png]]
| SLOPE_E
| <code style="color:darkgreen">bitmask(CORNER_E)</code>
| 4
| 4
|-
| [[Image:Sprite3989.png]]
| SLOPE_N
| <code style="color:darkgreen">bitmask(CORNER_N)</code>
| 8
| 8
|-
| [[Image:Sprite3990.png]]
| SLOPE_NW
| <code style="color:darkgreen">bitmask(CORNER_N, CORNER_W)</code>
| 9
| 9
|-
| [[Image:Sprite3984.png]]
| SLOPE_SW
| <code style="color:darkgreen">bitmask(CORNER_S, CORNER_W)</code>
| 3
| 3
|-
| [[Image:Sprite3987.png]]
| SLOPE_SE
| <code style="color:darkgreen">bitmask(CORNER_S, CORNER_E)</code>
| 6
| 6
|-
| [[Image:Sprite3993.png]]
| SLOPE_NE
| <code style="color:darkgreen">bitmask(CORNER_N, CORNER_E)</code>
| 12
| 12
|-
| [[Image:Sprite3986.png]]
| SLOPE_EW
| <code style="color:darkgreen">bitmask(CORNER_E, CORNER_W)</code>
| 5
| 5
|-
| [[Image:Sprite3991.png]]
| SLOPE_NS
| <code style="color:darkgreen">bitmask(CORNER_N, CORNER_S)</code>
| 10
| 10
|-
| [[Image:Sprite3992.png]]
| SLOPE_NWS
| <code style="color:darkgreen">bitmask(CORNER_N, CORNER_W, CORNER_S)</code>
| 11
| 11
|-
| [[Image:Sprite3988.png]]
| SLOPE_WSE
| <code style="color:darkgreen">bitmask(CORNER_W, CORNER_S, CORNER_E)</code>
| 7
| 7
|-
| [[Image:Sprite3995.png]]
| SLOPE_SEN
| <code style="color:darkgreen">bitmask(CORNER_S, CORNER_E, CORNER_N)</code>
| 14
| 14
|-
| [[Image:Sprite3994.png]]
| SLOPE_ENW
| <code style="color:darkgreen">bitmask(CORNER_E, CORNER_N, CORNER_W)</code>
| 13
| 13
|-
| [[Image:Sprite3998.png]]
| SLOPE_STEEP_W
| <code style="color:darkgreen">bitmask(CORNER_N, CORNER_W, CORNER_S, IS_STEEP_SLOPE)</code>
| 27
| 17
|-
| [[Image:Sprite3997.png]]
| SLOPE_STEEP_S
| <code style="color:darkgreen">bitmask(CORNER_W, CORNER_S, CORNER_E, IS_STEEP_SLOPE)</code>
| 23
| 16
|-
| [[Image:Sprite3999.png]]
| SLOPE_STEEP_E
| <code style="color:darkgreen">bitmask(CORNER_S, CORNER_E, CORNER_N, IS_STEEP_SLOPE)</code>
| 30
| 18
|-
| [[Image:Sprite3996.png]]
| SLOPE_STEEP_N
| <code style="color:darkgreen">bitmask(CORNER_E, CORNER_N, CORNER_W, IS_STEEP_SLOPE)</code>
| 29
| 15
|}

<br />[[Image:Industrytile var60.png|frame|left|tile slopes]]

File:Sprite3999.png

2011-09-06T13:55:15Z

FooBar:

File:Sprite3998.png

2011-09-06T13:55:08Z

FooBar:

File:Sprite3997.png

2011-09-06T13:55:00Z

FooBar:

File:Sprite3996.png

2011-09-06T13:54:53Z

FooBar:

File:Sprite3995.png

2011-09-06T13:54:47Z

FooBar:

File:Sprite3994.png

2011-09-06T13:54:39Z

FooBar:

File:Sprite3993.png

2011-09-06T13:54:31Z

FooBar:

File:Sprite3992.png

2011-09-06T13:54:24Z

FooBar:

File:Sprite3991.png

2011-09-06T13:54:17Z

FooBar:

File:Sprite3990.png

2011-09-06T13:54:10Z

FooBar:

File:Sprite3989.png

2011-09-06T13:54:01Z

FooBar:

File:Sprite3988.png

2011-09-06T13:53:54Z

FooBar:

File:Sprite3987.png

2011-09-06T13:53:45Z

FooBar:

File:Sprite3985.png

2011-09-06T13:53:37Z

FooBar:

File:Sprite3986.png

2011-09-06T13:52:55Z

FooBar:

File:Sprite3984.png

2011-09-06T13:52:44Z

FooBar: