GRFSpecs - User contributions [en-gb]

Action0/Tramtypes

2020-05-20T19:47:51Z

Yexo: /* Speed limit (14) */

'''''Action 0 properties for tram types'''''

= Action 0 - Properties for tram types =

Defining properties of tram types.

Up to 63 tramtypes can be defined.

== Properties ==

{| class="wikitable"
|-
!'''Number'''
!'''Version'''
!'''Size'''
!'''Description'''
|-
|08
|{{ottdp|1.10}}
|4*B
|Tram type label
|-
|09
|{{ottdp|1.10}}
|W
|StringID: Build tram toolbar caption
|-
|0A
|{{ottdp|1.10}}
|W
|StringID: Tram construction dropdown text
|-
|0B
|{{ottdp|1.10}}
|W
|StringID: Build vehicle window caption
|-
|0C
|{{ottdp|1.10}}
|W
|StringID: Autoreplace text
|-
|0D
|{{ottdp|1.10}}
|W
|StringID: New engine text
|-
|0F
|{{ottdp|1.10}}
|B n*D
|Powered tram type list<ref name="alt_label">Tram type labels in this list are ''not'' resolved using the alternate label list.</ref>
|-
|10
|{{ottdp|1.10}}
|B
|Tram type flags
|-
|13
|{{ottdp|1.10}}
|W
|Construction costs
|-
|14
|{{ottdp|1.10}}
|W
|Speed limit
|-
|16
|{{ottdp|1.10}}
|B
|Minimap colour
|-
|17
|{{ottdp|1.10}}
|D
|Introduction date
|-
|18
|{{ottdp|1.10}}
|B n*D
|Introduction required tram type list<ref name="alt_label" />
|-
|19
|{{ottdp|1.10}}
|B n*D
|Introduced tram type list<ref name="alt_label" />
|-
|1A
|{{ottdp|1.10}}
|B
|Sort order
|-
|1B
|{{ottdp|1.10}}
|W
|StringID: Tram type name
|-
|1C
|{{ottdp|1.10}}
|W
|Infrastructure maintenance cost factor
|-
|1D
|{{ottdp|1.10}}
|B n*D
|Alternate tram type labels that shall be "redirected" to this tram type
|}

<references />

In NFO, tram type IDs will be GRF local, with an ID to label mapping. Therefore to modify an existing tram type, specify its label in property 08. To create a new tram type, again just specify its label in property 08. This way there is no need for complex GRM mechanisms to allocate IDs. If a label 'clashes' with another GRF, then one GRF will end up modifying the properties instead of creating a new tram type.

When a new tram type is created, it is populated with the information from the first tram type, except that the powered list contains only the tram type being created. However, no default values should be assumed, as the first tram type may have been modified.

== Vehicle and Tramtype availability ==

Vehicle and tramtype availability and compatibility is influenced by multiple properties.
Generally, the vehicle defines which tramtype it is, and the tramtypes define the compatibility between each other.
* A vehicle exists, if its tramtype (road vehicle prop 05) is defined. Otherwise the vehicle is disabled.
* When a vehicle is introduced, it always introduces its tramtype (road vehicle prop 05).
* A tramtype is introduced, if at least one of the following conditions is met:
** A vehicle is introduced, that references the tramtype (road vehicle prop 05).
** Another tramtype is introduced, that references the tramtype via the introduced tramtype list (tramtype prop 19).
** The introduction date (tramtype prop 17) is passed and all required tramtypes (tramtype prop 18) are available.

Via tramtype property 1D multiple tramtypes can be defined, which shall be considered equivalent to a tramtype.
This affects the interpretation of road vehicle property 05. If road vehicle property 05 references an undefined tramtype, then
tramtype property 1D is checked for all defined tramtypes, whether the vehicle can be reassigned to some other tramtype.
Otherwise the vehicle is disabled.

== Tram type label (08) ==

These are globally unique four-letter identifiers for specific tram types (analoguous to [[Action0Cargos#Cargo label 17|cargo labels]]), used to make various tram types accessible from road vehicle grfs. Reserved labels for default tram types are:

{| class="wikitable
|-
!'''Label'''
!'''Tram Type'''
|-
|RAIL
| Normal Tram
|-
|ELRL
| Electrified Tram
|}

Tram type sets may use up to 63 tramtypes and have to specify their own [[TramtypeLabels|labels]].

See also [[Action0/Global Settings#Tram type translation table 12|Tram Type Translation Table]] for further info.

== Build tram toolbar caption (09) ==

String ID of the name of the tram type as shown in the toolbar caption.

== Tram construction dropdown text (0A) ==

String ID for text in the dropdown of all tram types.

This string must never start with a colour control code.

== Build vehicle window caption (0B) ==

String ID for build vehicle window caption.

== Autoreplace text (0C) ==

String ID for tram type shown in autoreplace window.

== New engines (0D) ==

StringID to use for showing texts of the type "We have invented a new <tram type> engine".

== Powered tram type list (0F) ==

List of tram types on which road vehicles of this tram type are powered. E.g. vehicles of "normal tram"-type are powered on "electrified tram"- and "haul-tram"-type as well. Note that there is no "compatible tram type list" since there is no difference between "powered" and "compatible" for tramtypes

The format is:

<pre>0E <nvar> (<tram type label>){n}</pre>

That is you give the number of compatible tram types in a single byte followed by a list of that length of tram type labels. A tram type is automatically powered with itself, so you don't need to list the current tram type.

Note that these properties apply to road vehicles of this tram type, not the tram itself. If you want road vehicles of other tram types to be able to run on your tram types, you must set the powered tram types property for each tram type. Setting these properties behaves always incremental, so you only need to the set additional bits for each other tram type, you cannot remove poweredness once it is set (by some other grf).

== Tram type flags (10) ==

Flags to define properties related to the tram type:

{| class="wikitable"
|-
!'''Bit'''
!'''Value'''
!'''Meaning'''
|-
|0
|1
|Draw catenary for this tram type
|-
|1
|2
|Disallow level crossings for this tram type
|-
|2
|4
|Disallow construction of houses along tramtype
|-
|3
|8
|Hide this tram type from construction menu
|-
|4
|16
|Enables towns to build tramtype, but towns don't build trams...
|}

== Speed limit (14) ==

Speed limit in mph*0.8 (approx. 0.5km/h). Set to "0" for no limit at all.

== Map colour (16) ==

This property defines the colour this tram type is drawn in the minimap view. The byte value specifies the colour entry in the [[PalettesAndCoordinates|DOS palette]].

== Introduction date (17) ==

This property defines the long date formatted introduction date of this tram type. With this property set the tram type will be introduced at (or after) this date when all of the introduction required tram types are available to the company of the player, or whenever a vehicle using this tram type gets introduced whichever is first.

== Introduction required tram type list (18) ==

List of tram types on that need to be available to the company of the player for this tram type to be introduced at (or after) the introduction date. This limit does not apply when the tram type is introduced by the introduction of a vehicle.

Same format as for property 0F above.

This can, for example, be used to introduce a tram type with catenary when both normal tram and electrified tram types are available.

== Introduced tram type list (19) ==

List of tram types that get introduced when this tram type is introduced. For example, to make sure that when a fast tram type is introduced the slow variant exists.

Same format as for property 0F above.

== Sort order (1A) ==

Property for influencing the sort order of the drop down lists with tram types. Default values are as follows:

{| class="wikitable"
|-
!'''Value'''
!'''Meaning'''
|-
|07
|Normal Tram
|-
|17
|Electrified Tram
|-
|n7
|Tramtype #n
|}

Thus the tram 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.

== Tram type name (1B) ==

String ID of the name of the tram type.

== Alternate tram type labels (1D) ==

A list of alternate labels that get "redirected" to this tram type when used e.g. as tram type of road vehicle or when testing if a label is defined. The redirection only happens if the alternate label isn't defined as a real tram type. Same format as for property 0F above.

Alternate labels are not considered when evaluating properties 0F, 18, and 19.

= Example =

To be written

Action0/Roadtypes

2020-05-20T19:47:29Z

Yexo: /* Speed limit (14) */

'''''Action 0 properties for road types'''''

= Action 0 - Properties for road types =

Defining properties of road types.

Up to 63 roadtypes can be defined.

== Properties ==

{| class="wikitable"
|-
!'''Number'''
!'''Version'''
!'''Size'''
!'''Description'''
|-
|08
|{{ottdp|1.10}}
|4*B
|Road type label
|-
|09
|{{ottdp|1.10}}
|W
|StringID: Build road toolbar caption
|-
|0A
|{{ottdp|1.10}}
|W
|StringID: Road construction dropdown text
|-
|0B
|{{ottdp|1.10}}
|W
|StringID: Build vehicle window caption
|-
|0C
|{{ottdp|1.10}}
|W
|StringID: Autoreplace text
|-
|0D
|{{ottdp|1.10}}
|W
|StringID: New engine text
|-
|0F
|{{ottdp|1.10}}
|B n*D
|Powered road type list<ref name="alt_label">Road type labels in this list are ''not'' resolved using the alternate label list.</ref>
|-
|10
|{{ottdp|1.10}}
|B
|Road type flags
|-
|13
|{{ottdp|1.10}}
|W
|Construction costs
|-
|14
|{{ottdp|1.10}}
|W
|Speed limit
|-
|16
|{{ottdp|1.10}}
|B
|Minimap colour
|-
|17
|{{ottdp|1.10}}
|D
|Introduction date
|-
|18
|{{ottdp|1.10}}
|B n*D
|Introduction required road type list<ref name="alt_label" />
|-
|19
|{{ottdp|1.10}}
|B n*D
|Introduced road type list<ref name="alt_label" />
|-
|1A
|{{ottdp|1.10}}
|B
|Sort order
|-
|1B
|{{ottdp|1.10}}
|W
|StringID: Road type name
|-
|1C
|{{ottdp|1.10}}
|W
|Infrastructure maintenance cost factor
|-
|1D
|{{ottdp|1.10}}
|B n*D
|Alternate road type labels that shall be "redirected" to this road type
|}

<references />

In NFO, road type IDs will be GRF local, with an ID to label mapping. Therefore to modify an existing road type, specify its label in property 08. To create a new road type, again just specify its label in property 08. This way there is no need for complex GRM mechanisms to allocate IDs. If a label 'clashes' with another GRF, then one GRF will end up modifying the properties instead of creating a new road type.

When a new road type is created, it is populated with the information from the first road type, except that the powered list contains only the road type being created. However, no default values should be assumed, as the first road type may have been modified.

== Vehicle and Roadtype availability ==

Vehicle and roadtype availability and compatibility is influenced by multiple properties.
Generally, the vehicle defines which roadtype it is, and the roadtypes define the compatibility between each other.
* A vehicle exists, if its roadtype (road vehicle prop 05) is defined. Otherwise the vehicle is disabled.
* When a vehicle is introduced, it always introduces its roadtype (road vehicle prop 05).
* A roadtype is introduced, if at least one of the following conditions is met:
** A vehicle is introduced, that references the roadtype (road vehicle prop 05).
** Another roadtype is introduced, that references the roadtype via the introduced roadtype list (roadtype prop 19).
** The introduction date (roadtype prop 17) is passed and all required roadtypes (roadtype prop 18) are available.

Via roadtype property 1D multiple roadtypes can be defined, which shall be considered equivalent to a roadtype.
This affects the interpretation of road vehicle property 05. If road vehicle property 05 references an undefined roadtype, then
roadtype property 1D is checked for all defined roadtypes, whether the vehicle can be reassigned to some other roadtype.
Otherwise the vehicle is disabled.

== Road type label (08) ==

These are globally unique four-letter identifiers for specific road types (analoguous to [[Action0Cargos#Cargo label 17|cargo labels]]), used to make various road types accessible from road vehicle grfs. Reserved labels for default road types are:

{| class="wikitable
|-
!'''Label'''
!'''Road Type'''
|-
|ROAD
| Normal Road
|-
|ELRD
| Electrified Road
|}

Road type sets may use up to 63 roadtypes and have to specify their own [[RoadtypeLabels|labels]].

See also [[Action0/Global Settings#Road type translation table 12|Road Type Translation Table]] for further info.

== Build road toolbar caption (09) ==

String ID of the name of the road type as shown in the toolbar caption.

== Road construction dropdown text (0A) ==

String ID for text in the dropdown of all road types.

This string must never start with a colour control code.

== Build vehicle window caption (0B) ==

String ID for build vehicle window caption.

== Autoreplace text (0C) ==

String ID for road type shown in autoreplace window.

== New engines (0D) ==

StringID to use for showing texts of the type "We have invented a new <road type> engine".

== Powered road type list (0F) ==

List of road types on which road vehicles of this road type are powered. E.g. vehicles of "normal road"-type are powered on "electrified road"- and "haul-road"-type as well. Note that there is no "compatible road type list" since there is no difference between "powered" and "compatible" for roadtypes

The format is:

<pre>0E <nvar> (<road type label>){n}</pre>

That is you give the number of compatible road types in a single byte followed by a list of that length of road type labels. A road type is automatically powered with itself, so you don't need to list the current road type.

Note that these properties apply to road vehicles of this road type, not the road itself. If you want road vehicles of other road types to be able to run on your road types, you must set the powered road types property for each road type. Setting these properties behaves always incremental, so you only need to the set additional bits for each other road type, you cannot remove poweredness once it is set (by some other grf).

== Road type flags (10) ==

Flags to define properties related to the road type:

{| class="wikitable"
|-
!'''Bit'''
!'''Value'''
!'''Meaning'''
|-
|0
|1
|Draw catenary for this road type
|-
|1
|2
|Disallow level crossings for this road type
|-
|2
|4
|Disallow construction of houses along roadtype
|-
|3
|8
|Hide this road type from construction menu
|-
|4
|16
|Enables road type to be built by towns, picked by highest speed limit (defaults to ROAD label if no speed limits?)
|}

== Speed limit (14) ==

Speed limit in mph*0.8 (approx. 0.5km/h). Set to "0" for no limit at all.

== Map colour (16) ==

This property defines the colour this road type is drawn in the minimap view. The byte value specifies the colour entry in the [[PalettesAndCoordinates|DOS palette]].

== Introduction date (17) ==

This property defines the long date formatted introduction date of this road type. With this property set the road type will be introduced at (or after) this date when all of the introduction required road types are available to the company of the player, or whenever a vehicle using this road type gets introduced whichever is first.

== Introduction required road type list (18) ==

List of road types on that need to be available to the company of the player for this road type to be introduced at (or after) the introduction date. This limit does not apply when the road type is introduced by the introduction of a vehicle.

Same format as for property 0F above.

This can, for example, be used to introduce a road type with streetlights when both paved road and electrified road types are available.

== Introduced road type list (19) ==

List of road types that get introduced when this road type is introduced. For example, to make sure that when a fast road type is introduced the slow variant exists.

Same format as for property 0F above.

== Sort order (1A) ==

Property for influencing the sort order of the drop down lists with road types. Default values are as follows:

{| class="wikitable"
|-
!'''Value'''
!'''Meaning'''
|-
|07
|Normal Road
|-
|17
|Electrified Road
|-
|n7
|Roadtype #n
|}

Thus the road 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.

== Road type name (1B) ==

String ID of the name of the road type.

== Alternate road type labels (1D) ==

A list of alternate labels that get "redirected" to this road type when used e.g. as road type of road vehicle or when testing if a label is defined. The redirection only happens if the alternate label isn't defined as a real road type. Same format as for property 0F above.

Alternate labels are not considered when evaluating properties 0F, 18, and 19.

= Example =

To be written

Action0/Tramtypes

2020-05-19T18:09:58Z

Yexo: /* Speed limit (14) */

'''''Action 0 properties for tram types'''''

= Action 0 - Properties for tram types =

Defining properties of tram types.

Up to 63 tramtypes can be defined.

== Properties ==

{| class="wikitable"
|-
!'''Number'''
!'''Version'''
!'''Size'''
!'''Description'''
|-
|08
|{{ottdp|1.10}}
|4*B
|Tram type label
|-
|09
|{{ottdp|1.10}}
|W
|StringID: Build tram toolbar caption
|-
|0A
|{{ottdp|1.10}}
|W
|StringID: Tram construction dropdown text
|-
|0B
|{{ottdp|1.10}}
|W
|StringID: Build vehicle window caption
|-
|0C
|{{ottdp|1.10}}
|W
|StringID: Autoreplace text
|-
|0D
|{{ottdp|1.10}}
|W
|StringID: New engine text
|-
|0F
|{{ottdp|1.10}}
|B n*D
|Powered tram type list<ref name="alt_label">Tram type labels in this list are ''not'' resolved using the alternate label list.</ref>
|-
|10
|{{ottdp|1.10}}
|B
|Tram type flags
|-
|13
|{{ottdp|1.10}}
|W
|Construction costs
|-
|14
|{{ottdp|1.10}}
|W
|Speed limit
|-
|16
|{{ottdp|1.10}}
|B
|Minimap colour
|-
|17
|{{ottdp|1.10}}
|D
|Introduction date
|-
|18
|{{ottdp|1.10}}
|B n*D
|Introduction required tram type list<ref name="alt_label" />
|-
|19
|{{ottdp|1.10}}
|B n*D
|Introduced tram type list<ref name="alt_label" />
|-
|1A
|{{ottdp|1.10}}
|B
|Sort order
|-
|1B
|{{ottdp|1.10}}
|W
|StringID: Tram type name
|-
|1C
|{{ottdp|1.10}}
|W
|Infrastructure maintenance cost factor
|-
|1D
|{{ottdp|1.10}}
|B n*D
|Alternate tram type labels that shall be "redirected" to this tram type
|}

<references />

In NFO, tram type IDs will be GRF local, with an ID to label mapping. Therefore to modify an existing tram type, specify its label in property 08. To create a new tram type, again just specify its label in property 08. This way there is no need for complex GRM mechanisms to allocate IDs. If a label 'clashes' with another GRF, then one GRF will end up modifying the properties instead of creating a new tram type.

When a new tram type is created, it is populated with the information from the first tram type, except that the powered list contains only the tram type being created. However, no default values should be assumed, as the first tram type may have been modified.

== Vehicle and Tramtype availability ==

Vehicle and tramtype availability and compatibility is influenced by multiple properties.
Generally, the vehicle defines which tramtype it is, and the tramtypes define the compatibility between each other.
* A vehicle exists, if its tramtype (road vehicle prop 05) is defined. Otherwise the vehicle is disabled.
* When a vehicle is introduced, it always introduces its tramtype (road vehicle prop 05).
* A tramtype is introduced, if at least one of the following conditions is met:
** A vehicle is introduced, that references the tramtype (road vehicle prop 05).
** Another tramtype is introduced, that references the tramtype via the introduced tramtype list (tramtype prop 19).
** The introduction date (tramtype prop 17) is passed and all required tramtypes (tramtype prop 18) are available.

Via tramtype property 1D multiple tramtypes can be defined, which shall be considered equivalent to a tramtype.
This affects the interpretation of road vehicle property 05. If road vehicle property 05 references an undefined tramtype, then
tramtype property 1D is checked for all defined tramtypes, whether the vehicle can be reassigned to some other tramtype.
Otherwise the vehicle is disabled.

== Tram type label (08) ==

These are globally unique four-letter identifiers for specific tram types (analoguous to [[Action0Cargos#Cargo label 17|cargo labels]]), used to make various tram types accessible from road vehicle grfs. Reserved labels for default tram types are:

{| class="wikitable
|-
!'''Label'''
!'''Tram Type'''
|-
|RAIL
| Normal Tram
|-
|ELRL
| Electrified Tram
|}

Tram type sets may use up to 63 tramtypes and have to specify their own [[TramtypeLabels|labels]].

See also [[Action0/Global Settings#Tram type translation table 12|Tram Type Translation Table]] for further info.

== Build tram toolbar caption (09) ==

String ID of the name of the tram type as shown in the toolbar caption.

== Tram construction dropdown text (0A) ==

String ID for text in the dropdown of all tram types.

This string must never start with a colour control code.

== Build vehicle window caption (0B) ==

String ID for build vehicle window caption.

== Autoreplace text (0C) ==

String ID for tram type shown in autoreplace window.

== New engines (0D) ==

StringID to use for showing texts of the type "We have invented a new <tram type> engine".

== Powered tram type list (0F) ==

List of tram types on which road vehicles of this tram type are powered. E.g. vehicles of "normal tram"-type are powered on "electrified tram"- and "haul-tram"-type as well. Note that there is no "compatible tram type list" since there is no difference between "powered" and "compatible" for tramtypes

The format is:

<pre>0E <nvar> (<tram type label>){n}</pre>

That is you give the number of compatible tram types in a single byte followed by a list of that length of tram type labels. A tram type is automatically powered with itself, so you don't need to list the current tram type.

Note that these properties apply to road vehicles of this tram type, not the tram itself. If you want road vehicles of other tram types to be able to run on your tram types, you must set the powered tram types property for each tram type. Setting these properties behaves always incremental, so you only need to the set additional bits for each other tram type, you cannot remove poweredness once it is set (by some other grf).

== Tram type flags (10) ==

Flags to define properties related to the tram type:

{| class="wikitable"
|-
!'''Bit'''
!'''Value'''
!'''Meaning'''
|-
|0
|1
|Draw catenary for this tram type
|-
|1
|2
|Disallow level crossings for this tram type
|-
|2
|4
|Disallow construction of houses along tramtype
|-
|3
|8
|Hide this tram type from construction menu
|-
|4
|16
|Enables towns to build tramtype, but towns don't build trams...
|}

== Speed limit (14) ==

Speed limit in mph*3.2 (approx. km/h*2). Set to "0" for no limit at all.

== Map colour (16) ==

This property defines the colour this tram type is drawn in the minimap view. The byte value specifies the colour entry in the [[PalettesAndCoordinates|DOS palette]].

== Introduction date (17) ==

This property defines the long date formatted introduction date of this tram type. With this property set the tram type will be introduced at (or after) this date when all of the introduction required tram types are available to the company of the player, or whenever a vehicle using this tram type gets introduced whichever is first.

== Introduction required tram type list (18) ==

List of tram types on that need to be available to the company of the player for this tram type to be introduced at (or after) the introduction date. This limit does not apply when the tram type is introduced by the introduction of a vehicle.

Same format as for property 0F above.

This can, for example, be used to introduce a tram type with catenary when both normal tram and electrified tram types are available.

== Introduced tram type list (19) ==

List of tram types that get introduced when this tram type is introduced. For example, to make sure that when a fast tram type is introduced the slow variant exists.

Same format as for property 0F above.

== Sort order (1A) ==

Property for influencing the sort order of the drop down lists with tram types. Default values are as follows:

{| class="wikitable"
|-
!'''Value'''
!'''Meaning'''
|-
|07
|Normal Tram
|-
|17
|Electrified Tram
|-
|n7
|Tramtype #n
|}

Thus the tram 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.

== Tram type name (1B) ==

String ID of the name of the tram type.

== Alternate tram type labels (1D) ==

A list of alternate labels that get "redirected" to this tram type when used e.g. as tram type of road vehicle or when testing if a label is defined. The redirection only happens if the alternate label isn't defined as a real tram type. Same format as for property 0F above.

Alternate labels are not considered when evaluating properties 0F, 18, and 19.

= Example =

To be written

Action0/Roadtypes

2020-05-19T18:09:35Z

Yexo: /* Speed limit (14) */

'''''Action 0 properties for road types'''''

= Action 0 - Properties for road types =

Defining properties of road types.

Up to 63 roadtypes can be defined.

== Properties ==

{| class="wikitable"
|-
!'''Number'''
!'''Version'''
!'''Size'''
!'''Description'''
|-
|08
|{{ottdp|1.10}}
|4*B
|Road type label
|-
|09
|{{ottdp|1.10}}
|W
|StringID: Build road toolbar caption
|-
|0A
|{{ottdp|1.10}}
|W
|StringID: Road construction dropdown text
|-
|0B
|{{ottdp|1.10}}
|W
|StringID: Build vehicle window caption
|-
|0C
|{{ottdp|1.10}}
|W
|StringID: Autoreplace text
|-
|0D
|{{ottdp|1.10}}
|W
|StringID: New engine text
|-
|0F
|{{ottdp|1.10}}
|B n*D
|Powered road type list<ref name="alt_label">Road type labels in this list are ''not'' resolved using the alternate label list.</ref>
|-
|10
|{{ottdp|1.10}}
|B
|Road type flags
|-
|13
|{{ottdp|1.10}}
|W
|Construction costs
|-
|14
|{{ottdp|1.10}}
|W
|Speed limit
|-
|16
|{{ottdp|1.10}}
|B
|Minimap colour
|-
|17
|{{ottdp|1.10}}
|D
|Introduction date
|-
|18
|{{ottdp|1.10}}
|B n*D
|Introduction required road type list<ref name="alt_label" />
|-
|19
|{{ottdp|1.10}}
|B n*D
|Introduced road type list<ref name="alt_label" />
|-
|1A
|{{ottdp|1.10}}
|B
|Sort order
|-
|1B
|{{ottdp|1.10}}
|W
|StringID: Road type name
|-
|1C
|{{ottdp|1.10}}
|W
|Infrastructure maintenance cost factor
|-
|1D
|{{ottdp|1.10}}
|B n*D
|Alternate road type labels that shall be "redirected" to this road type
|}

<references />

In NFO, road type IDs will be GRF local, with an ID to label mapping. Therefore to modify an existing road type, specify its label in property 08. To create a new road type, again just specify its label in property 08. This way there is no need for complex GRM mechanisms to allocate IDs. If a label 'clashes' with another GRF, then one GRF will end up modifying the properties instead of creating a new road type.

When a new road type is created, it is populated with the information from the first road type, except that the powered list contains only the road type being created. However, no default values should be assumed, as the first road type may have been modified.

== Vehicle and Roadtype availability ==

Vehicle and roadtype availability and compatibility is influenced by multiple properties.
Generally, the vehicle defines which roadtype it is, and the roadtypes define the compatibility between each other.
* A vehicle exists, if its roadtype (road vehicle prop 05) is defined. Otherwise the vehicle is disabled.
* When a vehicle is introduced, it always introduces its roadtype (road vehicle prop 05).
* A roadtype is introduced, if at least one of the following conditions is met:
** A vehicle is introduced, that references the roadtype (road vehicle prop 05).
** Another roadtype is introduced, that references the roadtype via the introduced roadtype list (roadtype prop 19).
** The introduction date (roadtype prop 17) is passed and all required roadtypes (roadtype prop 18) are available.

Via roadtype property 1D multiple roadtypes can be defined, which shall be considered equivalent to a roadtype.
This affects the interpretation of road vehicle property 05. If road vehicle property 05 references an undefined roadtype, then
roadtype property 1D is checked for all defined roadtypes, whether the vehicle can be reassigned to some other roadtype.
Otherwise the vehicle is disabled.

== Road type label (08) ==

These are globally unique four-letter identifiers for specific road types (analoguous to [[Action0Cargos#Cargo label 17|cargo labels]]), used to make various road types accessible from road vehicle grfs. Reserved labels for default road types are:

{| class="wikitable
|-
!'''Label'''
!'''Road Type'''
|-
|ROAD
| Normal Road
|-
|ELRD
| Electrified Road
|}

Road type sets may use up to 63 roadtypes and have to specify their own [[RoadtypeLabels|labels]].

See also [[Action0/Global Settings#Road type translation table 12|Road Type Translation Table]] for further info.

== Build road toolbar caption (09) ==

String ID of the name of the road type as shown in the toolbar caption.

== Road construction dropdown text (0A) ==

String ID for text in the dropdown of all road types.

This string must never start with a colour control code.

== Build vehicle window caption (0B) ==

String ID for build vehicle window caption.

== Autoreplace text (0C) ==

String ID for road type shown in autoreplace window.

== New engines (0D) ==

StringID to use for showing texts of the type "We have invented a new <road type> engine".

== Powered road type list (0F) ==

List of road types on which road vehicles of this road type are powered. E.g. vehicles of "normal road"-type are powered on "electrified road"- and "haul-road"-type as well. Note that there is no "compatible road type list" since there is no difference between "powered" and "compatible" for roadtypes

The format is:

<pre>0E <nvar> (<road type label>){n}</pre>

That is you give the number of compatible road types in a single byte followed by a list of that length of road type labels. A road type is automatically powered with itself, so you don't need to list the current road type.

Note that these properties apply to road vehicles of this road type, not the road itself. If you want road vehicles of other road types to be able to run on your road types, you must set the powered road types property for each road type. Setting these properties behaves always incremental, so you only need to the set additional bits for each other road type, you cannot remove poweredness once it is set (by some other grf).

== Road type flags (10) ==

Flags to define properties related to the road type:

{| class="wikitable"
|-
!'''Bit'''
!'''Value'''
!'''Meaning'''
|-
|0
|1
|Draw catenary for this road type
|-
|1
|2
|Disallow level crossings for this road type
|-
|2
|4
|Disallow construction of houses along roadtype
|-
|3
|8
|Hide this road type from construction menu
|-
|4
|16
|Enables road type to be built by towns, picked by highest speed limit (defaults to ROAD label if no speed limits?)
|}

== Speed limit (14) ==

Speed limit in mph*3.2 (approx. km/h*2). Set to "0" for no limit at all.

== Map colour (16) ==

This property defines the colour this road type is drawn in the minimap view. The byte value specifies the colour entry in the [[PalettesAndCoordinates|DOS palette]].

== Introduction date (17) ==

This property defines the long date formatted introduction date of this road type. With this property set the road type will be introduced at (or after) this date when all of the introduction required road types are available to the company of the player, or whenever a vehicle using this road type gets introduced whichever is first.

== Introduction required road type list (18) ==

List of road types on that need to be available to the company of the player for this road type to be introduced at (or after) the introduction date. This limit does not apply when the road type is introduced by the introduction of a vehicle.

Same format as for property 0F above.

This can, for example, be used to introduce a road type with streetlights when both paved road and electrified road types are available.

== Introduced road type list (19) ==

List of road types that get introduced when this road type is introduced. For example, to make sure that when a fast road type is introduced the slow variant exists.

Same format as for property 0F above.

== Sort order (1A) ==

Property for influencing the sort order of the drop down lists with road types. Default values are as follows:

{| class="wikitable"
|-
!'''Value'''
!'''Meaning'''
|-
|07
|Normal Road
|-
|17
|Electrified Road
|-
|n7
|Roadtype #n
|}

Thus the road 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.

== Road type name (1B) ==

String ID of the name of the road type.

== Alternate road type labels (1D) ==

A list of alternate labels that get "redirected" to this road type when used e.g. as road type of road vehicle or when testing if a label is defined. The redirection only happens if the alternate label isn't defined as a real road type. Same format as for property 0F above.

Alternate labels are not considered when evaluating properties 0F, 18, and 19.

= Example =

To be written

Action5

2012-11-15T23:13:53Z

Yexo: OpenTTD GUI sprites now up to 168

== Introduction ==

Define base graphics specific sets

Action 5 is used to define graphics for several new features of OpenTTD and TTDPatch. This is similar to action 1.

== Syntax ==

The data looks as follows:

<Sprite-number> * <Length> 05 <type> <num-sprites> [<offset>]

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

|-
|<Sprite-number>||dec||A sequential sprite number

|-
|<length>||dec||The total number of bytes used in this action

|-
|05||B||Defines action 05

|-
|<type>||B||What type of graphics follow

|-
|<num-sprites>||B*||How many regular sprites follow

|-
|<offset>||B*||Offset in the Action 5 assignable block of sprites
|}

The following num-sprites sprites in the .nfo file have to be RealSprites that will be used as graphics for the given TTDPatch feature, except for type 0A, which requires RecolorSprites.

{{ottdp|0.7|2.5|ttdprev=alpha 19}}Action 5 entries in a .grf file which has a regular GRFID (not FFFFFFFF) will always override those from .grf files with a GRFID of FFFFFFFF.

== Description ==

=== Sprite-number ===

This is just the number you are at.

=== Length ===

Count the number of bytes in this action.

=== type ===

This sets the type of feature that the graphics are for. If bit 7 is set, the offset variable needs to be set. Bit 7 may only be set if the type supports it. The type can be one of:

{|
!Type!!Version!!Feature!!num-sprites (decimal)

|-
|04||{{ottdp|0.6|2.0}}||Pre-signal graphics||48

|-
|04||{{ottdp|0.6|2.0}}||Pre-signal and semaphore graphics||112

|-
|04,84<ref name="offset">Offset allowed since {{ottdp|1.2|no|ottdrev=r23005}}</ref>||{{ottdp| |2.5|ttdprev=alpha 41}}||Pre-signal, semaphore, and [[PathBasedSignalling|PBS]] graphics||240

|-
|05,85<ref name="offset" />||{{ottdp|0.6|2.0}}||Overhead wires and pylon graphics||48

|-
|06 ||{{ottdp|0.6| }}||Foundations (retaining walls) for BuildOnSlopes ||74

|-
|06,86<ref name="offset" />||{{ottdp|0.6|no|ottdrev=r11321}}||Foundations for BuildOnSlopes and half tiles (NS and EW foundations) ||90

|-
|07||{{ottdp|no|2.5|ttdprev=alpha 43}}||TTDPatch GUI sprites||93 <ref>Type 07 only requires 73 sprites in the stable (2.5 branch); the extra sprites are the clone train and build canal cursors.</ref>

|-
|08,88<ref name="offset" />||{{ottdp|0.6|no}}<ref>TTDPatch supported canals via Action5 from 2.0.1 alpha 17 up to alpha 25. In alpha 26 it was removed again in favour of an action-1-2-3 method; see [[Action3/Canals|Action3]]. The method via Action5 is no longer supported by TTDpatch 2.0.1 alpha 26 and newer.</ref>||Canals||65

|-
|09,89<ref name="offset" />||{{ottdp|0.6|2.5|ttdprev=alpha 58}}||One-way road arrows||6

|-
|0A,8A<ref name="offset" />||{{ottdp|0.6|2.5|ttdprev=alpha 67}}||Two company color translation maps||256

|-
|0B,8B<ref name="offset" />||{{ottdp|0.6|2.5|ttdprev=alpha 68}}||Tram tracks||113

|-
|0C||{{ottdp|no|2.5|ttdprev=alpha 74}}||Snowy temperate trees||133

|-
|0D||{{ottdp|0.6|2.5|ottdrev=r7325 (r11726)|ttdprev=beta 5}}||Coast Tile graphics||16 (18)

|-
|0E||{{ottdp|no|2.6|ttdprev=r1247}}||New Signals||Any

|-
|0F,8F<ref name="offset" />||{{ottdp|0.7|2.6|ottdrev=r13469|ttdprev=r1487}}||Sprites for marking tracks on slopes (for track reservation systems like PBS or YAPP)||Up to 12

|-
|10,90<ref name="offset" />||{{ottdp|0.6|no|ottdrev=r9645}}||Additional airport graphics||15

|-
|11,91<ref name="offset" />||{{ottdp|0.6|2.6|ottdrev=r9645|ttdprev=r1589}}||Road stop graphics||8

|-
|12,92<ref name="offset" />||{{ottdp|0.7|2.6|ottdrev=r13464|ttdprev=r1498}}||Aqueduct graphics||8

|-
|13,93<ref name="offset" />||{{ottdp|0.6|no|ottdrev=r11433}}||Autorail sprites||55

|-
|14,94||{{ottdp|0.6|no|ottdrev=11433}}||Flag sprites||Up to 36

|-
|15,95||{{ottdp|0.6|no|ottdrev=r11433}}||OpenTTD GUI sprites||Up to 168

|-
|16,96||{{ottdp|1.1|no|ottdrev=r20370}}||Airport preview sprites||Up to 9

|-
|17,97||{{ottdp|1.2|no|ottdrev=r23952}}||Railtype tunnel base sprites||16
|}

<references/>

==== 04 Signal graphics. ====

Signal graphics come in groups of 16. These groups contain sprites in the same order as sprites 1275-1290 in trg1[r].grf; red, then green, for each of: SW-facing, NE-facing, NW-facing, SE-facing, E-facing, W-facing, S-facing, N-facing.

{|
!Group(s)!!Contents

|-
|0||lighted entrance signals

|-
|1||lighted exit signals

|-
|2||lighted combo signals

|-
|3||standard (non-pre-signal) semaphore signals

|-
|4..6||repeat 0..2 for semaphores

|-
|7||standard lighted PBS signals

|-
|8..14||repeat 0..6 for PBS signals
|}

==== 0C Snowy temperate trees ====

If the temperate snow line is enabled, you can use this to specify the snowy versions of temperate trees. The sprites must be the snowy versions of sprites 1576-1708 from TRG1.GRF, in the same order as they appear there.

==== 0D Coast tile sprites ====

If diagonal flooding is enabled then due to new corner coasts, you can use this to give a complete set of replacement coast tile sprites. There are 16 in total, 8 original Transport Tycoon Deluxe sprites and 8 for the corner slopes. Order of the sprites (1) is as follows:

3997, 4063, 4064, 4068, 4062, 3998, 4066, 3988,
4065, 4069, 3996, 3992, 4067, 3994, 3995, 3999.

(1) Sprite numbers from trg1(r).pcx.

[[File:Action5Coast16Sprites.png]]

''The 16 sprites for feature 0D''

Additionally, OpenTTD (since r11726) supports another method of supplying all additional coast tile sprites, but this is only allowed in the ''extra'' NewGRF of [http://wiki.openttd.org/Base_graphics Base Graphic Sets]. In this, only 10 sprites are supplied in the same order as the 16 sprites above, but without the coast sprites already in trg1(r).pcx. Note that the 10 sprites version supplies two additional slopes, but they are not used, and are currently unlikely to be ever used.

[[File:Action5Coast10Sprites.png]]

''Only 10 sprites are required for OpenTTD base graphic sets''

''In OpenTTD 10 sprites for type 0D is enough in base graphic sets. The 16 sprites version should not be used for base graphics.''

The reason for the existence of a 10 sprite version is to remove the need for including original graphics, and to keep compatibility with old NewGRFs that replace the original shore graphics using Action A without adding new shores using Action 5: When a NewGRF uses the 16 sprites version it takes precedence above any NewGRF replacing the shore graphics using Action A; when a NewGRF uses Action A to replace shore graphics it takes precedence above a 10-sprite Action 5, effectively disabling diagonal flooding. Also due to compatibility the 10 sprites version is invalid for normal NewGRFs, which are not the "extra" NewGRF of some Base Graphics Set.

==== 0E New Signals ====

Any number of real and recolour sprites can be specified in the action in any order.

Sprites are referenced by their offset into the action5 block by a [[VarAction2NewSignals]], hence a logically easily calculable order is advised.

As of TTDPatch 2.6 alpha 0 r1346, the action 5 block defined in the same GRF file as the varaction2, will be used as the base sprite block for the offsets returned by the callback even if it is overridden by a higher priority GRF action 5 definition of the same feature (0E).

==== 0F Tracks for Slopes ====

This should be in the same order as sprites 1031 to 1035 (1). These should only be the rails, basically the same format as sprites 1005 to 1010 (1). There should be 3 groups of these sprites, one for each rail type (railroad, monorail, maglev).

(1) Sprite numbers from trg1r.pcx / ogfx1_base.grf

==== 11 Road stop graphics ====

Road stop graphics consist of 2 groups of 4 sprites. The first group contains graphics for bus stops, second for truck stops. In each group, the sprites are in the following order: SW, NE, NW, SE.

SW and NE sprites are used with road going along the Y axis ( .\' ), NW and SE with road along the X axis( '/. ).

Internally, the stations are defined using the following station layouts:

<pre>\d1313

\b13 \b0 \b0 \b3 \b16 \b16 <SW sprite>

\b0 \b0 \b0 \b3 \b16 \b16 <NE sprite>

80</pre>

and

<pre>\d1314

\b0 \b0 \b0 \b16 \b3 \b16 <NW sprite>

\b0 \b13 \b0 \b16 \b3 \b16 <SE sprite>

80</pre>

where 1313 and 1314 are town road sprites.

[[File:roadstops.png]]

Further sprites can be found in '''openttd.grf''' (OpenTTD), '''ogfxe_extra.grf''' (OpenGFX) or '''ttdpbase(w).grf''' (TTDPatch).

'''Note''': As of OpenTTD r10185, the behaviour of this feature is identical in both games.

==== 12 Aqueducts ====

8 real sprites should be given. Firstly: 4 bridge end sprites in the order: SW, SE, NE, NW, where the direction is that heading onto the aqueduct. Then 2 middle part sprites for the X and Y directions. Followed by two pillar sprites for the X and Y directions. For examples of where the division between middle sprites and pillars should be made see sprites 2437 to 2592 (1), or an existing aqueduct GRF. Note, that for higher bridges to work effectively, pillars should be approximately 8px in height.

[[File:aqueduct.png]]

==== 15 / 95 OpenTTD GUI sprites ====

OpenTTD defines 162 GUI sprites. Additional sprites not needed by an OpenTTD are simply ignored, so that new(er) base sets can be used by old OpenTTD versions. One can (re-)define a subset of the GUI sprites by giving an offset into the GUI sprites. The sprites are:
{|
!Offset !! Meaning
|-
|0 .. 11|| Halftile selections
|-
|12 .. 13 || Title screen letters E and D
|-
|14 .. 37 || Bridge piers colours 1 .. 4
|-
|38 || square indicating NewGRF compatibility
|-
|39 || blob indicating server compatibility
|-
|40 || lock icon
|-
|41 || empty check box
|-
|42 || checked check box
|-
|43 || warning sign
|-
|44 || window resize right
|-
|45 .. 48|| arrows
|-
|49 || house
|-
|50 || shared orders
|-
|51 .. 52 || pin / pinned
|-
|53 .. 62 || rail build icons and cursors
|-
|63 .. 68 || monorail build icons and cursors
|-
|69 .. 74 || maglev build icons and cursors
|-
|75 || ??
|-
|76 .. 77 || waypoint toolbar and cursor icon
|-
|78 .. 81 || waypoint buildings
|-
|82 .. 85 || autoroad toobar and cursor for road and trams
|-
|86 || helipad
|-
|87 || build ship lift cursor
|-
|88 .. 89 || build canal toolbar and cursor
|-
|90 || fast forward
|-
|91 .. 92 || level land toolbar and cursor
|-
|93 .. 96 || sell vehicle
|-
|97 .. 100 || sell all vehicles
|-
|101 .. 104 || replace vehicle
|-
|105 || sell chain of rail vehicles
|-
|106 .. 113 || clone vehicles button and cursors
|-
|114 .. 117 || create vehicle group button
|-
|118 .. 121 || delete vehicle group button
|-
|122 .. 125 || rename vehicle group button
|-
|126 .. 133 || group replace on / off button
|-
|134 || road toolbar: build one-way roads
|-
|135 || signal toolbar: convert signals
|-
|136 .. 137|| build rivers toolbar and cursor
|-
|138 .. 143 || OSK
|-
|144 || switch toolbar
|-
|145 .. 146 || build aqueduct toolbar and cursor
|-
|147 .. 148 || (+) and (-) icon
|-
|149 || window resize left
|-
|150 || play music right-to-left languages
|-
|151 .. 152 || shade / unshade
|-
|153 || debug
|-
|154 .. 157 || vehicle profit icons
|-
|158 || unread news
|-
|159 || exclusive transport rights
|-
|160 || autoreplace protection
|-
|161 || autoreplace defined
|-
|162 .. 165 || Town happiness indicator: N/A, appalling, mediocre and good
|}

=== num-sprites ===

The number of sprites that follow.

Since TTDPatch 2.0.1 alpha 49, this value is an extended byte.

Note that it is not generally an error to provide more sprites than required, but this does expend sprite slots unnecessarily.

=== offset ===

The offset in the Action 5 assignable block of sprites. This term is only read when bit 7 of the type has been set. It can be used to only replace a subset of sprites from a set.

'''Note:''' When creating a TTDPatch compatible grf, you have to skip the OpenTTD specific Action 05's using an Action 09 rather than an Action 07. Using the latter will result in an error on your Action 05 when using the grf in TTDPatch.

'''Note:''' NFORenum distinguishes Action5 with no offset and Action5 with offset 0. While they have technically the same effect, NFORenum assumes an Action5 with no offset has the intention to replace all sprites and checks the number of sprites accordingly. An Action5 with offset is considered to only replace a subset of the sprites, so the sprites are not checked for completeness.

== Example ==

<pre>
// Replace the piers for the aqueduct
1457 * 3 05 12 02 06 // action5, type 12, 2 sprites, at offset 6 into that type
9 sprites/png/terrain/waterfeatures.png 546 8 09 23 33 -26 0
10 sprites/png/terrain/waterfeatures.png 594 8 09 23 33 -5 0
</pre>

VariationalAction2

2012-09-28T20:33:06Z

Yexo: /* Type */ Airports don't have a parent scope yet

==Introduction==

To support changes in graphics based on other factors than just the load states, you use a VarAction2. This provides a sophisticated way of deciding what graphics to use.

A VarAction2 can be used like any other action 2, but it provides an additional step in-between: instead of defining the action 1 sets right away, it instead specifies a list of additional action 2 entry, one of which is used depending on the kind of variation that is defined. These action 2 entries that are referred can in turn be variational or random (to provide chains of decisions), or they can be the final element, that is a regular action 2 which contains definitions of action 1 sets, or a callback result.

== Format ==

The data looks as follows:

<Sprite-number> * <Length> 02 <feature> <set-id> <type> <variable> <varadjust> <nvar> (<set-id> <low-range> <high-range>){n} <default>

{| |-
!'''Element'''!![[GRFActionsDetailed|'''Size''']]!!'''Description'''
|-
|<Sprite-number>||dec||A sequential sprite number
|-
|<length>||dec||The total number of bytes used in this action.
|-
|02||B||Defines action 02
|-
|<feature>||B||For what type of vehicle/station should this definition be used?
|-
|<set-id>||B||The ID of this action 2 (used like a cargo ID)
|-
|<type>||B||Type of VarAction2, see below
|-
|<variable>||B||Which variable we base the decision on
|-
|<varadjust>||V||How to manipulate the value before deciding.
|-
|<nvar>||B||Number of different ranges of the value (not counting the default)
|-
|<set-id>||W||Action 2 set-id to use for the following range.
|-
|<low-range>||B/W/D||Minimum (inclusive) of the range for which to use the above set-id
|-
|<high-range>||B/W/D||Maximum (inclusive) of the range
|-
|<default>||W||Action 2 set-id to use if no range matches
|}

You repeat the sequence of <set-id> <low-range> <high-range> as often as <nvar> specifies.

<low-range> and <high-range> have a size of B, W, or D, depending on <type>. See that entry for more information.

== 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||[[VariationalAction2/Vehicles | Trains]]
|-
|01||[[VariationalAction2/Vehicles | Road Vehicles]]
|-
|02||[[VariationalAction2/Vehicles | Ships]]
|-
|03||[[VariationalAction2/Vehicles | Aircraft]]
|-
|04||[[VariationalAction2/Stations | Stations]]
|-
|05||[[VariationalAction2/Canals | Canals/Rivers]]
|-
|06||[[VariationalAction2/Bridges | Bridges]]
|-
|07||[[VariationalAction2/Houses | Houses]]
|-
|09||[[VariationalAction2/Industry Tiles | Industry Tiles]]
|-
|0A||[[VariationalAction2/Industries | Industries]]
|-
|0B||Cargos (no feature specific variables)
|-
|0C||Sound Effects (no feature specific variables)
|-
|0D||[[VariationalAction2/Airports | Airports]]
|-
|0E||[[VariationalAction2/Signals | Signals]]
|-
|0F||[[VariationalAction2/Objects | Objects]]
|-
|10||[[VariationalAction2/Railtypes | Railtypes]]
|-
|11||[[VariationalAction2/Airport Tiles | Airport Tiles]]
|-
|12||[[VariationalAction2/Towns | Towns]]
|}

=== Set-ID ===

This defines the number of this action 2.  The ID can then be used as target in an action 3 or another variational/random action 2.

=== Type ===

{| |-
! !! B Access lowest byte !! {{ottdp|0.6|2.5}} W Access lowest word !! {{ottdp|0.6|2.5}} D Access lowest doubleword
|-
!align="left"| Access general variable or variable of the primary object
|align="center"| 81
|align="center"| 85
|align="center"| 89
|-
!align="left"| Access variable of "related" object
|align="center"| 82
|align="center"| 86
|align="center"| 8A
|}

The access type specifies both the size of the variable access, and selects between general variables and the object's innate variables, or variables of a specific "related" object.

{|- |
!colspan="2"|[[Features|Feature]]!!Related object
|-
|00-03||[[VariationalAction2/Vehicles | Vehicles]]||First [[VariationalAction2/Vehicles | vehicle]] of consist
|-
|04||[[VariationalAction2/Stations | Stations]]||[[VariationalAction2/Towns | Town]] to which station belongs
|-
|05||[[VariationalAction2/Canals | Canals/Rivers]]||N/A
|-
|06||[[VariationalAction2/Bridges | Bridges]]||[[VariationalAction2/Towns | Town]] of bridge
|-
|07||[[VariationalAction2/Houses | Houses]]||[[VariationalAction2/Towns | Town]] of house
|-
|09||[[VariationalAction2/Industry Tiles | Industry Tiles]]||[[VariationalAction2/Industries | Industry]] containing tile
|-
|0A||[[VariationalAction2/Industries | Industries]]||[[VariationalAction2/Towns | Town]] of industry
|-
|0B||Cargos||N/A
|-
|0C||Sound Effects||N/A
|-
|0D||[[VariationalAction2/Airports | Airports]]||N/A
|-
|0E||[[VariationalAction2/Signals | Signals]]||N/A
|-
|0F||[[VariationalAction2/Objects | Objects]]||[[VariationalAction2/Towns | Town]] of object
|-
|10||[[VariationalAction2/Railtypes | Railtypes]]||N/A
|-
|11||[[VariationalAction2/Airport Tiles | Airport Tiles]]||N/A
|-
|12||[[VariationalAction2/Towns | Towns]]||N/A
|}

Every variable specifies a size for it. Not every variable is a doubleword.
If the accessed variable is smaller than the size given here, the extra bits may contain junk, and should be <and-masked> out.

=== Variable ===

Variational Action 2 allows accessing these variables:

{| |-
!'''Number'''!![[GRFActionsDetailed|'''Size''']]!!Version!!'''Meaning'''
|-
|00-3F|| || ||See [[GlobalVariables| global variables page]].
|-
|40+x||D|| ||specially calculated feature-specific variable, see following feature-specific pages
|-
|5F||D||{{ottdp|0.7|2.6|ttdprev=r1928}}||Feature-specific random data: triggers in low byte, bits in other three bytes. Bits of the variable not associated with random or trigger bits are reserved.
|-
|60+x||D|| ||similar to 40+x variables, but the variable number must be followed by a byte, which will be given to the variable handler as parameter.
|-
|7B||-||{{ottdp|1.1|2.6|ottdrev=r21604|ttdprev=r2359}}||A special 60+x variable to be used in Advanced Variational Action 2. It allows to evaluate any other 60+x variable using a non-constant parameter from a register. The parameter of variable 7B specifies another 60+x variable which is evaluated. The parameter for that variable is read from the accumulator ('val1'), i.e. the result from the preceding operations of the same Advanced Variational Action 2. Hence variable 7B may not be the first variable used in the calculation. Variable 7B itself and 7E (procedure call) are not allowed to be used as parameter for variable 7B.

{{ottdp|1.2|no|ottdrev=r23138}} Since OpenTTD r23138 you can use this to pass 32 bit parameters to 60+x variables. Currently this is only useful for a few variables, e.g. vehicle variable 60. For most variables the higher bits of the parameter are considered reserved. So, make sure to mask the higher bits in the preceding calculations.
|-
|7C||D||{{ottdp|0.6|2.6|ttdprev=r1315}}||A special 60+x variable used to access values stored in the registers of [[Storages#Persistent storage|persistent storage]].
|-
|7D||D||{{ottdp|0.6|2.6|ttdprev=r1246}}||A special 60+x variable used to access values stored in the registers of [[Storages#Temporary storage|temporary storage]]. Available in the purchase list.
|-
|7E||D||{{ottdp|0.6|2.5}}||A special 60+x variable indicating a [[VarAction2Advanced#Using procedures|procedure call]]. Available in the purchase list.
|-
|7F||D||{{ottdp|0.6|2.5}}||A special 60+x variable that reads GRF parameter whose number is given by the 60+x parameter. Available in the purchase list.
|-
|80+x|| || ||Feature-specific variable, see following feature-specific pages. While most of these variables actually refer to raw memory locations of original TTD structures, you cannot rely on that. Some variables were added later, some were moved or replaced. Only the variables listed in the specs are somewhat set to not be changed in the future.
|}

For all features, the 80+x variables are offsets into the corresponding structure in TTD's game data.  The 40+x and 60+x variables are special variables that are computed on-the-fly, and aren't actually stored anywhere in memory, unless stated otherwise. Therefore they should be used as little as necessary so as not to slow down the game too much with the calculation of these variables (which can be called thousands of times per second, whenever any vehicle moves).

When displaying a vehicle (etc.) in the purchase list, the game will show those variations based on external variables (dates etc.) correctly, but variations based on vehicle variables (variables 40+x, 60+x and 80+x) will always show the first (not the default) cargo-ID unless otherwise specified for the given variable. If you do a calculation, the first cargo-ID will be selected if any of the needed variables is inaccessible.

The lists of 80+x variables on the following pages are not exhaustive; only the useful variables are listed there. For a full list check the definition of corresponding structures in TTD. Marcin Grzegorczyk has a pretty good list of the structure definitions on his [http://marcin.ttdpatch.net/sv1codec/TTD-locations.html savegame internals page].

=== varadjust ===

Adjust variable to a more useful range. It has the following format:

<pre> <shift-num> <and-mask> <nowiki>[<add-val> <divide-val>/<modulo-val>]</nowiki></pre>

{| |-
!'''Element'''!![[GRFActionsDetailed|'''Size''']]!!'''Description'''
|-
|shift-num||B||value to right-shift the variable, and some special bits. See below.
|-
|and-mask||B/W/D||value with which to AND the variable after shifting. Return this value if neither bit 6 nor bit 7 of shift-num are set.
|-
|add-val||B/W/D||value to add to the variable after ANDing. Only present if bits 6 or 7 are set in shift-num.
|-
|divide-val||B/W/D||return the sum divided by this value. Only present if bit 6 is set in shift-num.
|-
|modulo-val||B/W/D||return the sum modulo (remainder of division by) this value. Only present if bit 7 is set in shift-num.
|}

<shift-num> is a partial bit-mask; its bits have the following meanings:

{| |-
!Bit(s)!!Value!!Version!!Meaning
|-
|0..4||0..1F||{{ottdp|0.6|2.0}}||number of bits to right shift <variable>
|-
|5||20||{{ottdp|0.6|2.5}}||This is an [[VarAction2Advanced|advanced VarAction2]]
|-
|6||40||{{ottdp|0.6|2.5}}||This is a shift-and-add-divide adjustment.
|-
|7||80||{{ottdp|0.6|2.5}}||This is a shift-and-add-modulo adjustment.
|}

Bits 6 and 7 may not both be set. If neither are set, this varadjust is a shift-and adjustment.

Note that for the add and divide operations, both the variable and the divisor are taken to be signed numbers. This means that if the high bit is set, the number is taken to be negative, so you may need to mask out the most significant bit to do an unsigned division.

=== nvar ===

Here you set how many different ranges to check for. If the value of the variable, after the above manipulations, is not within one of these ranges, the default will be used.  When displayed in the purchase window, the game will always show the first range if the variable is of the 40+x or 80+x type (because the variable is undefined since the vehicle doesn't exist yet).

{{ottdp|0.6|2.5|ttdprev=2.0.1 alpha 57}} Since TTDPatch 2.0.1 alpha 57, nvar=0 is a special case. Instead of using ranges, nvar=0 means that the result of an [[VarAction2Advanced|advanced]] calculation (or, if no calculation is performed, the adjusted variable value itself) is returned as callback result, with bit 15 set.  This is useful for those callbacks where many different return values are possible and it is easier to calculate them than list them in ranges.  The default value must still be specified, and will be used in case the variable(s) used are not available.

=== sets and ranges ===

For each of the ranges to check, you give the set-id as a '''WORD''' value (i.e. with a 00 following, e.g. set-id 5 becomes 05 00, or - in case of a callback result - by setting the high bit, e.g. 05 80), followed by the low and high limits of this range.  The first range that matches will be used.

The various \b, \w, and \d escape sequences can be useful for <min-range> and <max-range>. See [[GRFActionsDetailed#Byte order|the discussion of escape sequences]] for further information.

=== default ===

The set-id to use if none of the ranges matches.

=Example=
<pre>
-1 * 15 02 05 03 81 // Action2, Feature 05 (canals), action2ID 03, 1-byte variable
81 00 04 // variable 81 (terrain type), shift 00, mask 0x04 (=bit for "on or above snowline")
01 // check one range
02 00 04 04 // snowy tile: link to action2ID 02
01 00 // default: link to action2ID 01

</pre>

NML:Builtin functions

2012-09-23T11:00:51Z

Yexo: Update list of builtin functions

{{NMLNavExpressions}}

Available builtin functions are

{| class="t"
! Function
! Description
|-
| min(''v1'', ''v2'')
| Return the smallest value
|-
| max(''v1'', ''v2'')
| Return the biggest value
|-
| date(''year'', ''month'', ''day'')
| If all values are constants, returns the number of days since year 0. If the year is a variable, the month and day should be 1.
|-
| day_of_year(''month'', ''day'')
| Return the day of the year since January 1st. Both values must be compile-time constants.
|-
| bitmask(''bitpos1'', ...)
| Compose an integer by switching the bits at the given positions on.
|-
| STORE_TEMP(''value'', ''address'')
| Store value in temporary storage
|-
| STORE_PERM(''value'', ''address'')
| Store value in permanent storage (industries, airports, towns only). Note that accessing permanent town registers thrashes the contents of temporary register 0x100.
|-
| LOAD_TEMP(''address'')
| Get value from temporary storage
|-
| LOAD_PERM(''address [, grfid]'')
| Get value from permanent storage (industries, airports, towns only). For towns only, specifying a grfid (4-byte string, optional) allows reading the storage of other grfs. Note that accessing permanent town registers thrashes the contents of temporary register 0x100.
|-
| hasbit(''value'', ''bit_num'')
| Test whether a bit in a value is on
|-
| version_openttd(''major'', ''minor'', ''revision''[, ''build''])
| Return the constant representing an OpenTTD version
|-
| cargotype_available(''cargotype'')
| Check if a certain cargo type is available in this game. ''cargotype'' must be a literal string of length 4.
|-
| railtype_available(''railtype'')
| Check if a railtype is available in this game. ''railtype'' must be a literal string of length 4.
|-
| grf_current_status(''grfid[, mask]'')
| 1 if the given GRF is currently active 0, otherwise. If ''mask'' is set, only the bits set in the mask will be tested. Both parameters must be a literal string of length 4.
|-
| grf_future_status(''grfid[, mask]'')
| Same as above, but tests whether the grf will become active instead of whether it's currently active.
|-
| grf_order_behind(''grfid[, mask]'')
| Same as above, but tests whether current grf will become active in the order behind the referenced grf.
|-
| visual_effect_and_powered(''effect'', ''offset'', ''powered''
| Helper function for the train property visual_effect_and_powered and the VEH_CB_VISUAL_EFFECT_AND_POWERED callback.
|-
| str2number(''4-byte long string'')
| Interpret the given string as a dword and return the value as integer.
|-
| cargotype(''4-byte long string'')
| Return the index of the given cargo type in the cargo translation table.
|-
| railtype(''4-byte long string'')
| Return the index of the given railtype in the railtype translation table.
|-
| reserve_sprites(''number of sprites'')
|
Reserve a number of sprites in the TTD sprite range. This is needed if you want to use your own recolour sprites. Example:
<pre style="color:blue">
param[10] = reserve_sprites(1);
replace(param[10]) {
recolour_sprite {
// your colour remap.
}
}
spritelayout xyz {
building {
...
recolour: param[10];
}
}
</pre>
|-
| int(''v1'')
| Converts v1 to an int. This is done by cutting off everything after the decimal point.
|-
| abs(''v1'')
| Return the absolute value of v1.
|-
| acos / asin / atan / cos / sin / tan
| Standard trigonometric functions.
|-
| CMP(''param1, param2'')
| Compares param1 and param2 (considering them as signed values). Returns CMP_LESS if param1 is less than param2, CMP_EQUAL if they are equal and CMP_GREATER if param1 is greater than param2.
|-
| UCMP(''param1, param2'')
| Compares param1 and param2 (considering them as unsigned values). Returns CMP_LESS if param1 is less than param2, CMP_EQUAL if they are equal and CMP_GREATER if param1 is greater than param2.
|-
| rotate(''value, amount'')
| Rotates ''value'' to the right ''amount'' steps. This is always a 32 bits rotation.
|-
| sound(''soundfile[, volume]'')
| Import sound from .wav-file ''soundfile'' into the grf file and return its numeric ID. Including a file multiple times will not cause it to be duplicated. Loaded sound files must be 8-bit mono sound files in WAV format, PCM encoding. There are two allowed frequencies: 11025 Hz and 22050 Hz. ''volume'' is in the [0, 100] range, the default value (if not set) is 100.
|-
| import_sound(''grfid, id[, volume]'')
| Import sound from a different grf file. ''grfid'' refers to the grf-file to import the sound from. ''id'' is the zero-based internal ID of the sound within the other grf-file. ''volume'' is in the [0, 100] range, the default value (if not set) is 100.
|-
| relative_coord(''x, y'')
| Returns the coordinates in ''0xYYXX'' format. x and y must be in the [0, 255] range.
|-
| num_corners_raised(''slope'')
|
Returns the number of corners raised in a slope. Return value is 0 .. 3 for normal slopes and 4 for steep ones. See also [[NML:List of tile slopes|here]] for more information about slopes. Using this on values that are not slopes results in undefined behaviour.
|-
| slope_to_sprite_offset(''slope'')
|
Returns the sprite offset corresponding to a given slope. Return value is in range 0 .. 18. See also [[NML:List of tile slopes|here]] for more information about slopes. The section on [[NML:Spritelayout|spritelayouts]] contains some more information one possible uses, as well as an example. Using this on values that are not slopes results in undefined behaviour.
|-
| palette_1cc(''colour'')
|
Returns the 1cc palette for the given company colour, see [[List default colour translation palettes#Company colour helper functions|here]] for more info.
|-
| palette_2cc(''colour1'', ''colour2'')
|
Returns the 2cc palette for the given first and second company colour, see [[List default colour translation palettes#Company colour helper functions|here]] for more info.
|-
| vehicle_curv_info(''prev_cur'', ''cur_next'')
| Returns the curvature state of a vehicle, given the direction differences between the (previous-current) and (current-next) vehicle pairs. For use with the vehicle variable <code style="color:darkgreen">curv_info</code>
|-
| format_string(''format'', args)
| Use the python string formatting functions to create a literal string. Keep in mind that the output is a literal string which cannot be used by string(). This function can however be used to create filenames.
|}

NML:Railtypes

2012-09-14T20:33:23Z

Yexo: Document town_zone var

{{NMLNavPropVarCB}}

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

==Railtype IDs==
Railtype IDs are limited to 16 in total. NewGRF-local IDs may freely be chosen, but must be in the 0..15 range. If other railtype GRFs are loaded, it may be that there are not enough railtype slots available. To prevent your entire NewGRF from being deactivated with the 'Attempt to use invalid ID'-error, you can use the following code:

if (railtype_available("LABL") || loading_stage == LOADING_STAGE_RESERVE)
... item definition ...
} else if (loading_stage == LOADING_STAGE_ACTIVATE) {
... warning / error ...
}
The warning / error is optional, but can be used to inform the user about the missing railtypes.

==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
|-
| town_zone
| [[NML:List of town zones|town zone]]
| Town zone of the tile. (Only available for level crossings and depots.)
|}

==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. 
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:Language files

2012-09-12T19:02:59Z

Yexo: /* LanguageIDs */

{{NMLNavNoSubpages}}
== Introduction ==
Language files are usually found in the <code style="color:darkgreen">lang</code> sub-folder of the project, but the place NML looks for the language files can be changed via command line parameter to any directory desired:

nmlc -l path/to/lang-dir path/to/nml-source-file.nml
nmlc --lang-dir=path/to/lang-dir path/to/nml-source-file.nml

Language files MUST have the extension <code style="color:darkgreen">.lng</code> The language files themselves follow a certain structure:

##grflangid <number>
<string-name> :<text>
<string-name> :<text>
...

where the first line must give the language code for the language this file describes (see below). The following lines each describe a string. The translated string follows immediately the colon. An NML project has exactly one fallback language, by default this is english.lng. You can change this with the command line parameter --default-lang. Example for a valid language file:

<pre class=example>
##grflangid 0x01
STR_GRF_NAME :{TITLE} 0.1.0 - {VERSION}
STR_GRF_DESCRIPTION :{TITLE} contains pimped ground tiles.
STR_NAME_MYVEHICLE :General Robotics Anti-Grav UFO Mark X
</pre>

== String codes ==

Strings may contain a number of special string codes which control how the string is being printed or which values to insert into the string. Custom replacements can be stored in the plain text file <code>custom_tags.txt</code> (for example a newgrf version which is written by your build script). In the case above the <code>custom_tags.txt</code> could, for example read

<pre class=example>
VERSION :alpha-r88
TITLE :Example NewGRF
</pre>

Additionally to custom-defined tags, NML comes with a number of default tags:
{|
!width="150pt"|Tag
!width="600pt"|Meaning
!Example
|-
| ||empty tag, written as {} is used to create a newline
|-
|NBSP || non-breaking space
|-
|{ || Display a left curly bracket. You write this as {{}. If you'd include it without surrounding it by { and } it'd be seen as the start of a tag and the rest of the string would be read as name of the tag.
|-
|COPYRIGHT || copyright symbol || ©
|-
|TRAIN || display train symbol
|-
|LORRY || display lorry symbol
|-
|BUS || display bus symbol
|-
|PLANE || display plane symbol
|-
|SHIP || display ship symbol
|-
|TINYFONT || switch to small font
|-
|BIGFONT || switch to big font
|-
|BLUE || switch to blue text
|-
|SILVER || switch to silver text
|-
|GOLD || switch to golden text
|-
|RED || switch to red text
|-
|PURPLE || switch to purple text
|-
|LTBROWN || switch to light brown text
|-
|ORANGE || switch to orange text
|-
|GREEN || switch to green text
|-
|YELLOW || switch to yellow text
|-
|DKGREEN || switch to dark green text
|-
|CREAM || switch to cream-coloured text
|-
|BROWN || switch to brown text
|-
|WHITE || switch to white text
|-
|LTBLUE || switch to light blue text
|-
|GRAY || switch to gray text
|-
|DKBLUE || switch to dark blue text
|-
|BLACK || switch to black text
|}
== String parameters ==
The above tags can be used in almost all strings. There are also a number of tags that need an argument they'll read from the textstack. The textstack is only available for certain callbacks an properties.
{|
!width="150pt"|Tag
!width="600pt"|Meaning
!Size (number of bytes read from stack)
!Example
|-
|COMMA || signed number with decimal separator between 1000's. || 4
|-
|SIGNED_WORD || signed number with decimal separator between 1000's. || 2
|-
|UNSIGNED_WORD || unsigned number with decimal separator between 1000's. || 2
|-
|CURRENCY || money in proper currency units || 4 || 24,492 €
|-
|VELOCITY || velocity in proper units || 2 || 35 km/h
|-
|VOLUME || volume in proper units || 2 || 29,000 litres
|-
|VOLUME_SHORT || volume in proper units in short form || 2 || 29,000l
|-
|POWER || power in proper units || 2 || 2,030 kW
|-
|WEIGHT || weight in proper units || 2 || 5 tonnes
|-
|WEIGHT_SHORT || weight in proper units in short form || 2 || 5t
|-
|HEX || hexadecimal presentation || 4 || F0 3D D4 33
|-
|STRING || include other string || 2
|-
|DATE1920_LONG || days since 1920 as long date || 2 || 12 August 1935
|-
|DATE1920_SHORT|| days since 1920 as short date || 2 || 12 Aug 1935
|-
|DATE_LONG || days since 0 as long date || 4 || 12 August 1610
|-
|DATE_SHORT || days since 0 as short date || 4 || 12 Aug 3049
|-
|POP_WORD || Remove 2 bytes from the top of the stack || 2
|-
|STATION || Station name of station with given ID || 2
|}

In case you don't want to use the first 2 (or 4) bytes from the stack but rather another variable, you can prefix the tag name with the number, like {1:COMMA} to use the second (indexing starts at 0) argument from the stack. You can also use this in translations that require a different order, for example (in english.lng):

STR_SOME_STRING :{COMMA} items cost {CURRENCY}

And the same string in dutch.lng:

STR_SOME_STRING ;{1:CURRENCY} is de prijs van {0:COMMA} items.

The string parameters itself are assigned in units of dwords (4 bytes), starting with temporary storage 256, up to 259 or 261. Thus if you use parameters which are not of dword size (e.g. strings or word-sized numbers), you have to construct the text stack via bit arithmetic:
<pre class=example>
switch(FEAT_INDUSTRIES, SELF, extra_text_switch, [
STORE_TEMP(
( (LOAD_PERM(var_supply_efficiency_factor) == 1) * string(STR_EXTRA_PRIMARY_EFFICIENT1) ) +
( (LOAD_PERM(var_supply_efficiency_factor) == 2) * string(STR_EXTRA_PRIMARY_EFFICIENT2) ) +
( (LOAD_PERM(var_supply_efficiency_factor) == 3) * string(STR_EXTRA_PRIMARY_EFFICIENT3) ) +
( (LOAD_PERM(var_supply_efficiency_factor) == 4) * string(STR_EXTRA_PRIMARY_EFFICIENT4) ) |
LOAD_PERM(var_supply_requirement) << 16,
256
),
return string(STR_EXTRA_PRIMARY);
}
</pre>

for a language file which reads
<pre class=example>
STR_EXTRA_PRIMARY_EFFICIENT1 :{YELLOW}very efficient{BLACK}ly
STR_EXTRA_PRIMARY_EFFICIENT2 :{YELLOW}efficient{BLACK}ly
STR_EXTRA_PRIMARY_EFFICIENT3 :in a {YELLOW}normal{BLACK} way
STR_EXTRA_PRIMARY_EFFICIENT4 :{YELLOW}wasteful{BLACK}ly
STR_EXTRA_PRIMARY :{BLACK}This industry needs {YELLOW}supplies{BLACK}.{}They use them {STRING}{}{}Monthly demand: {YELLOW}{UNSIGNED_WORD} crate{P "" s} of engineering supplies{BLACK}.
</pre>

== Defining cases ==
Similar to OpenTTD's language files, NML can also make use of cases, genders and plural forms. In order to utilize them, they have to be defined in the language file's header and have to match the definition as used in OpenTTD's language files:
<pre>
##case pragma

STR_NAME :Utas
STR_NAME.pragma :utast
</pre>

e.g. for Hungarian you'd have
<pre class=example>
##case t ba

STR_CARGO_PLURAL_PASSENGERS :Utas
STR_CARGO_PLURAL_PASSENGERS.t :utast
</pre>

In case the name of a case changes in the OpenTTD language file, your language file will have to follow that change. To keep compatible with older OpenTTD versions you can use the ##map_case pragma, like this:
<pre class=example>##map_case t t_old</pre>

== Defining genders ==
Genders just like cases are defined in the header of the language file and have to match the definition as found within OpenTTD's language files. The gender of a word or expression is declared within the string's text itself by a tag of the form <code>{G=gendername}</code>:
<pre>
##gender pragma

STR_NAME :{G=gendername}String which requires gender 'gendername'
</pre>
where the string with the defined gender then will trigger the correct usage in a string which includes it and which has to take provisions to show the proper gender:
<pre>
STR_OTHER :Some text {G gender1 gender2 ...} {STRING}
</pre>

for example in German
<pre class=example>
##gender m w n p

STR_CARGO_NAME_BAUXITE :{G=n}Bauxit
</pre>
which then will be used with the correct gender by a string which includes it:
<pre class=example>
STR_NEWS_STATION_NO_LONGER_ACCEPTS_CARGO :{WHITE}{STATION} akzeptiert kein{G "en" "e" "" "e"} {STRING} mehr.
</pre>

In case the name of a gender changes in the OpenTTD language file, your language file will have to follow that change. To keep compatible with older OpenTTD versions you can use the ##map_gender pragma, like this:
<pre class=example>##gender m f
##map_gender m male
##map_gender f female</pre>

== LanguageIDs ==

Valid language IDs are listed in the table below. The cases, genders and the type of plural form is only given as reference. Authorative are the definitions in OpenTTD's language file for each language.

{| class="t"
! ID
! language
! cases
! genders
! plurals
|-
| 00
| English (US)
|
|
|
|-
| 01
| English (GB)
|
|
|
|-
| 02
| German
|
| m w n p
|
|-
| 03
| French
|
| m m2 f
| 2
|-
| 04
| Spanish
|
| m f
|
|-
| 05
| Esperanto
|
| n
|
|-
| 06
| Ido
|
|
|
|-
| 07
| Russian
| m f n p nom gen dat acc abl pre
| m f n p
| 6
|-
| 08
| Irish
|
|
| 4
|-
| 09
| Maltese
|
|
| 12
|-
| 0A
| Tamil
|
|
|
|-
| 0B
| Chuvash
|
|
|
|-
| 0C
| Chinese (Traditional)
|
|
| 1
|-
| 0D
| Serbian
| nom big gen dat aku vok lok ins
| muški ženski srednji
| 6
|-
| 0E
| Norwegian (Nynorsk)
| small
| masculine feminine neuter
|
|-
| 0F
| Welsh
|
|
|
|-
| 10
| Belarusian
| m f n p nom gen dat acc abl pre
| m f n p
| 6
|-
| 11
| Marathi
|
|
|
|-
| 12
| Faroese
|
| m f n
|
|-
| 14
| Arabic (Egypt)
|
|
| 1
|-
| 15
| Czech
| nom gen dat acc voc loc ins big small
| m f n map mnp fp np
| 10
|-
| 16
| Slovak
| g
| m z s
| 10
|-
| 18
| Bulgarian
| m f n p
| m f n p
|
|-
| 1B
| Afrikaans
|
| male
|
|-
| 1E
| Greek
| subs date geniki
| m f n
| 2
|-
| 1F
| Dutch
|
|
|
|-
| 21
| Basque
|
|
|
|-
| 22
| Catalan
|
| Masculin Femenin
|
|-
| 23
| Luxembourgish
|
|
|
|-
| 24
| Hungarian
| t ba
|
| 2
|-
| 26
| Macedonian
|
|
|
|-
| 27
| Italian
| ms mp fs fp
| m ma f
|
|-
| 28
| Romanian
|
|
|
|-
| 29
| Icelandic
|
| karlkyn kvenkyn hvorugkyn
|
|-
| 2A
| Latvian
| kas
| m f
| 3
|-
| 2B
| Lithuanian
| kas ko kam ka kuo kur kreip
| vyr mot
| 5
|-
| 2C
| Slovenian
| r d t
|
| 8
|-
| 2D
| Danish
|
|
|
|-
| 2E
| Swedish
|
|
|
|-
| 2F
| Norwegian (Bokmal)
| small
| masculine feminine neuter
|
|-
| 30
| Polish
| d c b n m w
| m f n
| 7
|-
| 31
| Galician
|
| m f n
|
|-
| 32
| Frisian
|
|
|
|-
| 33
| Ukrainian
| r d z
| m f s mn
| 6
|-
| 34
| Estonian
| g in sü
|
|
|-
| 35
| Finnish
|
|
|
|-
| 36
| Portuguese
|
| n m f mp fp
|
|-
| 37
| Brazilian Portuguese
|
| m f
| 2
|-
| 38
| Croatian
| nom gen dat aku vok lok ins
| male female middle
| 6
|-
| 39
| Japanese
|
|
| 1
|-
| 3A
| Korean
|
| m f
| 11
|-
| 3C
| Malay
|
|
|
|-
| 3D
| English (AU)
|
|
|
|-
| 3E
| Turkish
| tamlanan
|
| 1
|-
| 42
| Thai
|
|
| 1
|-
| 54
| Vietnamese
|
|
| 1
|-
| 56
| Chinese (Simplified)
|
|
| 1
|-
| 5A
| Indonesian
|
|
| 1
|-
| 5C
| Urdu
|
| m f
|
|-
| 61
| Hebrew
| singular plural gen
| m f
|
|-
| 62
| Persian
|
|
|
|}

In case a language is not in this list, check the [[Action4#language IDs|master language list]] (for GRFv7) in the NewGRF Specs. This master list is always leading. NFO language ID 7F has no meaning in NML (set --default-lang instead) and setting bit 8 will break your language file.

NML:Language files

2012-09-12T19:00:33Z

Yexo: Document ##map_gender and ##map_case

NML:Language files

2012-05-13T14:44:54Z

Yexo: /* LanguageIDs */

{{NMLNavNoSubpages}}
== Introduction ==
Language files are usually found in the <code style="color:darkgreen">lang</code> sub-folder of the project, but the place NML looks for the language files can be changed via command line parameter to any directory desired:

nmlc -l path/to/lang-dir path/to/nml-source-file.nml
nmlc --lang-dir=path/to/lang-dir path/to/nml-source-file.nml

Language files MUST have the extension <code style="color:darkgreen">.lng</code> The language files themselves follow a certain structure:

##grflangid <number>
<string-name> :<text>
<string-name> :<text>
...

where the first line must give the language code for the language this file describes (see below). The following lines each describe a string. The translated string follows immediately the colon. An NML project has exactly one fallback language, by default this is english.lng. You can change this with the command line parameter --default-lang. Example for a valid language file:

<pre class=example>
##grflangid 0x01
STR_GRF_NAME :{TITLE} 0.1.0 - {VERSION}
STR_GRF_DESCRIPTION :{TITLE} contains pimped ground tiles.
STR_NAME_MYVEHICLE :General Robotics Anti-Grav UFO Mark X
</pre>

== String codes ==

Strings may contain a number of special string codes which control how the string is being printed or which values to insert into the string. Custom replacements can be stored in the plain text file <code>custom_tags.txt</code> (for example a newgrf version which is written by your build script). In the case above the <code>custom_tags.txt</code> could, for example read

<pre class=example>
VERSION :alpha-r88
TITLE :Example NewGRF
</pre>

Additionally to custom-defined tags, NML comes with a number of default tags:
{|
!width="150pt"|Tag
!width="600pt"|Meaning
!Example
|-
| ||empty tag, written as {} is used to create a newline
|-
|NBSP || non-breaking space
|-
|{ || Display a left curly bracket. You write this as {{}. If you'd include it without surrounding it by { and } it'd be seen as the start of a tag and the rest of the string would be read as name of the tag.
|-
|COPYRIGHT || copyright symbol || ©
|-
|TRAIN || display train symbol
|-
|LORRY || display lorry symbol
|-
|BUS || display bus symbol
|-
|PLANE || display plane symbol
|-
|SHIP || display ship symbol
|-
|TINYFONT || switch to small font
|-
|BIGFONT || switch to big font
|-
|BLUE || switch to blue text
|-
|SILVER || switch to silver text
|-
|GOLD || switch to golden text
|-
|RED || switch to red text
|-
|PURPLE || switch to purple text
|-
|LTBROWN || switch to light brown text
|-
|ORANGE || switch to orange text
|-
|GREEN || switch to green text
|-
|YELLOW || switch to yellow text
|-
|DKGREEN || switch to dark green text
|-
|CREAM || switch to cream-coloured text
|-
|BROWN || switch to brown text
|-
|WHITE || switch to white text
|-
|LTBLUE || switch to light blue text
|-
|GRAY || switch to gray text
|-
|DKBLUE || switch to dark blue text
|-
|BLACK || switch to black text
|}
== String parameters ==
The above tags can be used in almost all strings. There are also a number of tags that need an argument they'll read from the textstack. The textstack is only available for certain callbacks an properties.
{|
!width="150pt"|Tag
!width="600pt"|Meaning
!Size (number of bytes read from stack)
!Example
|-
|COMMA || signed number with decimal separator between 1000's. || 4
|-
|SIGNED_WORD || signed number with decimal separator between 1000's. || 2
|-
|UNSIGNED_WORD || unsigned number with decimal separator between 1000's. || 2
|-
|CURRENCY || money in proper currency units || 4 || 24,492 €
|-
|VELOCITY || velocity in proper units || 2 || 35 km/h
|-
|VOLUME || volume in proper units || 2 || 29,000 litres
|-
|VOLUME_SHORT || volume in proper units in short form || 2 || 29,000l
|-
|POWER || power in proper units || 2 || 2,030 kW
|-
|WEIGHT || weight in proper units || 2 || 5 tonnes
|-
|WEIGHT_SHORT || weight in proper units in short form || 2 || 5t
|-
|HEX || hexadecimal presentation || 4 || F0 3D D4 33
|-
|STRING || include other string || 2
|-
|DATE1920_LONG || days since 1920 as long date || 2 || 12 August 1935
|-
|DATE1920_SHORT|| days since 1920 as short date || 2 || 12 Aug 1935
|-
|DATE_LONG || days since 0 as long date || 4 || 12 August 1610
|-
|DATE_SHORT || days since 0 as short date || 4 || 12 Aug 3049
|-
|POP_WORD || Remove 2 bytes from the top of the stack || 2
|-
|STATION || Station name of station with given ID || 2
|}

In case you don't want to use the first 2 (or 4) bytes from the stack but rather another variable, you can prefix the tag name with the number, like {1:COMMA} to use the second (indexing starts at 0) argument from the stack. You can also use this in translations that require a different order, for example (in english.lng):

STR_SOME_STRING :{COMMA} items cost {CURRENCY}

And the same string in dutch.lng:

STR_SOME_STRING ;{1:CURRENCY} is de prijs van {0:COMMA} items.

The string parameters itself are assigned in units of dwords (4 bytes), starting with temporary storage 256, up to 259 or 261. Thus if you use parameters which are not of dword size (e.g. strings or word-sized numbers), you have to construct the text stack via bit arithmetic:
<pre class=example>
switch(FEAT_INDUSTRIES, SELF, extra_text_switch, [
STORE_TEMP(
( (LOAD_PERM(var_supply_efficiency_factor) == 1) * string(STR_EXTRA_PRIMARY_EFFICIENT1) ) +
( (LOAD_PERM(var_supply_efficiency_factor) == 2) * string(STR_EXTRA_PRIMARY_EFFICIENT2) ) +
( (LOAD_PERM(var_supply_efficiency_factor) == 3) * string(STR_EXTRA_PRIMARY_EFFICIENT3) ) +
( (LOAD_PERM(var_supply_efficiency_factor) == 4) * string(STR_EXTRA_PRIMARY_EFFICIENT4) ) |
LOAD_PERM(var_supply_requirement) << 16,
256
),
return string(STR_EXTRA_PRIMARY);
}
</pre>

for a language file which reads
<pre class=example>
STR_EXTRA_PRIMARY_EFFICIENT1 :{YELLOW}very efficient{BLACK}ly
STR_EXTRA_PRIMARY_EFFICIENT2 :{YELLOW}efficient{BLACK}ly
STR_EXTRA_PRIMARY_EFFICIENT3 :in a {YELLOW}normal{BLACK} way
STR_EXTRA_PRIMARY_EFFICIENT4 :{YELLOW}wasteful{BLACK}ly
STR_EXTRA_PRIMARY :{BLACK}This industry needs {YELLOW}supplies{BLACK}.{}They use them {STRING}{}{}Monthly demand: {YELLOW}{UNSIGNED_WORD} crate{P "" s} of engineering supplies{BLACK}.
</pre>

== Defining cases ==
Similar to OpenTTD's language files, NML can also make use of cases, genders and plural forms. In order to utilize them, they have to be defined in the language file's header and have to match the definition as used in OpenTTD's language files:
<pre>
##case pragma

STR_NAME :Utas
STR_NAME.pragma :utast
</pre>

e.g. for Hungarian you'd have
<pre class=example>
##case t ba

STR_CARGO_PLURAL_PASSENGERS :Utas
STR_CARGO_PLURAL_PASSENGERS.t :utast
</pre>

== Defining genders ==
Genders just like cases are defined in the header of the language file and have to match the definition as found within OpenTTD's language files. The gender of a word or expression is declared within the string's text itself by a tag of the form <code>{G=gendername}</code>:
<pre>
##gender pragma

STR_NAME :{G=gendername}String which requires gender 'gendername'
</pre>
where the string with the defined gender then will trigger the correct usage in a string which includes it and which has to take provisions to show the proper gender:
<pre>
STR_OTHER :Some text {G gender1 gender2 ...} {STRING}
</pre>

for example in German
<pre class=example>
##gender m w n p

STR_CARGO_NAME_BAUXITE :{G=n}Bauxit
</pre>
which then will be used with the correct gender by a string which includes it:
<pre class=example>
STR_NEWS_STATION_NO_LONGER_ACCEPTS_CARGO :{WHITE}{STATION} akzeptiert kein{G "en" "e" "" "e"} {STRING} mehr.
</pre>

== LanguageIDs ==

Valid language IDs are listed in the table below. The cases, genders and the type of plural form is only given as reference. Authorative are the definitions in OpenTTD's language file for each language.

{| class="t"
! ID
! language
! cases
! genders
! plurals
|-
| 00
| English (US)
|
|
|
|-
| 01
| English (GB)
|
|
|
|-
| 02
| German
|
| m w n p
|
|-
| 03
| French
|
| m m2 f
| 2
|-
| 04
| Spanish
|
| m f
|
|-
| 05
| Esperanto
|
| n
|
|-
| 06
| Ido
|
|
|
|-
| 07
| Russian
| m f n p nom gen dat acc abl pre
| m f n p
| 6
|-
| 08
| Irish
|
|
| 4
|-
| 09
| Maltese
|
|
| 12
|-
| 0A
| Tamil
|
|
|
|-
| 0B
| Chuvash
|
|
|
|-
| 0C
| Chinese (Traditional)
|
|
| 1
|-
| 0D
| Serbian
| nom big gen dat aku vok lok ins
| muški ženski srednji
| 6
|-
| 0E
| Norwegian (Nynorsk)
| small
| masculine feminine neuter
|
|-
| 0F
| Welsh
|
|
|
|-
| 10
| Belarusian
| m f n p nom gen dat acc abl pre
| m f n p
| 6
|-
| 11
| Marathi
|
|
|
|-
| 12
| Faroese
|
| m f n
|
|-
| 14
| Arabic (Egypt)
|
|
| 1
|-
| 15
| Czech
| nom gen dat acc voc loc ins big small
| m f n map mnp fp np
| 10
|-
| 16
| Slovak
| g
| m z s
| 10
|-
| 18
| Bulgarian
| m f n p
| m f n p
|
|-
| 1B
| Afrikaans
|
| male
|
|-
| 1E
| Greek
| subs date geniki
| m f n
| 2
|-
| 1F
| Dutch
|
|
|
|-
| 21
| Basque
|
|
|
|-
| 22
| Catalan
|
| Masculin Femenin
|
|-
| 23
| Luxembourgish
|
|
|
|-
| 24
| Hungarian
| t ba
|
| 2
|-
| 26
| Macedonian
|
|
|
|-
| 27
| Italian
| ms mp fs fp
| m ma f
|
|-
| 28
| Romanian
|
|
|
|-
| 29
| Icelandic
|
| karlkyn kvenkyn hvorugkyn
|
|-
| 2A
| Latvian
| kas
| m f
| 3
|-
| 2B
| Lithuanian
| kas ko kam ka kuo kur kreip
| vyr mot
| 5
|-
| 2C
| Slovenian
| r d t
|
| 8
|-
| 2D
| Danish
|
|
|
|-
| 2E
| Swedish
|
|
|
|-
| 2F
| Norwegian (Bokmal)
| small
| masculine feminine neuter
|
|-
| 30
| Polish
| d c b n m w
| m f n
| 7
|-
| 31
| Galician
|
| m f n
|
|-
| 32
| Frisian
|
|
|
|-
| 33
| Ukrainian
| r d z
| m f s mn
| 6
|-
| 34
| Estonian
| g in sü
|
|
|-
| 35
| Finnish
|
|
|
|-
| 36
| Portuguese
|
| n m f mp fp
|
|-
| 37
| Brazilian Portuguese
|
| m f
| 2
|-
| 38
| Croatian
| nom gen dat aku vok lok ins
| male female middle
| 6
|-
| 39
| Japanese
|
|
| 1
|-
| 3A
| Korean
|
| m f
| 11
|-
| 3C
| Malay
|
|
|
|-
| 3D
| English (AU)
|
|
|
|-
| 3E
| Turkish
| tamlanan
|
| 1
|-
| 42
| Thai
|
|
| 1
|-
| 54
| Vietnamese
|
|
| 1
|-
| 56
| Chinese (Simplified)
|
|
| 1
|-
| 5A
| Indonesian
|
|
| 1
|-
| 5C
| Urdu
|
| m f
|
|-
| 61
| Hebrew
| singular plural gen
| m f
|
|-
| 62
| Persian
|
|
|
|}

In case a language is not in this list, check the [[Action4#language IDs|master language list]] (for GRFv7) in the NewGRF Specs. This master list is always leading. NFO language ID 7F has no meaning in NML (set --default-lang instead) and setting bit 16 will break your language file.

NML:Language files

2012-05-13T13:46:11Z

Yexo: fix type

{{NMLNavNoSubpages}}
== Introduction ==
Language files are usually found in the <code style="color:darkgreen">lang</code> sub-folder of the project, but the place NML looks for the language files can be changed via command line parameter to any directory desired:

nmlc -l path/to/lang-dir path/to/nml-source-file.nml
nmlc --lang-dir=path/to/lang-dir path/to/nml-source-file.nml

Language files MUST have the extension <code style="color:darkgreen">.lng</code> The language files themselves follow a certain structure:

##grflangid <number>
<string-name> :<text>
<string-name> :<text>
...

where the first line must give the language code for the language this file describes (see below). The following lines each describe a string. The translated string follows immediately the colon. An NML project has exactly one fallback language, by default this is english.lng. You can change this with the command line parameter --default-lang. Example for a valid language file:

<pre class=example>
##grflangid 0x01
STR_GRF_NAME :{TITLE} 0.1.0 - {VERSION}
STR_GRF_DESCRIPTION :{TITLE} contains pimped ground tiles.
STR_NAME_MYVEHICLE :General Robotics Anti-Grav UFO Mark X
</pre>

== String codes ==

Strings may contain a number of special string codes which control how the string is being printed or which values to insert into the string. Custom replacements can be stored in the plain text file <code>custom_tags.txt</code> (for example a newgrf version which is written by your build script). In the case above the <code>custom_tags.txt</code> could, for example read

<pre class=example>
VERSION :alpha-r88
TITLE :Example NewGRF
</pre>

Additionally to custom-defined tags, NML comes with a number of default tags:
{|
!width="150pt"|Tag
!width="600pt"|Meaning
!Example
|-
| ||empty tag, written as {} is used to create a newline
|-
|NBSP || non-breaking space
|-
|{ || Display a left curly bracket. You write this as {{}. If you'd include it without surrounding it by { and } it'd be seen as the start of a tag and the rest of the string would be read as name of the tag.
|-
|COPYRIGHT || copyright symbol || ©
|-
|TRAIN || display train symbol
|-
|LORRY || display lorry symbol
|-
|BUS || display bus symbol
|-
|PLANE || display plane symbol
|-
|SHIP || display ship symbol
|-
|TINYFONT || switch to small font
|-
|BIGFONT || switch to big font
|-
|BLUE || switch to blue text
|-
|SILVER || switch to silver text
|-
|GOLD || switch to golden text
|-
|RED || switch to red text
|-
|PURPLE || switch to purple text
|-
|LTBROWN || switch to light brown text
|-
|ORANGE || switch to orange text
|-
|GREEN || switch to green text
|-
|YELLOW || switch to yellow text
|-
|DKGREEN || switch to dark green text
|-
|CREAM || switch to cream-coloured text
|-
|BROWN || switch to brown text
|-
|WHITE || switch to white text
|-
|LTBLUE || switch to light blue text
|-
|GRAY || switch to gray text
|-
|DKBLUE || switch to dark blue text
|-
|BLACK || switch to black text
|}
== String parameters ==
The above tags can be used in almost all strings. There are also a number of tags that need an argument they'll read from the textstack. The textstack is only available for certain callbacks an properties.
{|
!width="150pt"|Tag
!width="600pt"|Meaning
!Size (number of bytes read from stack)
!Example
|-
|COMMA || signed number with decimal separator between 1000's. || 4
|-
|SIGNED_WORD || signed number with decimal separator between 1000's. || 2
|-
|UNSIGNED_WORD || unsigned number with decimal separator between 1000's. || 2
|-
|CURRENCY || money in proper currency units || 4 || 24,492 €
|-
|VELOCITY || velocity in proper units || 2 || 35 km/h
|-
|VOLUME || volume in proper units || 2 || 29,000 litres
|-
|VOLUME_SHORT || volume in proper units in short form || 2 || 29,000l
|-
|POWER || power in proper units || 2 || 2,030 kW
|-
|WEIGHT || weight in proper units || 2 || 5 tonnes
|-
|WEIGHT_SHORT || weight in proper units in short form || 2 || 5t
|-
|HEX || hexadecimal presentation || 4 || F0 3D D4 33
|-
|STRING || include other string || 2
|-
|DATE1920_LONG || days since 1920 as long date || 2 || 12 August 1935
|-
|DATE1920_SHORT|| days since 1920 as short date || 2 || 12 Aug 1935
|-
|DATE_LONG || days since 0 as long date || 4 || 12 August 1610
|-
|DATE_SHORT || days since 0 as short date || 4 || 12 Aug 3049
|-
|POP_WORD || Remove 2 bytes from the top of the stack || 2
|-
|STATION || Station name of station with given ID || 2
|}

In case you don't want to use the first 2 (or 4) bytes from the stack but rather another variable, you can prefix the tag name with the number, like {1:COMMA} to use the second (indexing starts at 0) argument from the stack. You can also use this in translations that require a different order, for example (in english.lng):

STR_SOME_STRING :{COMMA} items cost {CURRENCY}

And the same string in dutch.lng:

STR_SOME_STRING ;{1:CURRENCY} is de prijs van {0:COMMA} items.

The string parameters itself are assigned in units of dwords (4 bytes), starting with temporary storage 256, up to 259 or 261. Thus if you use parameters which are not of dword size (e.g. strings or word-sized numbers), you have to construct the text stack via bit arithmetic:
<pre class=example>
switch(FEAT_INDUSTRIES, SELF, extra_text_switch, [
STORE_TEMP(
( (LOAD_PERM(var_supply_efficiency_factor) == 1) * string(STR_EXTRA_PRIMARY_EFFICIENT1) ) +
( (LOAD_PERM(var_supply_efficiency_factor) == 2) * string(STR_EXTRA_PRIMARY_EFFICIENT2) ) +
( (LOAD_PERM(var_supply_efficiency_factor) == 3) * string(STR_EXTRA_PRIMARY_EFFICIENT3) ) +
( (LOAD_PERM(var_supply_efficiency_factor) == 4) * string(STR_EXTRA_PRIMARY_EFFICIENT4) ) |
LOAD_PERM(var_supply_requirement) << 16,
256
),
return string(STR_EXTRA_PRIMARY);
}
</pre>

for a language file which reads
<pre class=example>
STR_EXTRA_PRIMARY_EFFICIENT1 :{YELLOW}very efficient{BLACK}ly
STR_EXTRA_PRIMARY_EFFICIENT2 :{YELLOW}efficient{BLACK}ly
STR_EXTRA_PRIMARY_EFFICIENT3 :in a {YELLOW}normal{BLACK} way
STR_EXTRA_PRIMARY_EFFICIENT4 :{YELLOW}wasteful{BLACK}ly
STR_EXTRA_PRIMARY :{BLACK}This industry needs {YELLOW}supplies{BLACK}.{}They use them {STRING}{}{}Monthly demand: {YELLOW}{UNSIGNED_WORD} crate{P "" s} of engineering supplies{BLACK}.
</pre>

== Defining cases ==
Similar to OpenTTD's language files, NML can also make use of cases, genders and plural forms. In order to utilize them, they have to be defined in the language file's header and have to match the definition as used in OpenTTD's language files:
<pre>
##case pragma

STR_NAME :Utas
STR_NAME.pragma :utast
</pre>

e.g. for Hungarian you'd have
<pre class=example>
##case t ba

STR_CARGO_PLURAL_PASSENGERS :Utas
STR_CARGO_PLURAL_PASSENGERS.t :utast
</pre>

== Defining genders ==
Genders just like cases are defined in the header of the language file and have to match the definition as found within OpenTTD's language files. The gender of a word or expression is declared within the string's text itself by a tag of the form <code>{G=gendername}</code>:
<pre>
##gender pragma

STR_NAME :{G=gendername}String which requires gender 'gendername'
</pre>
where the string with the defined gender then will trigger the correct usage in a string which includes it and which has to take provisions to show the proper gender:
<pre>
STR_OTHER :Some text {G gender1 gender2 ...} {STRING}
</pre>

for example in German
<pre class=example>
##gender m w n p

STR_CARGO_NAME_BAUXITE :{G=n}Bauxit
</pre>
which then will be used with the correct gender by a string which includes it:
<pre class=example>
STR_NEWS_STATION_NO_LONGER_ACCEPTS_CARGO :{WHITE}{STATION} akzeptiert kein{G "en" "e" "" "e"} {STRING} mehr.
</pre>

== LanguageIDs ==

Valid language IDs are listed in the table below. The cases, genders and number of plural forms is only given as reference. Authorative are the definitions in OpenTTD's language file for each language.

{| class="t"
! ID
! language
! cases
! genders
! plurals
|-
| 00
| English (US)
|
|
|
|-
| 01
| English (GB)
|
|
|
|-
| 02
| German
|
| m w n p
|
|-
| 03
| French
|
| m m2 f
| 2
|-
| 04
| Spanish
|
| m f
|
|-
| 05
| Esperanto
|
| n
|
|-
| 06
| Ido
|
|
|
|-
| 07
| Russian
| m f n p nom gen dat acc abl pre
| m f n p
| 6
|-
| 08
| Irish
|
|
| 4
|-
| 09
| Maltese
|
|
| 12
|-
| 0A
| Tamil
|
|
|
|-
| 0B
| Chuvash
|
|
|
|-
| 0C
| Chinese (Traditional)
|
|
| 1
|-
| 0D
| Serbian
| nom big gen dat aku vok lok ins
| muški ženski srednji
| 6
|-
| 0E
| Norwegian (Nynorsk)
| small
| masculine feminine neuter
|
|-
| 0F
| Welsh
|
|
|
|-
| 10
| Belarusian
| m f n p nom gen dat acc abl pre
| m f n p
| 6
|-
| 11
| Marathi
|
|
|
|-
| 12
| Faroese
|
| m f n
|
|-
| 14
| Arabic (Egypt)
|
|
| 1
|-
| 15
| Czech
| nom gen dat acc voc loc ins big small
| m f n map mnp fp np
| 10
|-
| 16
| Slovak
| g
| m z s
| 10
|-
| 18
| Bulgarian
| m f n p
| m f n p
|
|-
| 1B
| Afrikaans
|
| male
|
|-
| 1E
| Greek
| subs date geniki
| m f n
| 2
|-
| 1F
| Dutch
|
|
|
|-
| 21
| Basque
|
|
|
|-
| 22
| Catalan
|
| Masculin Femenin
|
|-
| 23
| Luxembourgish
|
|
|
|-
| 24
| Hungarian
| t ba
|
| 2
|-
| 26
| Macedonian
|
|
|
|-
| 27
| Italian
| ms mp fs fp
| m ma f
|
|-
| 28
| Romanian
|
|
|
|-
| 29
| Icelandic
|
| karlkyn kvenkyn hvorugkyn
|
|-
| 2A
| Latvian
| kas
| m f
| 3
|-
| 2B
| Lithuanian
| kas ko kam ka kuo kur kreip
| vyr mot
| 5
|-
| 2C
| Slovenian
| r d t
|
| 8
|-
| 2D
| Danish
|
|
|
|-
| 2E
| Swedish
|
|
|
|-
| 2F
| Norwegian (Bokmal)
| small
| masculine feminine neuter
|
|-
| 30
| Polish
| d c b n m w
| m f n
| 7
|-
| 31
| Galician
|
| m f n
|
|-
| 32
| Frisian
|
|
|
|-
| 33
| Ukrainian
| r d z
| m f s mn
| 6
|-
| 34
| Estonian
| g in sü
|
|
|-
| 35
| Finnish
|
|
|
|-
| 36
| Portuguese
|
| n m f mp fp
|
|-
| 37
| Brazilian Portuguese
|
| m f
| 2
|-
| 38
| Croatian
| nom gen dat aku vok lok ins
| male female middle
| 6
|-
| 39
| Japanese
|
|
| 1
|-
| 3A
| Korean
|
| m f
| 11
|-
| 3C
| Malay
|
|
|
|-
| 3D
| English (AU)
|
|
|
|-
| 3E
| Turkish
| tamlanan
|
| 1
|-
| 42
| Thai
|
|
| 1
|-
| 54
| Vietnamese
|
|
| 1
|-
| 56
| Chinese (Simplified)
|
|
| 1
|-
| 5A
| Indonesian
|
|
| 1
|-
| 5C
| Urdu
|
| m f
|
|-
| 61
| Hebrew
| singular plural gen
| m f
|
|-
| 62
| Persian
|
|
|
|}

In case a language is not in this list, check the [[Action4#language IDs|master language list]] (for GRFv7) in the NewGRF Specs. This master list is always leading. NFO language ID 7F has no meaning in NML (set --default-lang instead) and setting bit 16 will break your language file.

NML:Vehicles

2012-01-06T10:02:40Z

Yexo: /* Variables without parameter */

{{NMLNavPropVarCB}}

==Properties common to all vehicle types==

{| class="t"
! property
! value range
! available for articulated vehicle
! comment
|-
| <code style="color:green">name</code>
| (string)
| yes
| for example <code style="color:darkgreen">string(STR_NAME_HEREFORD_TRAM)</code>
|-
| <code style="color:green">climates_available</code>
| bitmask(CLIMATE_XXX, CLIMATE_YYY, ...)
| set to <code style="color:green">NO_CLIMATE</code>
| 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}} 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}} 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 articulated vehicle
! comment
|-
| <code style="color:green">sprite_id</code>
| <code style="color:green">SPRITE_ID_NEW_TRAIN</code>
| yes
| Set this property to enable new graphics
|-
| <code style="color:green">speed</code>
| 0 ... 65000 (float, speed units)
| no
| Max speed for engines, speed limit for wagons
|-
| <code style="color:green">misc_flags</code>
| bitmask(TRAIN_FLAG_XXX, ...)
| FLIP should not be set, TILT and MU 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
|
|-
| <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>
|-
| <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 articulated vehicle
! comment
|-
| sprite_id
| SPRITE_ID_NEW_ROADVEH
| yes
| Set this property to enable new graphics
|-
| speed
| 0 ... 514km/h (float, speed units)
| no
|
|-
| misc_flags
| bitmask(ROADVEH_FLAG_XXX, ...)
| partly; tram flag must the same
| The following flags are defined: ROADVEH_FLAG_TRAM, ROADVEH_FLAG_2CC, ROADVEH_FLAG_AUTOREFIT. Use 0 if you don't want to set any of these flags.
|-
| refit_cost
| 0 ... 255
| yes
| in 25% units of the purchase price cost base
|-
| callback_flags
| bitmask(VEH_CBF_XXX, ...)
| yes
|
Do not set this, unless you use [[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
|
|-
| 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
|
|-
| 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
|
|-
| mail_capacity
| 0 ... 255
|
|-
| 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 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
|
[[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
|-
| vehicle_type_id
|
| No
| ID of 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_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 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==

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

Storages

2011-12-27T16:58:14Z

Yexo: fix variable numbers

==Introduction==

Storages are arrays of registers that can be accessed when using [[VariationalAction2]]. Registers (temporary and persistent alike) always have a size of 4 bytes. If you're writing them using smaller sizes (anything but type 89/8A), the given value will be sign-extended to 4 bytes. Therefore, be careful when you read a register using a bigger size than it was written with. This also applies to registers read by TTDPatch; if not indicated specifically, TTDPatch reads all 4 bytes of the register.

==Description==
===Temporary storage===
{{ottdp|0.6|2.6}}

'''Size:''' 00 - FF (256) (from TTDPatch r1246 to r1301) or 00 - 10F (272) (since TTDPatch r1301 and OpenTTD r9707)

'''Data storage:''' [[VarAction2Advanced#operator|Operator \2sto (0E)]] allows to store values inside the registers of this storage.

'''Data access:''' The first 256 registers 00 to FF can be read using [[VariationalAction2#Variable|variable 7D]]. The rest of the values (100 to 10F) are write only: they are used to pass extra data to some 4x and 6x variables, as well as for returning extra data from callbacks.

Temporary storage contains values local to the current [[VariationalAction2]] chain. When a new chain starts, the values inside the temporary storage are undefined. Therefore, they should not be used unless they have been properly initialized. During the execution of a chain, only that chain can modify the values in the temporary storage.

===Persistent storage===
{{ottdp|0.6|2.6}}

'''Size:''' 00 - 0F (16)

'''Data storage:''' [[VarAction2Advanced#operator|Operator \2psto (10)]] allows to store values inside the registers of this storage.

'''Data access:''' The registers can be read using [[VariationalAction2#Variable|variable 7C]]. Note that it is possible to access the persistent storage of related objects (see [[VariationalAction2#Type]]).

'''Features that support it:''' Industries (0A)

Persistent storage is associated to a single item. When the item is created, all of the values of the persistent storage are set to zero. Persistent storage values cannot be accessed or modified by items that are being created. Persistent storage should not be read if the current feature doesn't support it.

===Persistent storage accessed by GRFID===
{{ottdp|1.2|ottdrev=r22569}}

'''Size:''' 00 - 0F (16) for each GRFID

'''Data storage:''' [[VarAction2Advanced#operator|Operator \2psto (10)]] allows to store values inside the registers of this storage. The GRFID to access must be stored in temporary register 0x100 before using Operator 10. 0xFFFFFFFF can be used to access the GRFID of the item using the current [[VariationalAction2]] chain.

'''Data access:''' The registers can be read using [[VariationalAction2#Variable|variable 7D]]. Note that it is possible to access the persistent storage of related objects (see [[VariationalAction2#Type]]). The GRFID to access must be stored in temporary register 0x100 before checking variable 7D. 0xFFFFFFFF can be used to access the GRFID of the item using the current [[VariationalAction2]] chain.

'''Features that support it:''' Towns (since OpenTTD r22569)

Features supporting persistent storage accessed by GRFID are not restricted to a single persistent storage; there is a persistent storage associated to every GRFID. An item only has write access to the persistent storage associated to its own GRFID, but it can read the registers of any GRFID. Persistent storage values cannot be accessed or modified by items that are being created. Persistent storage should not be read if the current feature doesn't support it.

NML:Vehicles

2011-12-24T22:54:13Z

Yexo: Typo in constant name

{{NMLNavPropVarCB}}

==Properties common to all vehicle types==

{| class="t"
! property
! value range
! available for articulated vehicle
! comment
|-
| <code style="color:green">name</code>
| (string)
| yes
| for example <code style="color:darkgreen">string(STR_NAME_HEREFORD_TRAM)</code>
|-
| <code style="color:green">climates_available</code>
| bitmask(CLIMATE_XXX, CLIMATE_YYY, ...)
| set to <code style="color:green">NO_CLIMATE</code>
| 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}} 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}} 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 articulated vehicle
! comment
|-
| <code style="color:green">sprite_id</code>
| <code style="color:green">SPRITE_ID_NEW_TRAIN</code>
| yes
| Set this property to enable new graphics
|-
| <code style="color:green">speed</code>
| 0 ... 65000 (float, speed units)
| no
| Max speed for engines, speed limit for wagons
|-
| <code style="color:green">misc_flags</code>
| bitmask(TRAIN_FLAG_XXX, ...)
| FLIP should not be set, TILT and MU 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
|
|-
| <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>
|-
| <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 articulated vehicle
! comment
|-
| sprite_id
| SPRITE_ID_NEW_ROADVEH
| yes
| Set this property to enable new graphics
|-
| speed
| 0 ... 514km/h (float, speed units)
| no
|
|-
| misc_flags
| bitmask(ROADVEH_FLAG_XXX, ...)
| partly; tram flag must the same
| The following flags are defined: ROADVEH_FLAG_TRAM, ROADVEH_FLAG_2CC, ROADVEH_FLAG_AUTOREFIT. Use 0 if you don't want to set any of these flags.
|-
| refit_cost
| 0 ... 255
| yes
| in 25% units of the purchase price cost base
|-
| callback_flags
| bitmask(VEH_CBF_XXX, ...)
| yes
|
Do not set this, unless you use [[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
|
|-
| 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
|
|-
| 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
|
|-
| mail_capacity
| 0 ... 255
|
|-
| 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 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
|
[[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
|-
| vehicle_type_id
|
| No
| ID of 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_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
| Not valid before 1920 and after 2090.
|-
| 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 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==

{| 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
|-
| 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 HEQS 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
|}

NML:Disable items

2011-12-22T22:58:47Z

Yexo: fix example

{{NMLNavBlocksyntax}}

With a <code style="color:darkgreen">disable_item</code> statement, it's possible to disable one or more existing items. This works for vehicles, houses, industries, cargos and airports. The general syntax is:

disable_item(feature[, first_id[, last_id]]);

<code style="color:darkgreen">feature</code> specifies the feature of the item(s) to disable. If no further arguments are given, all default items of that feature are disabled. If one more argument (<code style="color:darkgreen">first_id</code>) is given, only that ID is disabled. With two more arguments, all items from <code style="color:darkgreen">first_id</code> up to and including <code style="color:darkgreen">last_id</code> are disabled. For lists of default IDs, consult the documentation about that feature. An example:

<pre style="color:blue">
/* disable all monorail and maglev vehicles */
disable_item(FEAT_TRAINS, 54, 115);
</pre>

NML:Changes 0.3

2011-12-14T16:20:12Z

Yexo:

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

== Introduction ==
Between NML 0.2.x and NML 0.3.x (and their corresponding nightlies) the generated NewGRF version by NML changed from v7 to v8. This brings lot of advantages, but requires a few changes to existing NML files. NewGRFs thus will require a minimum OpenTTD version of 1.2.0 (r23166).

== Callbacks ==
NML 0.3 only supports the new style callbacks. Thus all callback_flag properties have been removed as have the callback flag constants *CBF*. For a complete list of affected constants see the [http://dev.openttdcoop.org/projects/nml/repository/revisions/28c88515e5e7/diff/nml/global_constants.py related commit]

== New named constants ==
A few constants have recently been introduced in both NML 0.2 and 0.3 that make the transition easier. Make sure to use them. For callback "articulated_part" use CB_RESULT_NO_MORE_ARTICULATED_PARTS and/or CB_RESULT_REVERSED_VEHICLE instead of hard-coded 0xFF / 0x80.
For callbacks "cargo_subtype_text", "cargo_subtype_display" and "start_stop" use CB_RESULT_NO_TEXT instead of hard-coded 0xFF.

== Industry availability ==
The callback "availability" is no longer available. Use the callback "construction_probability" instead.

== Heights ==
The "snowline_height" variable returns the height in tiles instead of pixels (=tiles*8).

The "nearby_tile_height" variable returns the height in tiles instead of pixels (=tiles*8).

Template:NMLNavPropVarCB

2011-12-14T15:51:00Z

Yexo:

<noinclude>This is the NML navigation template for Properties/Variables/Callbacks pages and includes the main navigation tempate by itself.</noinclude><div style="float:right; padding-left:12px; background:none;">
{{NMLNavMain}}
<div style="width:180px; border:1px solid #2f6fab; background:#b1cff8; padding:5px; font-size: 12pt; margin-top: 10px;">
<center>Props, Vars and CBs</center>
</div>
<div style="width:180px; border:1px solid #2f6fab; border-top-width: 0px; background:#eaf6f8; padding:5px; -moz-border-radius-bottomleft:5px; -moz-border-radius-bottomright:8px; font-size: 8pt; line-height: 11pt;">

[[NML:General|General]]
* [[NML:General#General variables|variables]]

[[NML:Vehicles|Vehicles]]
*[[NML:Vehicles#Properties common to all vehicle types|common props]] | [[NML:Vehicles#Vehicle variables|vars]] | [[NML:Vehicles#Vehicle callbacks|CBs]]
*[[NML:Vehicles#Train properties|train]] | [[NML:Vehicles#Road vehicle properties|roadveh]] | [[NML:Vehicles#Ship properties|ship]] | [[NML:Vehicles#Aircraft properties|aircr props]]

[[NML:Stations|Stations]]
*[[NML:Stations#Station properties|properties]] | [[NML:Stations#Station variables|variables]] | [[NML:Stations#Station callbacks|callbacks]]

[[NML:Canals|Canals]]
*[[NML:Canals#Canal properties|properties]] | [[NML:Canals#Canal variables|variables]] | [[NML:Canals#Canal callbacks|callbacks]]

[[NML:Bridges|Bridges]]
*[[NML:Bridges#Bridge properties|properties]] | [[NML:Bridges#Bridge variables|variables]] | [[NML:Bridges#Bridge callbacks|callbacks]]

[[NML:Towns|Towns]]

[[NML:Houses|Houses]]
*[[NML:Houses#House properties|properties]] | [[NML:Houses#House variables|variables]] | [[NML:Houses#House callbacks|callbacks]]

[[NML:Industries|Industries]]
*[[NML:Industries#Common variables|common variables]]
*[[NML:Industries#Industry properties|industry props]] | [[NML:Industries#Industry variables|vars]] | [[NML:Industries#Industry callbacks|CBs]]
*[[NML:Industries#Industry tile properties|tile props]] | [[NML:Industries#Industry tile variables|vars]] | [[NML:Industries#Industry tile callbacks|CBs]]

[[NML:Cargos|Cargos]]
*[[NML:Cargos#Cargo properties|properties]] | [[NML:Cargos#Cargo variables|variables]] | [[NML:Cargos#Cargo callbacks|callbacks]]

[[NML:Airports|Airports]]
*[[NML:Airports#Airport properties|airport props]] | [[NML:Airports#Airport variables|vars]] | [[NML:Airports#Airport callbacks|CBs]]
*[[NML:Airports#Airport tile properties|tile props]] | [[NML:Airports#Airport tile variables|vars]] | [[NML:Airports#Airport tile callbacks|CBs]]

[[NML:Objects|Objects]]
*[[NML:Objects#Object properties|properties]] | [[NML:Objects#Object variables|variables]] | [[NML:Objects#Object callbacks|callbacks]]

[[NML:Railtypes|Railtypes]]
*[[NML:Railtypes#Railtype properties|properties]] | [[NML:Railtypes#Railtype variables|variables]] | [[NML:Railtypes#Railtype callbacks|callbacks]]

</div>
</div>

NML:Changes 0.3

2011-12-14T15:39:04Z

Yexo: /* Heights */

== Introduction ==
Between NML 0.2.x and NML 0.3.x (and their corresponding nightlies) the generated NewGRF version by NML changed from v7 to v8. This brings lot of advantages, but requires a few changes to existing NML files. NewGRFs thus will require a minimum OpenTTD version of 1.2.0 (r23166).

== Callbacks ==
NML 0.3 only supports the new style callbacks. Thus all callback_flag properties have been removed as have the callback flag constants *CBF*. For a complete list of affected constants see the [http://dev.openttdcoop.org/projects/nml/repository/revisions/28c88515e5e7/diff/nml/global_constants.py related commit]

== New named constants ==
A few constants have recently been introduced in both NML 0.2 and 0.3 that make the transition easier. Make sure to use them. For callback "articulated_part" use CB_RESULT_NO_MORE_ARTICULATED_PARTS and/or CB_RESULT_REVERSED_VEHICLE instead of hard-coded 0xFF / 0x80.
For callbacks "cargo_subtype_text", "cargo_subtype_display" and "start_stop" use CB_RESULT_NO_TEXT instead of hard-coded 0xFF.

== Industry availability ==
The callback "availability" is no longer available. Use the callback "construction_probability" instead.

== Heights ==
The "snowline_height" variable returns the height in tiles instead of pixels (=tiles*8).

The "nearby_tile_height" variable returns the height in tiles instead of pixels (=tiles*8).

NML:Canals

2011-12-14T15:37:03Z

Yexo: /* Canal variables */

{{NMLNavPropVarCB}}

==Canal properties==

item (FEAT_CANAL, item_name, id) { ... }

{| class="t"
! name
! value range
! comment
|-
| graphic_flags
| bitmask(flags)
| only possible value other than undefined: <code style="color:darkgreen">WATERFEATURE_ALTERNATIVE_SPRITES</code>
|}

=== graphic_flags ===
the <code style="color:darkgreen">WATERFEATURE_ALTERNATIVE_SPRITES</code> defines the type of spritesets used by the single <code style="color:darkgreen">ids</code> of canals (compare also [[Action3/Canals#id| nfo specs]])

== Canal variables ==

{| class="t"
! name
! value range
! comment
|-
|tile_height
|0 .. max_tile_height
| {{nml|0.2}} Tile height in pixels (=tiles * 8).
{{nml|0.3}} Tile height in tiles.
|-
|terrain_type
| TILETYPE_XX
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|-
|random_bits
|0 .. 255
|random bits of that tile
|}

== Canal callbacks ==

{| class="t"
! callback
! return value
! comment
|-
|default
|spriteset
|graphics for the canal id
|-
|sprite_offset
|
|numeric offset into the spriteset for the canal id
|}

== Canal ids ==
{| class="t"
!name
!use
!normal sprites
!alternative sprites
|-
|WF_WATERCLIFFS
|{{ottdp|1.1|2.6|ottdrev=r20352|ttdprev=r1573}} water for canals / locks
|4 slope sprites
|1 flat ground sprite followed by 4 slope sprites
|-
|WF_LOCKS
|{{ottdp|0.6|2.5}} Locks
|24
|undefined
|-
|WF_DIKES
|{{ottdp|0.6|2.5}} Dikes
|12
|undefined
|-
|WF_CANAL_GUI
|{{ottdp|no|2.5}} Canal GUI
|1
|undefined
|-
|WF_FLAT_DOCKS
|{{ottdp|no|2.5}} Flat docks
|4
|undefined
|-
|WF_RIVER_SLOPE
|{{ottdp|1.1|2.6|ottdrev=r20352|ttdprev=r1573}} River water
|4
|1 flat ground sprite followed by 4 slope sprites
|-
|WF_RIVERBANKS
|{{ottdp|0.6|2.6}} Riverbanks
|12*5 (Last 4 for slopes)
|undefined
|-
|WF_RIVER_GUI
|{{ottdp|no|2.6}} River GUI
|2
|undefined
|-
|WF_BUOY
|{{ottdp|1.2|no|ottdrev=r22973}} Buoy
|1
|undefined
|}

NML:Changes 0.3

2011-12-14T15:35:16Z

Yexo: /* Snowline height */

== Introduction ==
Between NML 0.2.x and NML 0.3.x (and their corresponding nightlies) the generated NewGRF version by NML changed from v7 to v8. This brings lot of advantages, but requires a few changes to existing NML files. NewGRFs thus will require a minimum OpenTTD version of 1.2.0 (r23166).

== Callbacks ==
NML 0.3 only supports the new style callbacks. Thus all callback_flag properties have been removed as have the callback flag constants *CBF*. For a complete list of affected constants see the [http://dev.openttdcoop.org/projects/nml/repository/revisions/28c88515e5e7/diff/nml/global_constants.py related commit]

== New named constants ==
A few constants have recently been introduced in both NML 0.2 and 0.3 that make the transition easier. Make sure to use them. For callback "articulated_part" use CB_RESULT_NO_MORE_ARTICULATED_PARTS and/or CB_RESULT_REVERSED_VEHICLE instead of hard-coded 0xFF / 0x80.
For callbacks "cargo_subtype_text", "cargo_subtype_display" and "start_stop" use CB_RESULT_NO_TEXT instead of hard-coded 0xFF.

== Industry availability ==
The callback "availability" is no longer available. Use the callback "construction_probability" instead.

== Heights ==
The "snowline_height" variable returns the height in tiles instead of pixels (=tiles*8).
The "nearby_tile_height" variable returns the height in tiles instead of pixels (=tiles*8).

NML:General

2011-12-14T15:33:04Z

Yexo: Document change to snowline_height

{{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">LOADING_STAGE_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 />

NML:Changes 0.3

2011-12-14T15:32:47Z

Yexo:

== Introduction ==
Between NML 0.2.x and NML 0.3.x (and their corresponding nightlies) the generated NewGRF version by NML changed from v7 to v8. This brings lot of advantages, but requires a few changes to existing NML files. NewGRFs thus will require a minimum OpenTTD version of 1.2.0 (r23166).

== Callbacks ==
NML 0.3 only supports the new style callbacks. Thus all callback_flag properties have been removed as have the callback flag constants *CBF*. For a complete list of affected constants see the [http://dev.openttdcoop.org/projects/nml/repository/revisions/28c88515e5e7/diff/nml/global_constants.py related commit]

== New named constants ==
A few constants have recently been introduced in both NML 0.2 and 0.3 that make the transition easier. Make sure to use them. For callback "articulated_part" use CB_RESULT_NO_MORE_ARTICULATED_PARTS and/or CB_RESULT_REVERSED_VEHICLE instead of hard-coded 0xFF / 0x80.
For callbacks "cargo_subtype_text", "cargo_subtype_display" and "start_stop" use CB_RESULT_NO_TEXT instead of hard-coded 0xFF.

== Industry availability ==
The callback "availability" is no longer available. Use the callback "construction_probability" instead.

== Snowline height ==
The "snowline_height" variable now returns the height in tiles instead of "tiles * 8".

NML:Vehicles

2011-12-14T15:30:15Z

Yexo: /* Aircraft properties */

{{NMLNavPropVarCB}}

==Properties common to all vehicle types==

{| class="t"
! property
! value range
! available for articulated vehicle
! comment
|-
| <code style="color:green">name</code>
| (string)
| yes
| for example <code style="color:darkgreen">string(STR_NAME_HEREFORD_TRAM)</code>
|-
| <code style="color:green">climates_available</code>
| bitmask(CLIMATE_XXX, CLIMATE_YYY, ...)
| set to <code style="color:green">NO_CLIMATES</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}} 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}} 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 articulated vehicle
! comment
|-
| <code style="color:green">sprite_id</code>
| <code style="color:green">SPRITE_ID_NEW_TRAIN</code>
| yes
| Set this property to enable new graphics
|-
| <code style="color:green">speed</code>
| 0 ... 65000 (float, speed units)
| no
| Max speed for engines, speed limit for wagons
|-
| <code style="color:green">misc_flags</code>
| bitmask(TRAIN_FLAG_XXX, ...)
| FLIP should not be set, TILT and MU 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
|
|-
| <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>
|-
| <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 articulated vehicle
! comment
|-
| sprite_id
| SPRITE_ID_NEW_ROADVEH
| yes
| Set this property to enable new graphics
|-
| speed
| 0 ... 514km/h (float, speed units)
| no
|
|-
| misc_flags
| bitmask(ROADVEH_FLAG_XXX, ...)
| partly; tram flag must the same
| The following flags are defined: ROADVEH_FLAG_TRAM, ROADVEH_FLAG_2CC, ROADVEH_FLAG_AUTOREFIT. Use 0 if you don't want to set any of these flags.
|-
| refit_cost
| 0 ... 255
| yes
| in 25% units of the purchase price cost base
|-
| callback_flags
| bitmask(VEH_CBF_XXX, ...)
| yes
|
Do not set this, unless you use [[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
|
|-
| 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
|
|-
| 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
|
|-
| mail_capacity
| 0 ... 255
|
|-
| 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 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
|
[[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
|-
| vehicle_type_id
|
| No
| ID of 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_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
| Not valid before 1920 and after 2090.
|-
| 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 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==

{| 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
|-
| 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 HEQS 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
|}

Template:NMLNavMain

2011-12-13T23:37:55Z

Yexo:

<noinclude>This is the main NML navigation template, it is designed to be included in subnavigation templates. These subnavigation templates in turn are included on each documentation page.</noinclude>
<div style="width:180px; border:1px solid #2f6fab; background:#b1cff8; padding:5px; -moz-border-radius-topleft:5px; -moz-border-radius-topright:5px; font-size: 12pt;">
<center>[[NML:Main|NewGRF Meta Language]]</center>
</div>
<div style="width:180px; border:1px solid #2f6fab; border-top-width: 0px; background:#eaf6f8; padding:5px; font-size: 8pt; line-height: 12pt;">

;[[NML:Preface |Preface]]
;[[NML:Getting started|Getting started]]
;[[NML:Graphic files|Graphics files]]
;[[NML:Language structure|Language structure]]
;[[NML:Block syntax|Block syntax]]
;[[NML:Units|Units]]
;[[NML:Expressions|Expressions]]
;[[NML:Language files|Language files]]
;[[NML:Properties and variables and callbacks|Lists of props, vars and CBs]]
;[[NML:Warnings|Warnings]]
;[[NML:Additional references|Additional references]]
;[[NML:NewGRF compatibility|NewGRF compatibility]]
;[[NML:Old style callbacks|Old-style callbacks]]
;[[NML:changes 0.3|Changes between NML 0.2 and head / 0.3]]
</div>
<div style="width:180px; border:1px solid #2f6fab; border-top-width: 0px; background:#eaf6f8; padding:5px; font-size: 8pt; line-height: 12pt;">
[[NML:Vehicles|Vehicles]],
[[NML:Stations|Stations]],
[[NML:Canals|Canals]],
[[NML:Bridges|Bridges]],
[[NML:Towns|Towns]],
[[NML:Houses|Houses]],
[[NML:Industries|Industries]],
[[NML:Cargos|Cargos]],
[[NML:Airports|Airports]],
[[NML:Objects|Objects]],
[[NML:Railtypes|Railtypes]]
</div>
<div style="width:180px; border:1px solid #2f6fab; border-top-width: 0px; background:#eaf6f8; padding:5px; font-size: 8pt; line-height: 12pt;">

;[[ttwiki:NMLTutorial|NML Tutorial]]

</div>

NML:Changes 0.3

2011-12-13T23:22:00Z

Yexo:

NML:Changes 0.3

2011-12-13T23:19:41Z

Yexo: /* Industry availability */

NML:Spritelayout

2011-12-13T22:53:57Z

Yexo: /* Sprite */

{{NMLNavBlocksyntax}}

Stations, houses, industry tiles, objects, and airport tiles use spritelayouts to define layouts how sprites are supposed to be arranged on a tile. A <code style="color:darkgreen">spritelayout</code> can combine multiple sprites into one entity, which represents everything that is to be drawn on a particular tile. A simple example to illustrate how it works:

<pre style="color:blue">
spritelayout airport_building1 {
ground { sprite: GROUNDSPRITE_NORMAL; }
childsprite {
sprite: spr_small_dirt_ne; // custom spriteset
always_draw: 1; // also draw in transparent mode
}
building {
sprite: 0xA67; // reuse this existing base set sprite
xoffset: 0x0F;
xextent: 1;
zextent: 6;
recolour_mode: RECOLOUR_REMAP;
palette: PALETTE_USE_DEFAULT;
}
}
</pre>

The sprite layout is composed of one or more sprites. Each sprite is defined by a <code style="color:darkgreen">ground</code>, <code style="color:darkgreen">building</code> or <code style="color:darkgreen">childsprite</code> block. What block to use depends on how the sprite is to be placed on the tile.

* <code style="color:darkgreen">ground</code> sprites are drawn at the base of the tile, like grass and concrete, rails etc. in normal TTD. With a few exceptions (e.g. when using custom foundations), you should always provide a ground sprite, even when the building above fully covers it. This because in transparent mode, the building becomes invisible. A tile can only have one ground sprite.
* <code style="color:darkgreen">building</code> sprites are drawn on top of the ground sprite. To determine their location and drawing order (what goes in front of what), they have a 3D bounding box.
* With <code style="color:darkgreen">childsprite</code>(s), you can effectively compose sprites from multiple parts. When placing these after a building sprite, they will use the same bounding box as the previous building sprite. When placing them before the first building sprite, they will have no bounding box, as if they would use the 'bounding box' of the ground tile. Multiple childsprites may be used per ground / building sprite.

The sprite order is genrally determined by the sprite sorter, that evaluates the bounding box (see below) of each sprite. Child sprites are always part of the building (or ground) sprite that precedes them. In the GUI, sprites are always drawn in the order specified in the layout, so be sure to get this correct for spritelayouts that are to be displayed there.

Per sprite, a number of parameters may be set. These are listed below. Unless otherwise indicated, each may have a value that is dependant on '''variables, parameters or registers'''. Accessed variables are always in the <code style="color:darkgreen">SELF</code> scope. Accessing variables inside the purchase list is '''not''' supported, make sure that layouts accessed from there do not use them. Using variables and parameters, it's possible to create wildly differing looks with few spritelayouts.

===Sprite===

The most important parameter is <code style="color:darkgreen">sprite</code>, this determines the actual sprite to be drawn. If you set this to a number, a TTD sprite will be drawn, usually from the base set. Pre-defined constants for some base set sprites are:

* <code style="color:darkgreen">GROUNDSPRITE_NORMAL (a)</code> default terrain type for that climate (temperate, toyland: normal, arctic: without snow, tropical: rainforest).
* <code style="color:darkgreen">GROUNDSPRITE_DESERT (a)</code> desert tile
* <code style="color:darkgreen">GROUNDSPRITE_DESERT_1_2 (a)</code> transition tile between desert and grass
* <code style="color:darkgreen">GROUNDSPRITE_SNOW (a)</code> snowy ground tile
* <code style="color:darkgreen">GROUNDSPRITE_SNOW_1_4 (a)</code> 1/4 snowy ground tile
* <code style="color:darkgreen">GROUNDSPRITE_SNOW_2_4 (a)</code> half-snowy ground tile
* <code style="color:darkgreen">GROUNDSPRITE_SNOW_3_4 (a)</code> 3/4 snowy ground tile
* <code style="color:darkgreen">GROUNDSPRITE_SNOW_4_4 (a)</code> snowy ground tile
* <code style="color:darkgreen">GROUNDSPRITE_CONCRETE</code> concrete ground tile
* <code style="color:darkgreen">GROUNDSPRITE_WATER</code> flat water tile
* <code style="color:darkgreen">GROUNDSPRITE_CLEARED (a)</code> ground tile that has just been bulldozed (with brown colour)

(a) These constants can be used for sprites on flat ground. There are also equivalent sprites for sloped ground, however. These sprites follow the initial ground sprite, the [[NML:Builtin functions|builtin function]] <code style="color:darkgreen">slope_to_sprite_offset(''slope'')</code> may be used to compute the required offset. Refer to the reference on [[NML:List of tile slopes|slopes]] or the [[#Example_.28advanced.29_Spritelayout|example]] below.

Alternatively, you can set the value to (the name of) a [[NML:Spriteset|spriteset]], to provide a custom sprite. When the value is just a spriteset identifier, a sprite from that set will be selected depending on the construction stage, see below. All spritesets used in a layout '''must''' have the same number of sprites, due to a restriction in the NFO format. If you supply an argument (e.g. <code style="color:darkgreen">sprite: some_sprite_set(2);</code>), the corresponding sprite from the sprite set will be used, with an argument of 0 corresponding to the first sprite. Note that the argument may also be variable, so you could e.g. use <code style="color:darkgreen">sprite: some_set(construction_state);</code> to use the construction state to select the sprite (as is the default). If the spriteset has labels defined, you can use these labels in the argument expression.

* For stations, objects and airport tiles, there are no construction stages, so the first sprite from the set is used always.
* For houses and industry tiles, sprite chosen depends on the construction stage and the number of sprites available.
** If there is only one sprite in the set, it is used always.
** If there are two sprites, one is used during construction (stages 0-2) and one for the finished building (stage 3)
** If there are three sprites, one is used for the beginning of construction (stage 0), one for the other construction stages (stages 1-2) and one for the finished building (stage 3).
** If there are four sprites, one is used for each construction stage.
** Sprites after the first four are always ignored.

===Recolouring===

Next, you have the option to apply recolouring, i.e. to change the colours of the sprite. This is done via the following attributes:

* <code style="color:darkgreen">recolour_mode</code>: This must be compile-time constant. Available recolour modes are:
** <code style="color:darkgreen">RECOLOUR_NONE</code>: Use no colour translation (default)
** <code style="color:darkgreen">RECOLOUR_REMAP</code>: Use a colour translation table as defined by <code style="color:darkgreen">palette</code>. This tables maps all colours of the sprite to a new colour.
** <code style="color:darkgreen">RECOLOUR_TRANSPARENT</code>: Draw the sprite in transparant mode, using a colour translation table as defined by <code style="color:darkgreen">palette</code>. Normally the palette will be set to PALETTE_TO_TRANSPARANT to draw all underlying colours somewhat darker. Note that the selected palette is applied to the colours of the underlying sprite, whatever that happens to be. The supplied sprite is only used to determine what pixels to recolour.
* <code style="color:darkgreen">palette</code>: This defines the palette which is used for the colour translation. It may only (and must!) be set when <code style="color:darkgreen">recolour_mode</code> is set to <code style="color:darkgreen">RECOLOUR_REMAP</code> or <code style="color:darkgreen">RECOLOUR_TRANSPARENT</code>. The available values are the same as for <code style="color:darkgreen">sprite</code>, i.e. you can use either a default sprite or a sprite from a sprite set. In this case, however, the referenced sprite must not be a real sprite, but a [[NML:Recolour sprites|recolour sprite]]. For available default recolour sprites, see the appendix on [[NML:List of default colour translation palettes|available palettes]].

===Display yes/no===

The following attributes allow configuring whether the sprite will be displayed or not.

* <code style="color:darkgreen">hide_sprite</code>: If set to 1, this sprite will not be drawn at all. Default is 0. If a building sprite is not drawn, all child sprites that share its bounding box are not drawn either. Setting this to a constant value makes little sense, but you can use this to enable/disable drawing certain sprites at runtime depending on certain conditions.
* <code style="color:darkgreen">always_draw</code>: This must be a compile-time-constant. If set to 1, this sprite will also be drawn when the user has enabled transparant mode. The default value is 0. This is not available for ground sprites (those are drawn always), but it is for child sprites that share their bounding box with the ground sprite.

===Positioning===

How to position the sprite depends on the type of sprite:

* <code style="color:darkgreen">ground</code>: Ground sprites cannot be positioned.
* <code style="color:darkgreen">building</code>: A three-dimensional bounding box may be defined. The X-axis runs from top-right to bottom-left and the Y-axis from top-left to bottom-right. The Z axis is vertical. All units are relative to the tile, with a tile being 16 units in the X and Y directions. Extending the bounding box over the edges of a tile is possible, but not recommended as it may lead to glitches. To define the bounding box, the following attributes can be used:
** <code style="color:darkgreen">xoffset</code>: Offset from the northwestern edge to the start of the bounding box (X).
** <code style="color:darkgreen">yoffset</code>: Offset from the northeastern edge to the start of the bounding box (Y).
** <code style="color:darkgreen">zoffset</code>: Offset from the lowest tile corner (with foundation added) to the start of the bounding box (Z).
** <code style="color:darkgreen">xextent</code>: Size of the bounding box, in the X-direction. Must be a compile-time constant.
** <code style="color:darkgreen">yextent</code>: Size of the bounding box, in the Y-direction. Must be a compile-time constant.
** <code style="color:darkgreen">zextent</code>: Size of the bounding box, in the Z-direction. Must be a compile-time constant. Default values are 0, 0, 0, 16, 16, 16, respectively. In NewGRF developer mode in OpenTTD, it's possible to view the bounding boxes of all sprites by pressing Ctrl+B.
* <code style="color:darkgreen">childsprite</code>: Child sprites may be positioned relative to their 'parent' sprite that defines the bounding box. <code style="color:darkgreen">xoffset</code> and <code style="color:darkgreen">yoffset</code> may be set to specify an offset in pixels between the origin of the parent and child sprite. When the parent sprite is the ground sprite, TTDPatch does not support offsets other than 0,0. Note that all child sprites should fit inside the bounding box of the parent sprite to avoid visual glitches.

===Example (advanced) Spritelayout===

OpenTTD 1.2 (r22723) allows for nice shorthands in defining multiple views, e.g. for different slopes: Spritelayout can have parameters and may use variables and temporary storage inside of a layout. A common usage for such parametrized spritelayout is taking care of the tile slope and ground type as illustrated in this example:

<pre style="color:blue">
spritelayout company_land_layout {
ground {
// normal ground sprite - always draw
sprite: LOAD_TEMP(0) + LOAD_TEMP(1);
}
childsprite {
// company-coloured border - always draw
sprite: cc_frame(LOAD_TEMP(0));
always_draw: 1;
recolour_mode: RECOLOUR_REMAP;
palette: PALETTE_USE_DEFAULT;
}
childsprite {
// again the normal ground sprite. Thus in non-transparent view
// only the normal ground sprite is shown. In transparent view
// this acts as sprite which darkens the other two sprites via
// a translation to transparency.
sprite: LOAD_TEMP(0) + LOAD_TEMP(1);
}
}

// A pseudo-switch which sets the temporary parameters for the sprite layout, storing the sprite number
// which belongs to the terrain type and the corresponding offset due to the tile slope
switch (FEAT_OBJECTS, SELF, company_land_terrain_switch, [
// We store the offset into the spriteset due to the tile slope into the 1st temporary variable
STORE_TEMP(slope_to_sprite_offset(tile_slope), 0),

// We store the offset to the flat groundsprite we use into the 2nd temporary variable
STORE_TEMP(GROUNDSPRITE_NORMAL, 1),
STORE_TEMP(terrain_type == TILETYPE_DESERT ? GROUNDSPRITE_DESERT : LOAD_TEMP(1), 1),
STORE_TEMP(terrain_type == TILETYPE_SNOW ? GROUNDSPRITE_SNOW : LOAD_TEMP(1), 1),

1
]) {
company_land_layout;
}
</pre>

NML:Industries

2011-12-13T22:37:46Z

Yexo: /* Industry callbacks */

{{NMLNavPropVarCB}}

This page contains information on both industry and industry tile properties, variables and callbacks.

==Industry properties==

Industry properties. Default industry type numbers can be found at [[NML:Default industries|default industries]].

{| class="t"
! property
! value range
! comment
|-
| substitute
| industry type
| Number of the original industry type that replaces this one, should it not be available for some reason (e.g. missing NewGRF). This ''must'' be the first property to be set, before any other properties or graphics. All properties of the old type are copied to your new industry.
|-
| override
| industry type
| Number of the original industry type overridden. This will cause other grfs / industries to consider your industry type the same as the old type. Only set this property if your type is (more or less) the same as the old type.
|-
| layouts
| Array of tilelayouts
|
See [[NML:Tilelayout|Tilelayout]] syntax.
|-
| life_type
| One of IND_LIFE_TYPE_XXX, XXX = BLACK_HOLE <nowiki>|</nowiki> EXTRACTIVE <nowiki>|</nowiki> ORGANIC <nowiki>|</nowiki> PROCESSING
| The generic type of industry. This determines the production changes that occur by default (when not using the callback). Examples are respectively power plants, coal mines, forests en steel mills.
|-
| closure_msg
| string
|
Message displayed when the industry announces closure. Use a custom string or one of the [[NML:Default TTD strings|default TTD strings]].
|-
| prod_increase_msg
| string
|
Message displayed when industry increases production. Use a custom string or one of the [[NML:Default TTD strings|default TTD strings]].
|-
| prod_decrease_msg
| string
|
Message displayed when industry decreases production. Use a custom string or one of the [[NML:Default TTD strings|default TTD strings]].
|-
| fund_cost_multiplier
| 0..255
| Fund cost multiplier. Note that in OpenTTD the unmodified base cost is 8x higher for building (not prospecting) raw (=extractive / organic, see life_type) industries.
|-
| prod_cargo_types
| array of up to 2 ints
| Types of cargo produced. Use the cargotype(<label>) built-in function to specify a label from the cargotable.
|-
| accept_cargo_types
| array of up to 3 ints
| Types of cargo accepted. Use the cargotype(<label>) built-in function to specify a label from the cargotable
|-
| prod_multiplier
| array of up to 2 ints (0..255)
| Amount of each output cargo to produce every 256 ticks (8 or 9 times a month)
|-
| min_cargo_distr
| 0..255
| Minimal amount of cargo before transporting to stations.
|-
| random_sound_effects
| array of ints
| Sound effect numbers that are played some times.
|-
| conflicting_ind_types
| array of up to 3x industry_type(IND_TYPE_OLD <nowiki>|</nowiki> IND_TYPE_NEW, id)
|
Three industry types that should not be nearby. Use the [[NML:Builtin functions|builtin function]] <code style="color:darkgreen">industry_type(..)</code> to define either an old industry (using the global ID) or a new industry from your grf (using the grf-local ID).
|-
| prob_random
| 0..255
| Probability of occurring while generating initial industries.
|-
| prob_in_game
| 0..255
| Probability of occurring while creating industries during the game.
|-
| map_colour
| 0..255
|
Colour index from the [[NML:Graphic files|DOS palette]] to use on the minimap for this industry.
|-
| spec_flags
| bitmask(flags)
|
for flag values see [[#industry_special_flags|Industry special flags]]
|-
| new_ind_msg
| string
| Message displayed when industry gets built during game play.
|-
| input_multiplier_1
| array of up to 2 floats (0..255)
| Output cargo multiplication factors for getting a unit of the first accepted cargo.
|-
| input_multiplier_2
| array of up to 2 floats (0..255)
| Output cargo multiplication factors for getting a unit of the second accepted cargo.
|-
| input_multiplier_3
| array of up to 2 floats (0..255)
| Output cargo multiplication factors for getting a unit of the third accepted cargo.
|-
| name
| string
|
Name of the industry, use a custom string or one of the [[NML:Default TTD strings|default TTD strings]].
|-
| prospect_chance
| 0 .. 1 (float)
| Chance of successful prospecting.
|-
| callback_flags
| bitmask(flags)
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| remove_cost_multiplier
| int
| Cost multiplier for removing the industry (currently only possible with magic bulldozer).
|-
| nearby_station_name
| string
| Default additional name for a nearby station
|}

===Industry special flags===

{| class="t"
! flag
! meaning
|-
| IND_FLAG_PLANT_FIELDS_PERIODICALLY
| The industry periodically plants fields around itself (temperate and arctic farms)
|-
| IND_FLAG_CUT_TREES
| The industry cuts trees around itself and produces its first output cargo from them (lumber mill)
|-
| IND_FLAG_BUILT_ON_WATER
| The industry is built on water (oil rig)
|-
| IND_FLAG_ONLY_IN_LARGE_TOWNS
| The industry can only be built in towns (i.e. it has to replace houses) with population larger than 1200 (temperate bank)
|-
| IND_FLAG_ONLY_IN_TOWNS
| The industry can only be built in towns (i.e. it has to replace houses) (arctic and tropic banks, water tower)
|-
| IND_FLAG_BUILT_NEAR_TOWN
| The industry is always built near towns (i.e. near town sign; additionally the industry is allowed to replace houses) (toy shop)
|-
| IND_FLAG_PLANT_FIELDS_WHEN_BUILT
| Fields are planted around the industry when it's built (all farms)
|-
| IND_FLAG_NO_PRODUCTION_INCREASE
| The industry cannot increase its production on the temperate climate (oil wells)
|-
| IND_FLAG_BUILT_ONLY_BEFORE_1950
| The industry is built only before 1950 (oil wells)
|-
| IND_FLAG_BUILT_ONLY_AFTER_1960
| The industry is built only after 1960 (oil rig)
|-
| IND_FLAG_AI_CREATES_AIR_AND_SHIP_ROUTES
| AI players will attempt to establish air and ship routes going to this industry (oil rig)
|-
| IND_FLAG_MILITARY_AIRPLANE_CAN_EXPLODE
| The industry can be exploded by a military airplane (oil refinery)
|-
| IND_FLAG_MILITARY_HELICOPTER_CAN_EXPLODE
| The industry can be exploded by a military helicopter (factory)
|-
| IND_FLAG_CAN_CAUSE_SUBSIDENCE
| The industry can cause a subsidence (coal mine)
|-
| IND_FLAG_AUTOMATIC_PRODUCTION_MULTIPLIER
| Automatic production multiplier handing (No industry has this bit set by default.).
|-
| IND_FLAG_RANDOM_BITS_IN_PRODUCTION_CALLBACK
| The production callback needs random bits in var. 10 (No industry has this bit set by default.)
|-
| IND_FLAG_DO_NOT_FORCE_INSTANCE_AT_MAP_GENERATION
| Do not force one instance of this type to appear during initial map generation (No industry has this bit set by default.)
|-
| IND_FLAG_ALLOW_CLOSING_LAST_INSTANCE
| Allow closing down the last instance of this type (No industry has this bit set by default.)
|}

==Industry tile properties==

{| class="t"
! property
! value range
! comment
|-
| substitute
|
[[NML:Default industry tiles|0..174]]
| Number of the default industry tile that replaces this one, if this industry tile is not available for some reason. This property ''must'' be set first, before any other properties or graphics. All properties of the old type are copied to your new house.
|-
| override
|
[[NML:Default industry tiles|0..174]]
| id of the default industry tile which this industry tile replaces. This will cause your industry tile to be placed instead of the default industry tile. This is ignored, if the default industry tile has already been overridden. You can define this property multiple times
|-
| accepted_cargos
| Array with up to 3 [cargo_id, amount]-pairs.
| The cargos that are accepted by this tile. CargoID is a cargo type from your cargo translation table, amount is the acceptance of the given cargo in 1/8 units. Example: to make a tile accept both COAL and IORE you could use this: <code style="color:darkgreen"><nowiki>accepted_cargos: [[COAL, 8], [IORE, 8]];</nowiki></code> Example: for a tile that doesn't any cargos at all you'd use: <code style="color:darkgreen">accepted_cargos: [];</code>
|-
| land_shape_flags
|
bitmask([[#Land shape flags|Land shape flags]])
|
|-
| callback_flags
| bitmask(INDTILE_CBF_XXX, INDTILE_CBF_YYY)
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| 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
| bitmask(ANIM_TRIGGER_INDTILE_XXX, ... )
|
Bitmask of triggers that will trigger the <code style="color:darkgreen">anim_control</code> callback, see the [[#Animation triggers|table]] below.
|-
| special_flags
| bitmask(INDTILE_FLAG_XXX)
| XXX is a special flag description. Currently there's only one flag defined: set INDTILE_FLAG_RANDOM_ANIMATION if the decision in anim_control callback needs random bits via extra_callback_info1
|}

===Land shape flags===

{| class="t"
! Flag
! Meaning
|-
| LSF_CANNOT_LOWER_NW_EDGE
| North-west edge cannot be lowered
|-
| LSF_CANNOT_LOWER_NE_EDGE
| North-east edge cannot be lowered
|-
| LSF_CANNOT_LOWER_SW_EDGE
| South-west edge cannot be lowered
|-
| LSF_CANNOT_LOWER_SE_EDGE
| South-east edge cannot be lowered
|-
| LSF_ONLY_ON_FLAT_LAND
| This tile can only be built on flat land
|-
| LSF_ALLOW_ON_WATER
| The land/water check is disabled for this tile so it can be built on water. If you need more control over this use callback 0x2F.
|}

==Common variables==

The following variables are available to both industries and industry tiles. All of them require an x, y offset. For industries, this offset is unsigned and relative to the northernmost tile. For industry tiles, it is signed and relative to the current tile.

{| class="t"
! name
! value range
! comment
|-
| nearby_tile_slope
| SLOPE_XXX
|
See [[NML:List of tile slopes|tile slopes]] for an overview of possible values
|-
| nearby_tile_is_water
| 1 if the tile is water, 0 otherwise
|
|-
| nearby_tile_terrain_type
| TILETYPE_XX
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|-
| nearby_tile_water_class
| 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
| 0..120
| The height of the lowest corner of the given tile.
|-
| nearby_tile_class
|
[[NML:List of tile classes|Tile class]]
|
|-
| nearby_tile_animation_frame
| 0..255
| Animation frame of the given tile
|-
| nearby_tile_industrytile_id
| 0x00aa, 0xFFbb, 0xFFFE or 0xFFFF
| 0x00aa: The tile is an industry tile that is part of this GRF, the tile id is aa. 0xFFbb: The tile is an original industry tile with id bb. 0xFFFE: The tile is an industry tile defined in another GRF. 0xFFFF: The tile is not an industry tile or it belongs to another GRF.
|}

==Industry variables==

{| class="t"
! name
! value range
! comment
|-
| production_level
| 0, or 4 .. 128
| Current production level of the industry. Usually in range 4 .. 128, default starting level is 16. A level of 0 indicates imminent closure.
|-
| waiting_cargo_1
| 0..65535
| If any of the production callbacks is enabled, this variable will contain the amount of the first cargo type awaiting to be processed.
|-
| waiting_cargo_2
| 0..65535
| If any of the production callbacks is enabled, this variable will contain the amount of the second cargo type awaiting to be processed.
|-
| waiting_cargo_3
| 0..65535
| If any of the production callbacks is enabled, this variable will contain the amount of the third cargo type awaiting to be processed.
|-
| produced_cargo_waiting_1
| 0..65535
| The amount of produced 'output cargo type 1' that this waiting to be transported.
|-
| produced_cargo_waiting_2
| 0..65535
| The amount of produced 'output cargo type 2' that this waiting to be transported.
|-
| produced_this_month_1
| 0..65535
| The amount of 'output cargo type 1' that was produced this month.
|-
| produced_this_month_2
| 0..65535
| The amount of 'output cargo type 2' that was produced this month.
|-
| produced_last_month_1
| 0..65535
| The amount of 'output cargo type 1' that was produced last month.
|-
| produced_last_month_2
| 0..65535
| The amount of 'output cargo type 2' that was produced last month.
|-
| transported_this_month_1
| 0..65535
| The amount of 'output cargo type 1' that was transported this month.
|-
| transported_this_month_2
| 0..65535
| The amount of 'output cargo type 2' that was transported this month.
|-
| transported_last_month_1
| 0..65535
| The amount of 'output cargo type 1' that was produced last month.
|-
| transported_last_month_2
| 0..65535
| The amount of 'output cargo type 2' that was produced last month.
|-
| transported_last_month_pct_1
| 0..100
| Percentage of produced 'output cargo type 1' that was transported last month.
|-
| transported_last_month_pct_2
| 0..100
| Percentage of produced 'output cargo type 2' that was transported last month.
|-
| water_distance
| Distance to the tile
| If the industry is built on water, this variable gives the distance of the closest dry land tile, otherwise it gives the distance of the closest water tile.
|-
| layout_num
| 1..255
| Number of the layout being used by the industry.
|-
| founder
| 0..16
| Company number of the industry founder. It will be FOUNDER_GAME (=16) if the industry was generated randomly. TTDPatch only supports up to 8 companies (0..7).
|-
| founder_type
| PLAYERTYPE_XX
| PLAYERTYPE_HUMAN, PLAYERTYPE_AI, PLAYERTYPE_HUMAN_IN_AI (human managing AI company) or PLAYERTYPE_AI_IN_HUMAN (AI managing human company). OpenTTD only uses PLAYERTYPE_HUMAN and PLAYERTYPE_AI. If you cheat yourself to be part of an AI company OpenTTD will still report PLAYERTYPE_AI for the company with yourself and the AI and it'll report PLAYERTYPE_HUMAN for the now uncontrolled company.
|-
| founder_colour1
| COLOUR_XXX
|
Index of founding company's first colour. 0 if not founded by a company. Refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for possible values.
|-
| founder_colour2
| COLOUR_XXX
|
Index of founding company's second colour. It's the same as company_colour1, if no second company colour is chosen. 0 if not founded by a company. Refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for possible values.
|-
| colour
| COLOUR_XXX
|
Random colour for this industry. Refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for possible values.
|-
| build_date
| 0..1826212865
| Date of the industry foundation in days since year 0.
|-
| build_type
| BUILDTYPE_XX
| BUILDTYPE_UNKNOWN (if created in an old version or with newindustries disabled), BUILDTYPE_GAMEPLAY (if founded or created by the in-game random industry generator), BUILDTYPE_GENERATION (if created during random map generation) or BUILDTYPE_EDITOR (if created with the scenario editor).
|-
| counter
| 0..65535
| Decremented every tick, used to time primary industry production in TTD.
|-
| last_accept_date
| date(year, month, day)
| Date when cargo was accepted for the last time. Not valid before 1920 and after 2090.
|-
| random_bits
| 0 ... 65535
| Random data that can be used to randomize certain descisions. (see [[NML:Random_switch|Random switch]]) (NML r1666)
|}

 Variables that require some parameters.

{| class="t"
! name
! arguments
! comment
|-
| industry_count
| industry_type, grfid = -1
|
The value of this variable is the number of industries of a given type that are currently on the map. industry_type is either the ID of an industry. GRFid is the grf in which the industry was defined. The default value is -1, which means current newgrf. A grfid of 0 lets you check the number of default industries of a given type. Use the [[NML:Builtin functions|builtin function]] <code style="color:darkgreen">str2number()</code> to convert a grfid to its numeric representation. ''Warning: using this variable trashes the contents of temporary storage register 0x100''
|-
| industry_distance
| industry_type, grfid = -1
| The value of this variable is the manhattan distance the closest instance of the given industry or 0xFFFF if not applicable. See industry_count for a description of the parameters. ''Warning: using this variable trashes the contents of temporary storage register 0x100.''
|-
| industry_layout_count / industry_layout_distance
| industry_type, layout, grfid = -1.
| See industry_count / industry_distance for description of industry_type, grfid and return value. The results are filtered to industries that have the given layout number. ''Warning: using this variable trashes the contents of temporary storage registers 0x100 and 0x101.''
|-
| industry_town_count
| industry_type, grfid = -1.
| See industry_count / industry_distance for description of industry_type, grfid and return value. The results are filtered to industries that have the same town than the current industry. ''Warning: using this variable trashes the contents of temporary storage registers 0x100 and 0x101.''
|-
| town_manhattan_dist
| x, y
| Parameters indicate a signed offset relative to the northern tile. Returns the Manhattan distance (dx + dy) from the selected tile to the closest town
|-
| town_euclidean_dist
| x, y
| Parameters indicate a signed offset relative to the northern tile. Returns the squared Eucleidean distance (dx^2 + dy^2) from the selected tile to the closest town.
|-
| town_zone
| x, y
|
Parameters indicate a signed offset relative to the northern tile. Returns the [[NML:List of town zones|town zone]] that the selected tile is in.
|-
| nearby_tile_random_bits
| x, y
| Parameters indicate an unsigned offset relative to the northern tile. Returns the random bits of the selected industry tile, or 0 if it is not an industry tile that's part of this industry.
|}

==Industry tile variables==

{| class="t"
! name
! value range
! comment
|-
| construction_state
| 0..3
| Current construction state of the industry tile.
|-
| terrain_type
| TILETYPE_XX
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|-
| town_zone
|
[[NML:List of town zones|town zone]]
| The town zone of the current tile.
|-
| 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.
|-
| animation_frame
| 0..255
| Current animation frame.
|}

 

Industry tiles have access to the [[#Common variables|common variables]] described above. Additionally, they have access to the following:

{| class="t"
! name
! arguments
! comment
|-
| nearby_tile_is_same_industry
| x, y
| Parameters indicate a signed tile offset relative to the current tile. Returns 1 if the tile is part of the same industry, 0 otherwise
|}

==Industry callbacks==

{| class="t"
! callback
! return value
! comment
|-
| default
| varies
| Any unhandled callbacks. Generally this doesn't need to be used, except for old-style callbacks.
|-
| produce_cargo_arrival
| Produce-block
| Called to produce cargo when it arrives.
|-
| produce_256_ticks
| Produce-block
| Called to produce cargo every 256 ticks.
|-
| availability
| CB_RESULT_IND_ALLOW or CB_RESULT_IND_DISALLOW
|
Only available in NML 0.2 or earlier. Called when the game needs to know if the industry type is available. It is limited to the type as a whole, so you can't access industry-specific variables. <code style="color:darkgreen">extra_callback_info2</code> contains the [[#Industry creation types|creation type]].
|-
| construction_probability
| CB_RESULT_IND_NO_CONSTRUCTION, CB_RESULT_IND_PROBABILITY_FROM_PROPERTY or a relative probability 0..255
|
Only available in NML 0.3 or later. Called when the game needs to know if the industry type is available. It is limited to the type as a whole, so you can't access industry-specific variables. <code style="color:darkgreen">extra_callback_info2</code> contains the [[#Industry creation types|creation type]]. If you return CB_RESULT_IND_NO_CONSTRUCTION or 0 the industry won't be build. If you return CB_RESULT_IND_PROBABILITY_FROM_PROPERTY it'll be build according to the relative probability as defined in the <code style="color:darkgreen">prob_random</code> or <code style="color:darkgreen">prob_in_game</code> properties, otherwise it'll use the value as returned as relative probability.
|-
| location_check
|
See the [[#Location check results|table]] below.
|
Called to check if a location is suitable. <code style="color:darkgreen">extra_callback_info2</code> contains the [[#Industry creation types|creation type]]. Since the industry isn't built yet, industry variables aren't available. If this callback is not implemented or fails, constructing the industry will be allowed. Construction might also be prevented via the <code style="color:darkgreen">tile_check</code> industry tile callback, though.
|-
| monthly_prod_change
|
See [[#Production change callback results|below]]
| Called each month to (possibly) change the industry production. <code style="color:darkgreen">extra_callback_info2</code> contains random bits.
|-
| random_prod_change
|
See [[#Production change callback results|below]]
| Works exactly the same as <code style="color:darkgreen">monthly_prod_change</code>, except that it's only called when TTD selects this industry for a random production change.
|-
| cargo_subtype_display
| String or CB_RESULT_NO_TEXT
| This callback allows displaying some text after a cargo name. Returning CB_RESULT_NO_TEXT displays nothing. The lowest byte of <code style="color:darkgreen">extra_callback_info2</code> contains 0 .. 2 to get texts for the first .. third accepted cargo type, and 3 .. 4 for the first ... second produced cargo type. The second byte contains 0 when getting a string for the buy menu (no industry variables available!), 1 when for the industry window and 2 for the industry directory window.
|-
| extra_text_industry
| String
| Show extra text in the industry window.
|-
| extra_text_fund
| String
| Show extra text in the fund window. Since the industry isn't built, no industry variables are available.
|-
| control_special
| 0 or 1
| Called to control various effects from the <code style="color:darkgreen">spec_flags</code> property. Currently only works for the first two (plant fields / cut trees). Return 1 to execute the action or 0 to not do so. The relevant flag is given in <code style="color:darkgreen">extra_callback_info2</code>. The default (if the flag is enabled, of course) is to plant fields with 1/8th chance every 256 ticks, and to cut trees every 512 ticks. Random bits are supplied in <code style="color:darkgreen">extra_callback_info1</code>.
|-
| stop_accept_cargo
| 0 or 1
| With this callback, you can temporarily refuse accepting a certain cargo, for example because the stockpile is full. Return 1 to accept or 0 to refuse. Make sure to synchronize this callback with the <code style="color:darkgreen">cargo_amount_accept</code> callback for industry tiles. <code style="color:darkgreen">extra_callback_info2</code> contains the cargo type to accept or not.
|-
| colour
| COLOUR_XXX
| Called after constructing the industry. The <code style="color:darkgreen">colour</code> variable is set to a random value at this point, you can use this callback to change this.
|-
| cargo_input
| Cargo type, or 0xFF
| Decide the input cargo types. Called repeatedly until 0xFF is returned, although currently not more than three times. Do not rely on this limitation, though. <code style="color:darkgreen">extra_callback_info1</code> starts at 0 and is incremented for every iteration. Return a cargo type (from the table) or 0xFF to stop.
|-
| cargo_output
| Cargo type, or 0xFF
| Same as <code style="color:darkgreen">cargo_input</code> above, except that it is applied to the output cargo types and currently not called more than twice.
|}

===Location check results===

The following values can be used as return values for the <code style="color:darkgreen">location_check</code> callback for industries
and the <code style="color:darkgreen">tile_check</code> callback for industry tiles and objects.

{| class="t"
! return value
! meaning
|-
| string(..)
| Item can't be built, show the string as error message.
|-
| CB_RESULT_LOCATION_ALLOW
| Item can be built.
|-
| CB_RESULT_LOCATION_DISALLOW
| Item can't be built, display the default error message. This is "site unsuitable" for industries and industry tiles, and "land sloped in wrong direction" for objects.
|-
| CB_RESULT_LOCATION_DISALLOW_ONLY_RAINFOREST
| Item can't be built, display the "...can only be built in rainforest areas" error message.
|-
| CB_RESULT_LOCATION_DISALLOW_ONLY_DESERT
| Item can't be built, display the "...can only be built in desert areas" error message.
|-
| CB_RESULT_LOCATION_DISALLOW_ONLY_ABOVE_SNOWLINE
| Item can't be built, display the "...can only be built above the snow-line" error message.
|-
| CB_RESULT_LOCATION_DISALLOW_ONLY_BELOW_SNOWLINE
| Item can't be built, display the "...can only be built below the snow-line" error message.
|-
| CB_RESULT_LOCATION_DISALLOW_NOT_ON_OPEN_SEA
| Item can't be built, display the "...can't build on open sea" error message.
|-
| CB_RESULT_LOCATION_DISALLOW_NOT_ON_CANAL
| Item can't be built, display the "...can't build on canal" error message
|-
| CB_RESULT_LOCATION_DISALLOW_NOT_ON_RIVER
| Item can't be built, display the "...can't build on river" error message.
|}

===Production change callback results===

{| class="t"
! value
! meaning
|-
| CB_RESULT_IND_PROD_NO_CHANGE
| Do not change industry production
|-
| CB_RESULT_IND_PROD_HALF
| Half industry production. If production goes below a quarter of default, the industry closes.
|-
| CB_RESULT_IND_PROD_DOUBLE
| Double production if it's not 8x default yet.
|-
| CB_RESULT_IND_PROD_CLOSE
| Announce closoure and remove the industry next month.
|-
| CB_RESULT_IND_PROD_RANDOM
| Do a random production change, as if the industry is a primary one.
|-
| CB_RESULT_IND_PROD_DIVIDE_BY_4
| Divide production by 4
|-
| CB_RESULT_IND_PROD_DIVIDE_BY_8
| Divide production by 8
|-
| CB_RESULT_IND_PROD_DIVIDE_BY_16
| Divide production by 16
|-
| CB_RESULT_IND_PROD_DIVIDE_BY_32
| Divide production by 32
|-
| CB_RESULT_IND_PROD_MULTIPLY_BY_4
| Multiply production by 4
|-
| CB_RESULT_IND_PROD_MULTIPLY_BY_8
| Multiply production by 8
|-
| CB_RESULT_IND_PROD_MULTIPLY_BY_16
| Multiply production by 16
|-
| CB_RESULT_IND_PROD_MULTIPLY_BY_32
| Multiply production by 32
|-
| CB_RESULT_IND_PROD_DECREMENT_BY_1
| Decrement production by 1
|-
| CB_RESULT_IND_PROD_INCREMENT_BY_1
| Increment production by 1
|-
| CB_RESULT_IND_PROD_SET_BY_0x100
| Set the production level to the value in bits 16 .. 23 of register 0x100.
|}

Setting bit 7 of the result disables the associated news message. Setting bit 8 replaces the news message with a custom message, read from register 0x100 bits 0 .. 15.

===Industry creation types===

{| class="t"
! value
! meaning
|-
| IND_CREATION_GENERATION
| Industry is created during map generation, or when building 'many random industries' in the scenario editor.
|-
| IND_CREATION_RANDOM
| Industry is randomly generated during gameplay
|-
| IND_CREATION_FUND
| Industry is funded by the player (in game or scenario editor)
|-
| IND_CREATION_PROSPECT
| Industry is prospected by the player
|}

==Industry tile callbacks==

{| class="t"
! callback
! return value
! comment
|-
| default
| Sprite layout
| Graphics for the industry tile
|-
| random_trigger
| N/A
|
See [[NML:Random switch|random switch]] for more information.
|-
| 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 enabled in the <code style="color:darkgreen">special_flags</code> property. Returning a sound effect in the high byte will cause that sound effect to be played.
|-
| anim_control
| Next animation frame or CB_RESULT_XXX
|
Called whenever an 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 enabled in the <code style="color:darkgreen">special_flags</code> property. Returning a sound effect in the high byte will cause that sound effect to be played. <code style="color:darkgreen">extra_callback_info2</code> contains the reason to trigger the animation, see the [[#Animation triggers|table]] below. Note that you need to enable the wanted triggers in the <code style="color:darkgreen">animation_triggers</code> property.
|-
| 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.
|-
| cargo_type_accept
| type1 + (type2 << 5) + (type3 << 10)
| Decide the cargo types that this tile accepts. If this callback is not implemented or fails, the values from <code style="color:darkgreen">accepted_cargos</code> are used instead. Bits 0..4: First cargo type. Bits 5..9: Second cargo type. Bits 10..14: Third cargo type.
|-
| cargo_amount_accept
| amt1 + (amt2 << 4) + (amt3 << 8)
| Acceptance for each cargo amount in 1/8th. If this callback is not implemented or fails, the values from <code style="color:darkgreen">accepted_cargos</code> are used instead. Cargo types are from the <code style="color:darkgreen">cargo_type_accept</code> callback, or the <code style="color:darkgreen">accepted_cargos</code> property if that callback failed. Bits 0..3: Acceptance of first cargo type. Bits 4..7: Acceptance of second cargo type. Bits 8..11: Acceptance of third cargo type.
|-
| tile_check
|
Same as for the [[#Location check results|location_check]] industry callback
|
Called before constructing the industry, so nothing exists on the map yet. Since the industry isn't built yet, so you can't access industry variables. From the tile variables, relative x/y/position, town zone are available, as well as the class, height, slope, terrain type and water status of nearby tiles. <code style="color:darkgreen">extra_callback_info2</code> contains the industry layout number in the lowest (first) byte and the [[#Industry creation types|creation type]] in the second byte. If this callback is not implemented or fails, the <code style="color:darkgreen">land_shape_flags</code> property will be used instead to determine if the slope is suitable. This also means that without this callback, the tile may not be built on steep slopes.
|-
| foundations
| CB_RESULT[_NO]_FOUNDATIONS
| Return CB_RESULT_FOUNDATIONS to draw standard foundations (default) or CB_RESULT_NO_FOUNDATIONS to not draw them.
|-
| 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.
|}

===Animation triggers===

{| class="t"
! Trigger
! Meaning
|-
| ANIM_TRIGGER_INDTILE_CONSTRUCTION_STATE
| the construction state changes
|-
| ANIM_TRIGGER_INDTILE_TILE_LOOP
| the tile is processed in the periodic processing loop
|-
| ANIM_TRIGGER_INDTILE_INDUSTRY_LOOP
| the industry of the tile is processed in the periodic processing loop (synchronized for all tiles)
|-
| ANIM_TRIGGER_INDTILE_RECEIVED_CARGO
| the industry of the tile receives input cargo from a station (synchronized for all tiles)
|-
| ANIM_TRIGGER_INDTILE_DISTRIBUTES_CARGO
| the industry distributes its output cargo to one of the stations nearby (synchronized for all tiles)
|}

NML:Vehicles

2011-12-13T22:20:34Z

Yexo: /* Vehicle callbacks */

{{NMLNavPropVarCB}}

==Properties common to all vehicle types==

{| class="t"
! property
! value range
! available for articulated vehicle
! comment
|-
| <code style="color:green">name</code>
| (string)
| yes
| for example <code style="color:darkgreen">string(STR_NAME_HEREFORD_TRAM)</code>
|-
| <code style="color:green">climates_available</code>
| bitmask(CLIMATE_XXX, CLIMATE_YYY, ...)
| set to <code style="color:green">NO_CLIMATES</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}} 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}} 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 articulated vehicle
! comment
|-
| <code style="color:green">sprite_id</code>
| <code style="color:green">SPRITE_ID_NEW_TRAIN</code>
| yes
| Set this property to enable new graphics
|-
| <code style="color:green">speed</code>
| 0 ... 65000 (float, speed units)
| no
| Max speed for engines, speed limit for wagons
|-
| <code style="color:green">misc_flags</code>
| bitmask(TRAIN_FLAG_XXX, ...)
| FLIP should not be set, TILT and MU 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
|
|-
| <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>
|-
| <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 articulated vehicle
! comment
|-
| sprite_id
| SPRITE_ID_NEW_ROADVEH
| yes
| Set this property to enable new graphics
|-
| speed
| 0 ... 514km/h (float, speed units)
| no
|
|-
| misc_flags
| bitmask(ROADVEH_FLAG_XXX, ...)
| partly; tram flag must the same
| The following flags are defined: ROADVEH_FLAG_TRAM, ROADVEH_FLAG_2CC, ROADVEH_FLAG_AUTOREFIT. Use 0 if you don't want to set any of these flags.
|-
| refit_cost
| 0 ... 255
| yes
| in 25% units of the purchase price cost base
|-
| callback_flags
| bitmask(VEH_CBF_XXX, ...)
| yes
|
Do not set this, unless you use [[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
|
|-
| 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
|
|-
| 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
| 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
|
|-
| mail_capacity
| 0 ... 255
|
|-
| 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 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
|
[[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
|-
| vehicle_type_id
|
| No
| ID of 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_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
| Not valid before 1920 and after 2090.
|-
| 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 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==

{| 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
|-
| 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 HEQS 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
|}

NML:Industries

2011-12-13T22:17:06Z

Yexo: /* Industry callbacks */

{{NMLNavPropVarCB}}

This page contains information on both industry and industry tile properties, variables and callbacks.

==Industry properties==

Industry properties. Default industry type numbers can be found at [[NML:Default industries|default industries]].

{| class="t"
! property
! value range
! comment
|-
| substitute
| industry type
| Number of the original industry type that replaces this one, should it not be available for some reason (e.g. missing NewGRF). This ''must'' be the first property to be set, before any other properties or graphics. All properties of the old type are copied to your new industry.
|-
| override
| industry type
| Number of the original industry type overridden. This will cause other grfs / industries to consider your industry type the same as the old type. Only set this property if your type is (more or less) the same as the old type.
|-
| layouts
| Array of tilelayouts
|
See [[NML:Tilelayout|Tilelayout]] syntax.
|-
| life_type
| One of IND_LIFE_TYPE_XXX, XXX = BLACK_HOLE <nowiki>|</nowiki> EXTRACTIVE <nowiki>|</nowiki> ORGANIC <nowiki>|</nowiki> PROCESSING
| The generic type of industry. This determines the production changes that occur by default (when not using the callback). Examples are respectively power plants, coal mines, forests en steel mills.
|-
| closure_msg
| string
|
Message displayed when the industry announces closure. Use a custom string or one of the [[NML:Default TTD strings|default TTD strings]].
|-
| prod_increase_msg
| string
|
Message displayed when industry increases production. Use a custom string or one of the [[NML:Default TTD strings|default TTD strings]].
|-
| prod_decrease_msg
| string
|
Message displayed when industry decreases production. Use a custom string or one of the [[NML:Default TTD strings|default TTD strings]].
|-
| fund_cost_multiplier
| 0..255
| Fund cost multiplier. Note that in OpenTTD the unmodified base cost is 8x higher for building (not prospecting) raw (=extractive / organic, see life_type) industries.
|-
| prod_cargo_types
| array of up to 2 ints
| Types of cargo produced. Use the cargotype(<label>) built-in function to specify a label from the cargotable.
|-
| accept_cargo_types
| array of up to 3 ints
| Types of cargo accepted. Use the cargotype(<label>) built-in function to specify a label from the cargotable
|-
| prod_multiplier
| array of up to 2 ints (0..255)
| Amount of each output cargo to produce every 256 ticks (8 or 9 times a month)
|-
| min_cargo_distr
| 0..255
| Minimal amount of cargo before transporting to stations.
|-
| random_sound_effects
| array of ints
| Sound effect numbers that are played some times.
|-
| conflicting_ind_types
| array of up to 3x industry_type(IND_TYPE_OLD <nowiki>|</nowiki> IND_TYPE_NEW, id)
|
Three industry types that should not be nearby. Use the [[NML:Builtin functions|builtin function]] <code style="color:darkgreen">industry_type(..)</code> to define either an old industry (using the global ID) or a new industry from your grf (using the grf-local ID).
|-
| prob_random
| 0..255
| Probability of occurring while generating initial industries.
|-
| prob_in_game
| 0..255
| Probability of occurring while creating industries during the game.
|-
| map_colour
| 0..255
|
Colour index from the [[NML:Graphic files|DOS palette]] to use on the minimap for this industry.
|-
| spec_flags
| bitmask(flags)
|
for flag values see [[#industry_special_flags|Industry special flags]]
|-
| new_ind_msg
| string
| Message displayed when industry gets built during game play.
|-
| input_multiplier_1
| array of up to 2 floats (0..255)
| Output cargo multiplication factors for getting a unit of the first accepted cargo.
|-
| input_multiplier_2
| array of up to 2 floats (0..255)
| Output cargo multiplication factors for getting a unit of the second accepted cargo.
|-
| input_multiplier_3
| array of up to 2 floats (0..255)
| Output cargo multiplication factors for getting a unit of the third accepted cargo.
|-
| name
| string
|
Name of the industry, use a custom string or one of the [[NML:Default TTD strings|default TTD strings]].
|-
| prospect_chance
| 0 .. 1 (float)
| Chance of successful prospecting.
|-
| callback_flags
| bitmask(flags)
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| remove_cost_multiplier
| int
| Cost multiplier for removing the industry (currently only possible with magic bulldozer).
|-
| nearby_station_name
| string
| Default additional name for a nearby station
|}

===Industry special flags===

{| class="t"
! flag
! meaning
|-
| IND_FLAG_PLANT_FIELDS_PERIODICALLY
| The industry periodically plants fields around itself (temperate and arctic farms)
|-
| IND_FLAG_CUT_TREES
| The industry cuts trees around itself and produces its first output cargo from them (lumber mill)
|-
| IND_FLAG_BUILT_ON_WATER
| The industry is built on water (oil rig)
|-
| IND_FLAG_ONLY_IN_LARGE_TOWNS
| The industry can only be built in towns (i.e. it has to replace houses) with population larger than 1200 (temperate bank)
|-
| IND_FLAG_ONLY_IN_TOWNS
| The industry can only be built in towns (i.e. it has to replace houses) (arctic and tropic banks, water tower)
|-
| IND_FLAG_BUILT_NEAR_TOWN
| The industry is always built near towns (i.e. near town sign; additionally the industry is allowed to replace houses) (toy shop)
|-
| IND_FLAG_PLANT_FIELDS_WHEN_BUILT
| Fields are planted around the industry when it's built (all farms)
|-
| IND_FLAG_NO_PRODUCTION_INCREASE
| The industry cannot increase its production on the temperate climate (oil wells)
|-
| IND_FLAG_BUILT_ONLY_BEFORE_1950
| The industry is built only before 1950 (oil wells)
|-
| IND_FLAG_BUILT_ONLY_AFTER_1960
| The industry is built only after 1960 (oil rig)
|-
| IND_FLAG_AI_CREATES_AIR_AND_SHIP_ROUTES
| AI players will attempt to establish air and ship routes going to this industry (oil rig)
|-
| IND_FLAG_MILITARY_AIRPLANE_CAN_EXPLODE
| The industry can be exploded by a military airplane (oil refinery)
|-
| IND_FLAG_MILITARY_HELICOPTER_CAN_EXPLODE
| The industry can be exploded by a military helicopter (factory)
|-
| IND_FLAG_CAN_CAUSE_SUBSIDENCE
| The industry can cause a subsidence (coal mine)
|-
| IND_FLAG_AUTOMATIC_PRODUCTION_MULTIPLIER
| Automatic production multiplier handing (No industry has this bit set by default.).
|-
| IND_FLAG_RANDOM_BITS_IN_PRODUCTION_CALLBACK
| The production callback needs random bits in var. 10 (No industry has this bit set by default.)
|-
| IND_FLAG_DO_NOT_FORCE_INSTANCE_AT_MAP_GENERATION
| Do not force one instance of this type to appear during initial map generation (No industry has this bit set by default.)
|-
| IND_FLAG_ALLOW_CLOSING_LAST_INSTANCE
| Allow closing down the last instance of this type (No industry has this bit set by default.)
|}

==Industry tile properties==

{| class="t"
! property
! value range
! comment
|-
| substitute
|
[[NML:Default industry tiles|0..174]]
| Number of the default industry tile that replaces this one, if this industry tile is not available for some reason. This property ''must'' be set first, before any other properties or graphics. All properties of the old type are copied to your new house.
|-
| override
|
[[NML:Default industry tiles|0..174]]
| id of the default industry tile which this industry tile replaces. This will cause your industry tile to be placed instead of the default industry tile. This is ignored, if the default industry tile has already been overridden. You can define this property multiple times
|-
| accepted_cargos
| Array with up to 3 [cargo_id, amount]-pairs.
| The cargos that are accepted by this tile. CargoID is a cargo type from your cargo translation table, amount is the acceptance of the given cargo in 1/8 units. Example: to make a tile accept both COAL and IORE you could use this: <code style="color:darkgreen"><nowiki>accepted_cargos: [[COAL, 8], [IORE, 8]];</nowiki></code> Example: for a tile that doesn't any cargos at all you'd use: <code style="color:darkgreen">accepted_cargos: [];</code>
|-
| land_shape_flags
|
bitmask([[#Land shape flags|Land shape flags]])
|
|-
| callback_flags
| bitmask(INDTILE_CBF_XXX, INDTILE_CBF_YYY)
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| 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
| bitmask(ANIM_TRIGGER_INDTILE_XXX, ... )
|
Bitmask of triggers that will trigger the <code style="color:darkgreen">anim_control</code> callback, see the [[#Animation triggers|table]] below.
|-
| special_flags
| bitmask(INDTILE_FLAG_XXX)
| XXX is a special flag description. Currently there's only one flag defined: set INDTILE_FLAG_RANDOM_ANIMATION if the decision in anim_control callback needs random bits via extra_callback_info1
|}

===Land shape flags===

{| class="t"
! Flag
! Meaning
|-
| LSF_CANNOT_LOWER_NW_EDGE
| North-west edge cannot be lowered
|-
| LSF_CANNOT_LOWER_NE_EDGE
| North-east edge cannot be lowered
|-
| LSF_CANNOT_LOWER_SW_EDGE
| South-west edge cannot be lowered
|-
| LSF_CANNOT_LOWER_SE_EDGE
| South-east edge cannot be lowered
|-
| LSF_ONLY_ON_FLAT_LAND
| This tile can only be built on flat land
|-
| LSF_ALLOW_ON_WATER
| The land/water check is disabled for this tile so it can be built on water. If you need more control over this use callback 0x2F.
|}

==Common variables==

The following variables are available to both industries and industry tiles. All of them require an x, y offset. For industries, this offset is unsigned and relative to the northernmost tile. For industry tiles, it is signed and relative to the current tile.

{| class="t"
! name
! value range
! comment
|-
| nearby_tile_slope
| SLOPE_XXX
|
See [[NML:List of tile slopes|tile slopes]] for an overview of possible values
|-
| nearby_tile_is_water
| 1 if the tile is water, 0 otherwise
|
|-
| nearby_tile_terrain_type
| TILETYPE_XX
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|-
| nearby_tile_water_class
| 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
| 0..120
| The height of the lowest corner of the given tile.
|-
| nearby_tile_class
|
[[NML:List of tile classes|Tile class]]
|
|-
| nearby_tile_animation_frame
| 0..255
| Animation frame of the given tile
|-
| nearby_tile_industrytile_id
| 0x00aa, 0xFFbb, 0xFFFE or 0xFFFF
| 0x00aa: The tile is an industry tile that is part of this GRF, the tile id is aa. 0xFFbb: The tile is an original industry tile with id bb. 0xFFFE: The tile is an industry tile defined in another GRF. 0xFFFF: The tile is not an industry tile or it belongs to another GRF.
|}

==Industry variables==

{| class="t"
! name
! value range
! comment
|-
| production_level
| 0, or 4 .. 128
| Current production level of the industry. Usually in range 4 .. 128, default starting level is 16. A level of 0 indicates imminent closure.
|-
| waiting_cargo_1
| 0..65535
| If any of the production callbacks is enabled, this variable will contain the amount of the first cargo type awaiting to be processed.
|-
| waiting_cargo_2
| 0..65535
| If any of the production callbacks is enabled, this variable will contain the amount of the second cargo type awaiting to be processed.
|-
| waiting_cargo_3
| 0..65535
| If any of the production callbacks is enabled, this variable will contain the amount of the third cargo type awaiting to be processed.
|-
| produced_cargo_waiting_1
| 0..65535
| The amount of produced 'output cargo type 1' that this waiting to be transported.
|-
| produced_cargo_waiting_2
| 0..65535
| The amount of produced 'output cargo type 2' that this waiting to be transported.
|-
| produced_this_month_1
| 0..65535
| The amount of 'output cargo type 1' that was produced this month.
|-
| produced_this_month_2
| 0..65535
| The amount of 'output cargo type 2' that was produced this month.
|-
| produced_last_month_1
| 0..65535
| The amount of 'output cargo type 1' that was produced last month.
|-
| produced_last_month_2
| 0..65535
| The amount of 'output cargo type 2' that was produced last month.
|-
| transported_this_month_1
| 0..65535
| The amount of 'output cargo type 1' that was transported this month.
|-
| transported_this_month_2
| 0..65535
| The amount of 'output cargo type 2' that was transported this month.
|-
| transported_last_month_1
| 0..65535
| The amount of 'output cargo type 1' that was produced last month.
|-
| transported_last_month_2
| 0..65535
| The amount of 'output cargo type 2' that was produced last month.
|-
| transported_last_month_pct_1
| 0..100
| Percentage of produced 'output cargo type 1' that was transported last month.
|-
| transported_last_month_pct_2
| 0..100
| Percentage of produced 'output cargo type 2' that was transported last month.
|-
| water_distance
| Distance to the tile
| If the industry is built on water, this variable gives the distance of the closest dry land tile, otherwise it gives the distance of the closest water tile.
|-
| layout_num
| 1..255
| Number of the layout being used by the industry.
|-
| founder
| 0..16
| Company number of the industry founder. It will be FOUNDER_GAME (=16) if the industry was generated randomly. TTDPatch only supports up to 8 companies (0..7).
|-
| founder_type
| PLAYERTYPE_XX
| PLAYERTYPE_HUMAN, PLAYERTYPE_AI, PLAYERTYPE_HUMAN_IN_AI (human managing AI company) or PLAYERTYPE_AI_IN_HUMAN (AI managing human company). OpenTTD only uses PLAYERTYPE_HUMAN and PLAYERTYPE_AI. If you cheat yourself to be part of an AI company OpenTTD will still report PLAYERTYPE_AI for the company with yourself and the AI and it'll report PLAYERTYPE_HUMAN for the now uncontrolled company.
|-
| founder_colour1
| COLOUR_XXX
|
Index of founding company's first colour. 0 if not founded by a company. Refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for possible values.
|-
| founder_colour2
| COLOUR_XXX
|
Index of founding company's second colour. It's the same as company_colour1, if no second company colour is chosen. 0 if not founded by a company. Refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for possible values.
|-
| colour
| COLOUR_XXX
|
Random colour for this industry. Refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for possible values.
|-
| build_date
| 0..1826212865
| Date of the industry foundation in days since year 0.
|-
| build_type
| BUILDTYPE_XX
| BUILDTYPE_UNKNOWN (if created in an old version or with newindustries disabled), BUILDTYPE_GAMEPLAY (if founded or created by the in-game random industry generator), BUILDTYPE_GENERATION (if created during random map generation) or BUILDTYPE_EDITOR (if created with the scenario editor).
|-
| counter
| 0..65535
| Decremented every tick, used to time primary industry production in TTD.
|-
| last_accept_date
| date(year, month, day)
| Date when cargo was accepted for the last time. Not valid before 1920 and after 2090.
|-
| random_bits
| 0 ... 65535
| Random data that can be used to randomize certain descisions. (see [[NML:Random_switch|Random switch]]) (NML r1666)
|}

 Variables that require some parameters.

{| class="t"
! name
! arguments
! comment
|-
| industry_count
| industry_type, grfid = -1
|
The value of this variable is the number of industries of a given type that are currently on the map. industry_type is either the ID of an industry. GRFid is the grf in which the industry was defined. The default value is -1, which means current newgrf. A grfid of 0 lets you check the number of default industries of a given type. Use the [[NML:Builtin functions|builtin function]] <code style="color:darkgreen">str2number()</code> to convert a grfid to its numeric representation. ''Warning: using this variable trashes the contents of temporary storage register 0x100''
|-
| industry_distance
| industry_type, grfid = -1
| The value of this variable is the manhattan distance the closest instance of the given industry or 0xFFFF if not applicable. See industry_count for a description of the parameters. ''Warning: using this variable trashes the contents of temporary storage register 0x100.''
|-
| industry_layout_count / industry_layout_distance
| industry_type, layout, grfid = -1.
| See industry_count / industry_distance for description of industry_type, grfid and return value. The results are filtered to industries that have the given layout number. ''Warning: using this variable trashes the contents of temporary storage registers 0x100 and 0x101.''
|-
| industry_town_count
| industry_type, grfid = -1.
| See industry_count / industry_distance for description of industry_type, grfid and return value. The results are filtered to industries that have the same town than the current industry. ''Warning: using this variable trashes the contents of temporary storage registers 0x100 and 0x101.''
|-
| town_manhattan_dist
| x, y
| Parameters indicate a signed offset relative to the northern tile. Returns the Manhattan distance (dx + dy) from the selected tile to the closest town
|-
| town_euclidean_dist
| x, y
| Parameters indicate a signed offset relative to the northern tile. Returns the squared Eucleidean distance (dx^2 + dy^2) from the selected tile to the closest town.
|-
| town_zone
| x, y
|
Parameters indicate a signed offset relative to the northern tile. Returns the [[NML:List of town zones|town zone]] that the selected tile is in.
|-
| nearby_tile_random_bits
| x, y
| Parameters indicate an unsigned offset relative to the northern tile. Returns the random bits of the selected industry tile, or 0 if it is not an industry tile that's part of this industry.
|}

==Industry tile variables==

{| class="t"
! name
! value range
! comment
|-
| construction_state
| 0..3
| Current construction state of the industry tile.
|-
| terrain_type
| TILETYPE_XX
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|-
| town_zone
|
[[NML:List of town zones|town zone]]
| The town zone of the current tile.
|-
| 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.
|-
| animation_frame
| 0..255
| Current animation frame.
|}

 

Industry tiles have access to the [[#Common variables|common variables]] described above. Additionally, they have access to the following:

{| class="t"
! name
! arguments
! comment
|-
| nearby_tile_is_same_industry
| x, y
| Parameters indicate a signed tile offset relative to the current tile. Returns 1 if the tile is part of the same industry, 0 otherwise
|}

==Industry callbacks==

{| class="t"
! callback
! return value
! comment
|-
| default
| varies
| Any unhandled callbacks. Generally this doesn't need to be used, except for old-style callbacks.
|-
| produce_cargo_arrival
| Produce-block
| Called to produce cargo when it arrives.
|-
| produce_256_ticks
| Produce-block
| Called to produce cargo every 256 ticks.
|-
| availability
| CB_RESULT_IND_ALLOW or CB_RESULT_IND_DISALLOW
|
Called when the game needs to know if the industry type is available. It is limited to the type as a whole, so you can't access industry-specific variables. <code style="color:darkgreen">extra_callback_info2</code> contains the [[#Industry creation types|creation type]].
|-
| location_check
|
See the [[#Location check results|table]] below.
|
Called to check if a location is suitable. <code style="color:darkgreen">extra_callback_info2</code> contains the [[#Industry creation types|creation type]]. Since the industry isn't built yet, industry variables aren't available. If this callback is not implemented or fails, constructing the industry will be allowed. Construction might also be prevented via the <code style="color:darkgreen">tile_check</code> industry tile callback, though.
|-
| monthly_prod_change
|
See [[#Production change callback results|below]]
| Called each month to (possibly) change the industry production. <code style="color:darkgreen">extra_callback_info2</code> contains random bits.
|-
| random_prod_change
|
See [[#Production change callback results|below]]
| Works exactly the same as <code style="color:darkgreen">monthly_prod_change</code>, except that it's only called when TTD selects this industry for a random production change.
|-
| cargo_subtype_display
| String or CB_RESULT_NO_TEXT
| This callback allows displaying some text after a cargo name. Returning CB_RESULT_NO_TEXT displays nothing. The lowest byte of <code style="color:darkgreen">extra_callback_info2</code> contains 0 .. 2 to get texts for the first .. third accepted cargo type, and 3 .. 4 for the first ... second produced cargo type. The second byte contains 0 when getting a string for the buy menu (no industry variables available!), 1 when for the industry window and 2 for the industry directory window.
|-
| extra_text_industry
| String
| Show extra text in the industry window.
|-
| extra_text_fund
| String
| Show extra text in the fund window. Since the industry isn't built, no industry variables are available.
|-
| control_special
| 0 or 1
| Called to control various effects from the <code style="color:darkgreen">spec_flags</code> property. Currently only works for the first two (plant fields / cut trees). Return 1 to execute the action or 0 to not do so. The relevant flag is given in <code style="color:darkgreen">extra_callback_info2</code>. The default (if the flag is enabled, of course) is to plant fields with 1/8th chance every 256 ticks, and to cut trees every 512 ticks. Random bits are supplied in <code style="color:darkgreen">extra_callback_info1</code>.
|-
| stop_accept_cargo
| 0 or 1
| With this callback, you can temporarily refuse accepting a certain cargo, for example because the stockpile is full. Return 1 to accept or 0 to refuse. Make sure to synchronize this callback with the <code style="color:darkgreen">cargo_amount_accept</code> callback for industry tiles. <code style="color:darkgreen">extra_callback_info2</code> contains the cargo type to accept or not.
|-
| colour
| COLOUR_XXX
| Called after constructing the industry. The <code style="color:darkgreen">colour</code> variable is set to a random value at this point, you can use this callback to change this.
|-
| cargo_input
| Cargo type, or 0xFF
| Decide the input cargo types. Called repeatedly until 0xFF is returned, although currently not more than three times. Do not rely on this limitation, though. <code style="color:darkgreen">extra_callback_info1</code> starts at 0 and is incremented for every iteration. Return a cargo type (from the table) or 0xFF to stop.
|-
| cargo_output
| Cargo type, or 0xFF
| Same as <code style="color:darkgreen">cargo_input</code> above, except that it is applied to the output cargo types and currently not called more than twice.
|}

===Location check results===

The following values can be used as return values for the <code style="color:darkgreen">location_check</code> callback for industries
and the <code style="color:darkgreen">tile_check</code> callback for industry tiles and objects.

{| class="t"
! return value
! meaning
|-
| string(..)
| Item can't be built, show the string as error message.
|-
| CB_RESULT_LOCATION_ALLOW
| Item can be built.
|-
| CB_RESULT_LOCATION_DISALLOW
| Item can't be built, display the default error message. This is "site unsuitable" for industries and industry tiles, and "land sloped in wrong direction" for objects.
|-
| CB_RESULT_LOCATION_DISALLOW_ONLY_RAINFOREST
| Item can't be built, display the "...can only be built in rainforest areas" error message.
|-
| CB_RESULT_LOCATION_DISALLOW_ONLY_DESERT
| Item can't be built, display the "...can only be built in desert areas" error message.
|-
| CB_RESULT_LOCATION_DISALLOW_ONLY_ABOVE_SNOWLINE
| Item can't be built, display the "...can only be built above the snow-line" error message.
|-
| CB_RESULT_LOCATION_DISALLOW_ONLY_BELOW_SNOWLINE
| Item can't be built, display the "...can only be built below the snow-line" error message.
|-
| CB_RESULT_LOCATION_DISALLOW_NOT_ON_OPEN_SEA
| Item can't be built, display the "...can't build on open sea" error message.
|-
| CB_RESULT_LOCATION_DISALLOW_NOT_ON_CANAL
| Item can't be built, display the "...can't build on canal" error message
|-
| CB_RESULT_LOCATION_DISALLOW_NOT_ON_RIVER
| Item can't be built, display the "...can't build on river" error message.
|}

===Production change callback results===

{| class="t"
! value
! meaning
|-
| CB_RESULT_IND_PROD_NO_CHANGE
| Do not change industry production
|-
| CB_RESULT_IND_PROD_HALF
| Half industry production. If production goes below a quarter of default, the industry closes.
|-
| CB_RESULT_IND_PROD_DOUBLE
| Double production if it's not 8x default yet.
|-
| CB_RESULT_IND_PROD_CLOSE
| Announce closoure and remove the industry next month.
|-
| CB_RESULT_IND_PROD_RANDOM
| Do a random production change, as if the industry is a primary one.
|-
| CB_RESULT_IND_PROD_DIVIDE_BY_4
| Divide production by 4
|-
| CB_RESULT_IND_PROD_DIVIDE_BY_8
| Divide production by 8
|-
| CB_RESULT_IND_PROD_DIVIDE_BY_16
| Divide production by 16
|-
| CB_RESULT_IND_PROD_DIVIDE_BY_32
| Divide production by 32
|-
| CB_RESULT_IND_PROD_MULTIPLY_BY_4
| Multiply production by 4
|-
| CB_RESULT_IND_PROD_MULTIPLY_BY_8
| Multiply production by 8
|-
| CB_RESULT_IND_PROD_MULTIPLY_BY_16
| Multiply production by 16
|-
| CB_RESULT_IND_PROD_MULTIPLY_BY_32
| Multiply production by 32
|-
| CB_RESULT_IND_PROD_DECREMENT_BY_1
| Decrement production by 1
|-
| CB_RESULT_IND_PROD_INCREMENT_BY_1
| Increment production by 1
|-
| CB_RESULT_IND_PROD_SET_BY_0x100
| Set the production level to the value in bits 16 .. 23 of register 0x100.
|}

Setting bit 7 of the result disables the associated news message. Setting bit 8 replaces the news message with a custom message, read from register 0x100 bits 0 .. 15.

===Industry creation types===

{| class="t"
! value
! meaning
|-
| IND_CREATION_GENERATION
| Industry is created during map generation, or when building 'many random industries' in the scenario editor.
|-
| IND_CREATION_RANDOM
| Industry is randomly generated during gameplay
|-
| IND_CREATION_FUND
| Industry is funded by the player (in game or scenario editor)
|-
| IND_CREATION_PROSPECT
| Industry is prospected by the player
|}

==Industry tile callbacks==

{| class="t"
! callback
! return value
! comment
|-
| default
| Sprite layout
| Graphics for the industry tile
|-
| random_trigger
| N/A
|
See [[NML:Random switch|random switch]] for more information.
|-
| 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 enabled in the <code style="color:darkgreen">special_flags</code> property. Returning a sound effect in the high byte will cause that sound effect to be played.
|-
| anim_control
| Next animation frame or CB_RESULT_XXX
|
Called whenever an 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 enabled in the <code style="color:darkgreen">special_flags</code> property. Returning a sound effect in the high byte will cause that sound effect to be played. <code style="color:darkgreen">extra_callback_info2</code> contains the reason to trigger the animation, see the [[#Animation triggers|table]] below. Note that you need to enable the wanted triggers in the <code style="color:darkgreen">animation_triggers</code> property.
|-
| 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.
|-
| cargo_type_accept
| type1 + (type2 << 5) + (type3 << 10)
| Decide the cargo types that this tile accepts. If this callback is not implemented or fails, the values from <code style="color:darkgreen">accepted_cargos</code> are used instead. Bits 0..4: First cargo type. Bits 5..9: Second cargo type. Bits 10..14: Third cargo type.
|-
| cargo_amount_accept
| amt1 + (amt2 << 4) + (amt3 << 8)
| Acceptance for each cargo amount in 1/8th. If this callback is not implemented or fails, the values from <code style="color:darkgreen">accepted_cargos</code> are used instead. Cargo types are from the <code style="color:darkgreen">cargo_type_accept</code> callback, or the <code style="color:darkgreen">accepted_cargos</code> property if that callback failed. Bits 0..3: Acceptance of first cargo type. Bits 4..7: Acceptance of second cargo type. Bits 8..11: Acceptance of third cargo type.
|-
| tile_check
|
Same as for the [[#Location check results|location_check]] industry callback
|
Called before constructing the industry, so nothing exists on the map yet. Since the industry isn't built yet, so you can't access industry variables. From the tile variables, relative x/y/position, town zone are available, as well as the class, height, slope, terrain type and water status of nearby tiles. <code style="color:darkgreen">extra_callback_info2</code> contains the industry layout number in the lowest (first) byte and the [[#Industry creation types|creation type]] in the second byte. If this callback is not implemented or fails, the <code style="color:darkgreen">land_shape_flags</code> property will be used instead to determine if the slope is suitable. This also means that without this callback, the tile may not be built on steep slopes.
|-
| foundations
| CB_RESULT[_NO]_FOUNDATIONS
| Return CB_RESULT_FOUNDATIONS to draw standard foundations (default) or CB_RESULT_NO_FOUNDATIONS to not draw them.
|-
| 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.
|}

===Animation triggers===

{| class="t"
! Trigger
! Meaning
|-
| ANIM_TRIGGER_INDTILE_CONSTRUCTION_STATE
| the construction state changes
|-
| ANIM_TRIGGER_INDTILE_TILE_LOOP
| the tile is processed in the periodic processing loop
|-
| ANIM_TRIGGER_INDTILE_INDUSTRY_LOOP
| the industry of the tile is processed in the periodic processing loop (synchronized for all tiles)
|-
| ANIM_TRIGGER_INDTILE_RECEIVED_CARGO
| the industry of the tile receives input cargo from a station (synchronized for all tiles)
|-
| ANIM_TRIGGER_INDTILE_DISTRIBUTES_CARGO
| the industry distributes its output cargo to one of the stations nearby (synchronized for all tiles)
|}

NML:Industries

2011-12-11T18:38:19Z

Yexo: Fix range for prob_random / prob_in_game

{{NMLNavPropVarCB}}

This page contains information on both industry and industry tile properties, variables and callbacks.

==Industry properties==

Industry properties. Default industry type numbers can be found at [[NML:Default industries|default industries]].

{| class="t"
! property
! value range
! comment
|-
| substitute
| industry type
| Number of the original industry type that replaces this one, should it not be available for some reason (e.g. missing NewGRF). This ''must'' be the first property to be set, before any other properties or graphics. All properties of the old type are copied to your new industry.
|-
| override
| industry type
| Number of the original industry type overridden. This will cause other grfs / industries to consider your industry type the same as the old type. Only set this property if your type is (more or less) the same as the old type.
|-
| layouts
| Array of tilelayouts
|
See [[NML:Tilelayout|Tilelayout]] syntax.
|-
| life_type
| One of IND_LIFE_TYPE_XXX, XXX = BLACK_HOLE <nowiki>|</nowiki> EXTRACTIVE <nowiki>|</nowiki> ORGANIC <nowiki>|</nowiki> PROCESSING
| The generic type of industry. This determines the production changes that occur by default (when not using the callback). Examples are respectively power plants, coal mines, forests en steel mills.
|-
| closure_msg
| string
|
Message displayed when the industry announces closure. Use a custom string or one of the [[NML:Default TTD strings|default TTD strings]].
|-
| prod_increase_msg
| string
|
Message displayed when industry increases production. Use a custom string or one of the [[NML:Default TTD strings|default TTD strings]].
|-
| prod_decrease_msg
| string
|
Message displayed when industry decreases production. Use a custom string or one of the [[NML:Default TTD strings|default TTD strings]].
|-
| fund_cost_multiplier
| 0..255
| Fund cost multiplier. Note that in OpenTTD the unmodified base cost is 8x higher for building (not prospecting) raw (=extractive / organic, see life_type) industries.
|-
| prod_cargo_types
| array of up to 2 ints
| Types of cargo produced. Use the cargotype(<label>) built-in function to specify a label from the cargotable.
|-
| accept_cargo_types
| array of up to 3 ints
| Types of cargo accepted. Use the cargotype(<label>) built-in function to specify a label from the cargotable
|-
| prod_multiplier
| array of up to 2 ints (0..255)
| Amount of each output cargo to produce every 256 ticks (8 or 9 times a month)
|-
| min_cargo_distr
| 0..255
| Minimal amount of cargo before transporting to stations.
|-
| random_sound_effects
| array of ints
| Sound effect numbers that are played some times.
|-
| conflicting_ind_types
| array of up to 3x industry_type(IND_TYPE_OLD <nowiki>|</nowiki> IND_TYPE_NEW, id)
|
Three industry types that should not be nearby. Use the [[NML:Builtin functions|builtin function]] <code style="color:darkgreen">industry_type(..)</code> to define either an old industry (using the global ID) or a new industry from your grf (using the grf-local ID).
|-
| prob_random
| 0..255
| Probability of occurring while generating initial industries.
|-
| prob_in_game
| 0..255
| Probability of occurring while creating industries during the game.
|-
| map_colour
| 0..255
|
Colour index from the [[NML:Graphic files|DOS palette]] to use on the minimap for this industry.
|-
| spec_flags
| bitmask(flags)
|
for flag values see [[#industry_special_flags|Industry special flags]]
|-
| new_ind_msg
| string
| Message displayed when industry gets built during game play.
|-
| input_multiplier_1
| array of up to 2 floats (0..255)
| Output cargo multiplication factors for getting a unit of the first accepted cargo.
|-
| input_multiplier_2
| array of up to 2 floats (0..255)
| Output cargo multiplication factors for getting a unit of the second accepted cargo.
|-
| input_multiplier_3
| array of up to 2 floats (0..255)
| Output cargo multiplication factors for getting a unit of the third accepted cargo.
|-
| name
| string
|
Name of the industry, use a custom string or one of the [[NML:Default TTD strings|default TTD strings]].
|-
| prospect_chance
| 0 .. 1 (float)
| Chance of successful prospecting.
|-
| callback_flags
| bitmask(flags)
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| remove_cost_multiplier
| int
| Cost multiplier for removing the industry (currently only possible with magic bulldozer).
|-
| nearby_station_name
| string
| Default additional name for a nearby station
|}

===Industry special flags===

{| class="t"
! flag
! meaning
|-
| IND_FLAG_PLANT_FIELDS_PERIODICALLY
| The industry periodically plants fields around itself (temperate and arctic farms)
|-
| IND_FLAG_CUT_TREES
| The industry cuts trees around itself and produces its first output cargo from them (lumber mill)
|-
| IND_FLAG_BUILT_ON_WATER
| The industry is built on water (oil rig)
|-
| IND_FLAG_ONLY_IN_LARGE_TOWNS
| The industry can only be built in towns (i.e. it has to replace houses) with population larger than 1200 (temperate bank)
|-
| IND_FLAG_ONLY_IN_TOWNS
| The industry can only be built in towns (i.e. it has to replace houses) (arctic and tropic banks, water tower)
|-
| IND_FLAG_BUILT_NEAR_TOWN
| The industry is always built near towns (i.e. near town sign; additionally the industry is allowed to replace houses) (toy shop)
|-
| IND_FLAG_PLANT_FIELDS_WHEN_BUILT
| Fields are planted around the industry when it's built (all farms)
|-
| IND_FLAG_NO_PRODUCTION_INCREASE
| The industry cannot increase its production on the temperate climate (oil wells)
|-
| IND_FLAG_BUILT_ONLY_BEFORE_1950
| The industry is built only before 1950 (oil wells)
|-
| IND_FLAG_BUILT_ONLY_AFTER_1960
| The industry is built only after 1960 (oil rig)
|-
| IND_FLAG_AI_CREATES_AIR_AND_SHIP_ROUTES
| AI players will attempt to establish air and ship routes going to this industry (oil rig)
|-
| IND_FLAG_MILITARY_AIRPLANE_CAN_EXPLODE
| The industry can be exploded by a military airplane (oil refinery)
|-
| IND_FLAG_MILITARY_HELICOPTER_CAN_EXPLODE
| The industry can be exploded by a military helicopter (factory)
|-
| IND_FLAG_CAN_CAUSE_SUBSIDENCE
| The industry can cause a subsidence (coal mine)
|-
| IND_FLAG_AUTOMATIC_PRODUCTION_MULTIPLIER
| Automatic production multiplier handing (No industry has this bit set by default.).
|-
| IND_FLAG_RANDOM_BITS_IN_PRODUCTION_CALLBACK
| The production callback needs random bits in var. 10 (No industry has this bit set by default.)
|-
| IND_FLAG_DO_NOT_FORCE_INSTANCE_AT_MAP_GENERATION
| Do not force one instance of this type to appear during initial map generation (No industry has this bit set by default.)
|-
| IND_FLAG_ALLOW_CLOSING_LAST_INSTANCE
| Allow closing down the last instance of this type (No industry has this bit set by default.)
|}

==Industry tile properties==

{| class="t"
! property
! value range
! comment
|-
| substitute
|
[[NML:Default industry tiles|0..174]]
| Number of the default industry tile that replaces this one, if this industry tile is not available for some reason. This property ''must'' be set first, before any other properties or graphics. All properties of the old type are copied to your new house.
|-
| override
|
[[NML:Default industry tiles|0..174]]
| id of the default industry tile which this industry tile replaces. This will cause your industry tile to be placed instead of the default industry tile. This is ignored, if the default industry tile has already been overridden. You can define this property multiple times
|-
| accepted_cargos
| Array with up to 3 [cargo_id, amount]-pairs.
| The cargos that are accepted by this tile. CargoID is a cargo type from your cargo translation table, amount is the acceptance of the given cargo in 1/8 units. Example: to make a tile accept both COAL and IORE you could use this: <code style="color:darkgreen"><nowiki>accepted_cargos: [[COAL, 8], [IORE, 8]];</nowiki></code> Example: for a tile that doesn't any cargos at all you'd use: <code style="color:darkgreen">accepted_cargos: [];</code>
|-
| land_shape_flags
|
bitmask([[#Land shape flags|Land shape flags]])
|
|-
| callback_flags
| bitmask(INDTILE_CBF_XXX, INDTILE_CBF_YYY)
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| 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
| bitmask(ANIM_TRIGGER_INDTILE_XXX, ... )
|
Bitmask of triggers that will trigger the <code style="color:darkgreen">anim_control</code> callback, see the [[#Animation triggers|table]] below.
|-
| special_flags
| bitmask(INDTILE_FLAG_XXX)
| XXX is a special flag description. Currently there's only one flag defined: set INDTILE_FLAG_RANDOM_ANIMATION if the decision in anim_control callback needs random bits via extra_callback_info1
|}

===Land shape flags===

{| class="t"
! Flag
! Meaning
|-
| LSF_CANNOT_LOWER_NW_EDGE
| North-west edge cannot be lowered
|-
| LSF_CANNOT_LOWER_NE_EDGE
| North-east edge cannot be lowered
|-
| LSF_CANNOT_LOWER_SW_EDGE
| South-west edge cannot be lowered
|-
| LSF_CANNOT_LOWER_SE_EDGE
| South-east edge cannot be lowered
|-
| LSF_ONLY_ON_FLAT_LAND
| This tile can only be built on flat land
|-
| LSF_ALLOW_ON_WATER
| The land/water check is disabled for this tile so it can be built on water. If you need more control over this use callback 0x2F.
|}

==Common variables==

The following variables are available to both industries and industry tiles. All of them require an x, y offset. For industries, this offset is unsigned and relative to the northernmost tile. For industry tiles, it is signed and relative to the current tile.

{| class="t"
! name
! value range
! comment
|-
| nearby_tile_slope
| SLOPE_XXX
|
See [[NML:List of tile slopes|tile slopes]] for an overview of possible values
|-
| nearby_tile_is_water
| 1 if the tile is water, 0 otherwise
|
|-
| nearby_tile_terrain_type
| TILETYPE_XX
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|-
| nearby_tile_water_class
| 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
| 0..120
| The height of the lowest corner of the given tile.
|-
| nearby_tile_class
|
[[NML:List of tile classes|Tile class]]
|
|-
| nearby_tile_animation_frame
| 0..255
| Animation frame of the given tile
|-
| nearby_tile_industrytile_id
| 0x00aa, 0xFFbb, 0xFFFE or 0xFFFF
| 0x00aa: The tile is an industry tile that is part of this GRF, the tile id is aa. 0xFFbb: The tile is an original industry tile with id bb. 0xFFFE: The tile is an industry tile defined in another GRF. 0xFFFF: The tile is not an industry tile or it belongs to another GRF.
|}

==Industry variables==

{| class="t"
! name
! value range
! comment
|-
| production_level
| 0, or 4 .. 128
| Current production level of the industry. Usually in range 4 .. 128, default starting level is 16. A level of 0 indicates imminent closure.
|-
| waiting_cargo_1
| 0..65535
| If any of the production callbacks is enabled, this variable will contain the amount of the first cargo type awaiting to be processed.
|-
| waiting_cargo_2
| 0..65535
| If any of the production callbacks is enabled, this variable will contain the amount of the second cargo type awaiting to be processed.
|-
| waiting_cargo_3
| 0..65535
| If any of the production callbacks is enabled, this variable will contain the amount of the third cargo type awaiting to be processed.
|-
| produced_cargo_waiting_1
| 0..65535
| The amount of produced 'output cargo type 1' that this waiting to be transported.
|-
| produced_cargo_waiting_2
| 0..65535
| The amount of produced 'output cargo type 2' that this waiting to be transported.
|-
| produced_this_month_1
| 0..65535
| The amount of 'output cargo type 1' that was produced this month.
|-
| produced_this_month_2
| 0..65535
| The amount of 'output cargo type 2' that was produced this month.
|-
| produced_last_month_1
| 0..65535
| The amount of 'output cargo type 1' that was produced last month.
|-
| produced_last_month_2
| 0..65535
| The amount of 'output cargo type 2' that was produced last month.
|-
| transported_this_month_1
| 0..65535
| The amount of 'output cargo type 1' that was transported this month.
|-
| transported_this_month_2
| 0..65535
| The amount of 'output cargo type 2' that was transported this month.
|-
| transported_last_month_1
| 0..65535
| The amount of 'output cargo type 1' that was produced last month.
|-
| transported_last_month_2
| 0..65535
| The amount of 'output cargo type 2' that was produced last month.
|-
| transported_last_month_pct_1
| 0..100
| Percentage of produced 'output cargo type 1' that was transported last month.
|-
| transported_last_month_pct_2
| 0..100
| Percentage of produced 'output cargo type 2' that was transported last month.
|-
| water_distance
| Distance to the tile
| If the industry is built on water, this variable gives the distance of the closest dry land tile, otherwise it gives the distance of the closest water tile.
|-
| layout_num
| 1..255
| Number of the layout being used by the industry.
|-
| founder
| 0..16
| Company number of the industry founder. It will be FOUNDER_GAME (=16) if the industry was generated randomly. TTDPatch only supports up to 8 companies (0..7).
|-
| founder_type
| PLAYERTYPE_XX
| PLAYERTYPE_HUMAN, PLAYERTYPE_AI, PLAYERTYPE_HUMAN_IN_AI (human managing AI company) or PLAYERTYPE_AI_IN_HUMAN (AI managing human company). OpenTTD only uses PLAYERTYPE_HUMAN and PLAYERTYPE_AI. If you cheat yourself to be part of an AI company OpenTTD will still report PLAYERTYPE_AI for the company with yourself and the AI and it'll report PLAYERTYPE_HUMAN for the now uncontrolled company.
|-
| founder_colour1
| COLOUR_XXX
|
Index of founding company's first colour. 0 if not founded by a company. Refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for possible values.
|-
| founder_colour2
| COLOUR_XXX
|
Index of founding company's second colour. It's the same as company_colour1, if no second company colour is chosen. 0 if not founded by a company. Refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for possible values.
|-
| colour
| COLOUR_XXX
|
Random colour for this industry. Refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for possible values.
|-
| build_date
| 0..1826212865
| Date of the industry foundation in days since year 0.
|-
| build_type
| BUILDTYPE_XX
| BUILDTYPE_UNKNOWN (if created in an old version or with newindustries disabled), BUILDTYPE_GAMEPLAY (if founded or created by the in-game random industry generator), BUILDTYPE_GENERATION (if created during random map generation) or BUILDTYPE_EDITOR (if created with the scenario editor).
|-
| counter
| 0..65535
| Decremented every tick, used to time primary industry production in TTD.
|-
| last_accept_date
| date(year, month, day)
| Date when cargo was accepted for the last time. Not valid before 1920 and after 2090.
|-
| random_bits
| 0 ... 65535
| Random data that can be used to randomize certain descisions. (see [[NML:Random_switch|Random switch]]) (NML r1666)
|}

 Variables that require some parameters.

{| class="t"
! name
! arguments
! comment
|-
| industry_count
| industry_type, grfid = -1
|
The value of this variable is the number of industries of a given type that are currently on the map. industry_type is either the ID of an industry. GRFid is the grf in which the industry was defined. The default value is -1, which means current newgrf. A grfid of 0 lets you check the number of default industries of a given type. Use the [[NML:Builtin functions|builtin function]] <code style="color:darkgreen">str2number()</code> to convert a grfid to its numeric representation. ''Warning: using this variable trashes the contents of temporary storage register 0x100''
|-
| industry_distance
| industry_type, grfid = -1
| The value of this variable is the manhattan distance the closest instance of the given industry or 0xFFFF if not applicable. See industry_count for a description of the parameters. ''Warning: using this variable trashes the contents of temporary storage register 0x100.''
|-
| industry_layout_count / industry_layout_distance
| industry_type, layout, grfid = -1.
| See industry_count / industry_distance for description of industry_type, grfid and return value. The results are filtered to industries that have the given layout number. ''Warning: using this variable trashes the contents of temporary storage registers 0x100 and 0x101.''
|-
| industry_town_count
| industry_type, grfid = -1.
| See industry_count / industry_distance for description of industry_type, grfid and return value. The results are filtered to industries that have the same town than the current industry. ''Warning: using this variable trashes the contents of temporary storage registers 0x100 and 0x101.''
|-
| town_manhattan_dist
| x, y
| Parameters indicate a signed offset relative to the northern tile. Returns the Manhattan distance (dx + dy) from the selected tile to the closest town
|-
| town_euclidean_dist
| x, y
| Parameters indicate a signed offset relative to the northern tile. Returns the squared Eucleidean distance (dx^2 + dy^2) from the selected tile to the closest town.
|-
| town_zone
| x, y
|
Parameters indicate a signed offset relative to the northern tile. Returns the [[NML:List of town zones|town zone]] that the selected tile is in.
|-
| nearby_tile_random_bits
| x, y
| Parameters indicate an unsigned offset relative to the northern tile. Returns the random bits of the selected industry tile, or 0 if it is not an industry tile that's part of this industry.
|}

==Industry tile variables==

{| class="t"
! name
! value range
! comment
|-
| construction_state
| 0..3
| Current construction state of the industry tile.
|-
| terrain_type
| TILETYPE_XX
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|-
| town_zone
|
[[NML:List of town zones|town zone]]
| The town zone of the current tile.
|-
| 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.
|-
| animation_frame
| 0..255
| Current animation frame.
|}

 

Industry tiles have access to the [[#Common variables|common variables]] described above. Additionally, they have access to the following:

{| class="t"
! name
! arguments
! comment
|-
| nearby_tile_is_same_industry
| x, y
| Parameters indicate a signed tile offset relative to the current tile. Returns 1 if the tile is part of the same industry, 0 otherwise
|}

==Industry callbacks==

{| class="t"
! callback
! return value
! comment
|-
| default
| varies
| Any unhandled callbacks. Generally this doesn't need to be used, except for old-style callbacks.
|-
| produce_cargo_arrival
| Produce-block
| Called to produce cargo when it arrives.
|-
| produce_256_ticks
| Produce-block
| Called to produce cargo every 256 ticks.
|-
| availability
| CB_RESULT_IND_ALLOW or CB_RESULT_IND_DISALLOW
|
Called when the game needs to know if the industry type is available. It is limited to the type as a whole, so you can't access industry-specific variables. <code style="color:darkgreen">extra_callback_info2</code> contains the [[#Industry creation types|creation type]].
|-
| location_check
|
See the [[#Location check results|table]] below.
|
Called to check if a location is suitable. <code style="color:darkgreen">extra_callback_info2</code> contains the [[#Industry creation types|creation type]]. Since the industry isn't built yet, industry variables aren't available. If this callback is not implemented or fails, constructing the industry will be allowed. Construction might also be prevented via the <code style="color:darkgreen">tile_check</code> industry tile callback, though.
|-
| monthly_prod_change
|
See [[#Production change callback results|below]]
| Called each month to (possibly) change the industry production. <code style="color:darkgreen">extra_callback_info2</code> contains random bits.
|-
| random_prod_change
|
See [[#Production change callback results|below]]
| Works exactly the same as <code style="color:darkgreen">monthly_prod_change</code>, except that it's only called when TTD selects this industry for a random production change.
|-
| cargo_subtype_display
| String or 0xFF
| This callback allows displaying some text after a cargo name. Returning 0xFF displays nothing. The lowest byte of <code style="color:darkgreen">extra_callback_info2</code> contains 0 .. 2 to get texts for the first .. third accepted cargo type, and 3 .. 4 for the first ... second produced cargo type. The second byte contains 0 when getting a string for the buy menu (no industry variables available!), 1 when for the industry window and 2 for the industry directory window.
|-
| extra_text_industry
| String
| Show extra text in the industry window.
|-
| extra_text_fund
| String
| Show extra text in the fund window. Since the industry isn't built, no industry variables are available.
|-
| control_special
| 0 or 1
| Called to control various effects from the <code style="color:darkgreen">spec_flags</code> property. Currently only works for the first two (plant fields / cut trees). Return 1 to execute the action or 0 to not do so. The relevant flag is given in <code style="color:darkgreen">extra_callback_info2</code>. The default (if the flag is enabled, of course) is to plant fields with 1/8th chance every 256 ticks, and to cut trees every 512 ticks. Random bits are supplied in <code style="color:darkgreen">extra_callback_info1</code>.
|-
| stop_accept_cargo
| 0 or 1
| With this callback, you can temporarily refuse accepting a certain cargo, for example because the stockpile is full. Return 1 to accept or 0 to refuse. Make sure to synchronize this callback with the <code style="color:darkgreen">cargo_amount_accept</code> callback for industry tiles. <code style="color:darkgreen">extra_callback_info2</code> contains the cargo type to accept or not.
|-
| colour
| COLOUR_XXX
| Called after constructing the industry. The <code style="color:darkgreen">colour</code> variable is set to a random value at this point, you can use this callback to change this.
|-
| cargo_input
| Cargo type, or 0xFF
| Decide the input cargo types. Called repeatedly until 0xFF is returned, although currently not more than three times. Do not rely on this limitation, though. <code style="color:darkgreen">extra_callback_info1</code> starts at 0 and is incremented for every iteration. Return a cargo type (from the table) or 0xFF to stop.
|-
| cargo_output
| Cargo type, or 0xFF
| Same as <code style="color:darkgreen">cargo_input</code> above, except that it is applied to the output cargo types and currently not called more than twice.
|}

===Location check results===

The following values can be used as return values for the <code style="color:darkgreen">location_check</code> callback for industries
and the <code style="color:darkgreen">tile_check</code> callback for industry tiles and objects.

{| class="t"
! return value
! meaning
|-
| string(..)
| Item can't be built, show the string as error message.
|-
| CB_RESULT_LOCATION_ALLOW
| Item can be built.
|-
| CB_RESULT_LOCATION_DISALLOW
| Item can't be built, display the default error message. This is "site unsuitable" for industries and industry tiles, and "land sloped in wrong direction" for objects.
|-
| CB_RESULT_LOCATION_DISALLOW_ONLY_RAINFOREST
| Item can't be built, display the "...can only be built in rainforest areas" error message.
|-
| CB_RESULT_LOCATION_DISALLOW_ONLY_DESERT
| Item can't be built, display the "...can only be built in desert areas" error message.
|-
| CB_RESULT_LOCATION_DISALLOW_ONLY_ABOVE_SNOWLINE
| Item can't be built, display the "...can only be built above the snow-line" error message.
|-
| CB_RESULT_LOCATION_DISALLOW_ONLY_BELOW_SNOWLINE
| Item can't be built, display the "...can only be built below the snow-line" error message.
|-
| CB_RESULT_LOCATION_DISALLOW_NOT_ON_OPEN_SEA
| Item can't be built, display the "...can't build on open sea" error message.
|-
| CB_RESULT_LOCATION_DISALLOW_NOT_ON_CANAL
| Item can't be built, display the "...can't build on canal" error message
|-
| CB_RESULT_LOCATION_DISALLOW_NOT_ON_RIVER
| Item can't be built, display the "...can't build on river" error message.
|}

===Production change callback results===

{| class="t"
! value
! meaning
|-
| CB_RESULT_IND_PROD_NO_CHANGE
| Do not change industry production
|-
| CB_RESULT_IND_PROD_HALF
| Half industry production. If production goes below a quarter of default, the industry closes.
|-
| CB_RESULT_IND_PROD_DOUBLE
| Double production if it's not 8x default yet.
|-
| CB_RESULT_IND_PROD_CLOSE
| Announce closoure and remove the industry next month.
|-
| CB_RESULT_IND_PROD_RANDOM
| Do a random production change, as if the industry is a primary one.
|-
| CB_RESULT_IND_PROD_DIVIDE_BY_4
| Divide production by 4
|-
| CB_RESULT_IND_PROD_DIVIDE_BY_8
| Divide production by 8
|-
| CB_RESULT_IND_PROD_DIVIDE_BY_16
| Divide production by 16
|-
| CB_RESULT_IND_PROD_DIVIDE_BY_32
| Divide production by 32
|-
| CB_RESULT_IND_PROD_MULTIPLY_BY_4
| Multiply production by 4
|-
| CB_RESULT_IND_PROD_MULTIPLY_BY_8
| Multiply production by 8
|-
| CB_RESULT_IND_PROD_MULTIPLY_BY_16
| Multiply production by 16
|-
| CB_RESULT_IND_PROD_MULTIPLY_BY_32
| Multiply production by 32
|-
| CB_RESULT_IND_PROD_DECREMENT_BY_1
| Decrement production by 1
|-
| CB_RESULT_IND_PROD_INCREMENT_BY_1
| Increment production by 1
|-
| CB_RESULT_IND_PROD_SET_BY_0x100
| Set the production level to the value in bits 16 .. 23 of register 0x100.
|}

Setting bit 7 of the result disables the associated news message. Setting bit 8 replaces the news message with a custom message, read from register 0x100 bits 0 .. 15.

===Industry creation types===

{| class="t"
! value
! meaning
|-
| IND_CREATION_GENERATION
| Industry is created during map generation, or when building 'many random industries' in the scenario editor.
|-
| IND_CREATION_RANDOM
| Industry is randomly generated during gameplay
|-
| IND_CREATION_FUND
| Industry is funded by the player (in game or scenario editor)
|-
| IND_CREATION_PROSPECT
| Industry is prospected by the player
|}

==Industry tile callbacks==

{| class="t"
! callback
! return value
! comment
|-
| default
| Sprite layout
| Graphics for the industry tile
|-
| random_trigger
| N/A
|
See [[NML:Random switch|random switch]] for more information.
|-
| 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 enabled in the <code style="color:darkgreen">special_flags</code> property. Returning a sound effect in the high byte will cause that sound effect to be played.
|-
| anim_control
| Next animation frame or CB_RESULT_XXX
|
Called whenever an 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 enabled in the <code style="color:darkgreen">special_flags</code> property. Returning a sound effect in the high byte will cause that sound effect to be played. <code style="color:darkgreen">extra_callback_info2</code> contains the reason to trigger the animation, see the [[#Animation triggers|table]] below. Note that you need to enable the wanted triggers in the <code style="color:darkgreen">animation_triggers</code> property.
|-
| 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.
|-
| cargo_type_accept
| type1 + (type2 << 5) + (type3 << 10)
| Decide the cargo types that this tile accepts. If this callback is not implemented or fails, the values from <code style="color:darkgreen">accepted_cargos</code> are used instead. Bits 0..4: First cargo type. Bits 5..9: Second cargo type. Bits 10..14: Third cargo type.
|-
| cargo_amount_accept
| amt1 + (amt2 << 4) + (amt3 << 8)
| Acceptance for each cargo amount in 1/8th. If this callback is not implemented or fails, the values from <code style="color:darkgreen">accepted_cargos</code> are used instead. Cargo types are from the <code style="color:darkgreen">cargo_type_accept</code> callback, or the <code style="color:darkgreen">accepted_cargos</code> property if that callback failed. Bits 0..3: Acceptance of first cargo type. Bits 4..7: Acceptance of second cargo type. Bits 8..11: Acceptance of third cargo type.
|-
| tile_check
|
Same as for the [[#Location check results|location_check]] industry callback
|
Called before constructing the industry, so nothing exists on the map yet. Since the industry isn't built yet, so you can't access industry variables. From the tile variables, relative x/y/position, town zone are available, as well as the class, height, slope, terrain type and water status of nearby tiles. <code style="color:darkgreen">extra_callback_info2</code> contains the industry layout number in the lowest (first) byte and the [[#Industry creation types|creation type]] in the second byte. If this callback is not implemented or fails, the <code style="color:darkgreen">land_shape_flags</code> property will be used instead to determine if the slope is suitable. This also means that without this callback, the tile may not be built on steep slopes.
|-
| foundations
| CB_RESULT[_NO]_FOUNDATIONS
| Return CB_RESULT_FOUNDATIONS to draw standard foundations (default) or CB_RESULT_NO_FOUNDATIONS to not draw them.
|-
| 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.
|}

===Animation triggers===

{| class="t"
! Trigger
! Meaning
|-
| ANIM_TRIGGER_INDTILE_CONSTRUCTION_STATE
| the construction state changes
|-
| ANIM_TRIGGER_INDTILE_TILE_LOOP
| the tile is processed in the periodic processing loop
|-
| ANIM_TRIGGER_INDTILE_INDUSTRY_LOOP
| the industry of the tile is processed in the periodic processing loop (synchronized for all tiles)
|-
| ANIM_TRIGGER_INDTILE_RECEIVED_CARGO
| the industry of the tile receives input cargo from a station (synchronized for all tiles)
|-
| ANIM_TRIGGER_INDTILE_DISTRIBUTES_CARGO
| the industry distributes its output cargo to one of the stations nearby (synchronized for all tiles)
|}

NML:GRF

2011-12-11T13:05:52Z

Yexo: Document "url" property in grf-block

{{NMLNavBlocksyntax}}

== GRF block ==

Syntax:

grf {
grfid: <literal-string>;
name: <string>;
desc: <string>;
[url: <string>;
version: <expression>;
min_compatible_version: <expression>;
[param { ... }]
}

== GRF parameters ==

As part of the grf block you can specify some parameter settings that the user will be able to change as part of the newgrf configuration. These can for example be used to disable parts of your NewGRF or to change between multiple graphics in case that's not possible at runtime. In general the settings (sub-)block looks like

param <num> {
<name> {
type: <type>;
name: <string>;
desc: <string>;
min_value: <expression>;
max_value: <expression>;
def_value: <expression>;
bit: <expression>;
names: {
0: <string>;
1: <string>;
.
.
.
};
}
}

Looking at the single entries:

<num>

Optional, you can specify in which param number this setting should be stored.

type

This defines the parameter type. Possible values are <code style="color:darkgreen">bool</code> for on/off statements or <code style="color:darkgreen">int</code> for positive integer values

name

This gives the parameter name as shown in the parameter configuration dialogue of OpenTTD.

desc

This gives the description which is displayed when the parameter is selected. Here you can explain the meaning and impact it will have

min_value

The minimum acceptable value for the parameter (only valid for type int), default of min_value is 0

max_value

The maximum acceptable value for the parameter (only valid for type int), default of max_value = 0xFFFFFFFF

def_value

This sets the default value for this parameter. If left out, the default value of 0 will be used.

bit

Only valid for settings with type "bool". The value is the bit in which this setting should be stored.

names

If you chose type <code style="color:darkgreen">int</code> and the numbers themselves are only used internally, have no direct numerical meaning and are better explained in words, you can use this to associate the single numbers with a string which describes it and is shown to the user instead of the value.

== A simple example ==

<pre style=example>
grf {
grfid: "AB\03\02";
name: string(STR_GRF_NAME);
desc: string(STR_GRF_DESC);
version: 1;
min_compatible_version: 0;
param {
param_provide {
type: int;
name: string(STR_PARAM_PROVIDE);
desc: string(STR_PARAM_PROVIDE_DESC);
min_value: 0;
max_value: 1;
def_value: 0;
names: {
0: string(STR_PARAM_PROVIDE_ENGINES_AND_WAGONS);
1: string(STR_PARAM_PROVIDE_WAGONS_ONLY);
};
}
}
}</pre>

Action14

2011-12-11T13:03:19Z

Yexo: Document "INFO"->"URL_"

'''''Static GRF Information'''''

== Introduction ==

Static GRF Information

This action allows to specify additional information about the GRF. Every piece of information is considered optional and non-essential, thus OpenTTD/TTDPatch will ignore unknown parts and not display any error. The action is also meant to allow interfacing non-official extensions/patches for OpenTTD.

Currently this action can be used to define
* {{ottdp|1.1|no|ottdrev=r20250}} translations for the name and description of the GRF. (Those from action 8)
* {{ottdp|1.1|no|ottdrev=r20254}} the palette (DOS, Windows) the GRF needs, or whether the palette does not matter.
* {{ottdp|1.2|no|ottdrev=r23001}} the colour depth (8bpp, 32bpp) the GRF needs
* {{ottdp|1.1|no|ottdrev=r20255}} the number, format and purpose of GRF parameters. (allowed values, names, descriptions, ...)
* {{ottdp|1.1|no|ottdrev=r20960}} version information and compatibility to older versions of the same GRF.
* {{ottdp|1.2|no|ottdrev=r23494}} website url that can be opened in-game.

The action itself is available since OpenTTD r20250. TTDPatch ignores the action since r2334, so no skipping is needed. The action is only allowed for GRF version 7 or above.

The action is processed while scanning for GRFs and their action 8 descriptions. This scanning stops when encountering an action 8, thus action 14 needs to appear earlier in the GRF.

== Syntax ==

The data is provided using nestable chunks, and looks as follows:

<pre><sprite-number> * <length> 14 <chunks ...> 00</pre>

Where <chunks ...> is one or a sequence of

<pre>"C" <identifier> <chunks ...> 00</pre>

<pre>"B" <identifier> <length> <binary-data></pre>

<pre>"T" <identifier> <language-id> <text> 00</pre>

These three types of chunks define branch nodes (containers) and binary and textual leafs in a tree-like information structure. A piece of information is identified by the path in the information tree. E.g. the text leaf node at "INFO" -> "DESC" provides translatable descriptions for the GRF. It does not matter how many action 14 appear in a GRF, and which information is defined in which. Information with different identifier paths or same identifier paths (but e.g. different language-ids) can be set in the same action 14 or in multiple. If information is assigned to the same identifier-path multiple times, the information adds up resp. the last set information wins.

Chunks with unknown identifiers are just skipped including their subchunks. Following chunks are processed nevertheless.

{| class="wikitable"
|-
! '''Element'''
! [[GRFActionsDetailed|'''Size''']]
! '''Description'''
|-
| <sprite-number>
| dec
| A sequential sprite number
|-
| <length>
| dec
| The total number of bytes in the action
|-
| 14
| B
| Action 14
|-
| <chunks ...>
| *
| Any number of sub chunks.
|-
| "C"/"B"/"T"
| B
| chunk type (container/binary/text)
|-
| <identifier>
| 4*B
| Unique identifier for the chunk (see below)
|-
| <length>
| W
| Number of bytes of binary data following.
|-
| <binary-data>
| length*B
| Binary data
|-
| <language-id>
| B
| Which of TTD's languages the text is used for, see [[action4]]. (only GRF version >= 7 language codes allowed)
|-
| <text>
| S
| Text data
|}

== Descriptions ==
=== Custom information for non-official extensions/patches ("CSTM" -> <extension-id> -> ...) ===

<pre>-1 * -1 14 "C" "CSTM"
"C" <extension-id>
... whatever suits you ...
00
00
00</pre>

Due to the purely-optional character of action 14 it is especially meant for non-official extensions/patches. However, to avoid conflicts custom additions should go into the "CSTM" chunk. Every extension may define its own subchunk with its own custom 4 byte <extension-id> below the "CSTM" chunk. The format of the subchunks below the <extension-id> chunk is freely defineable.

The information there could be used e.g. to notify an extension that the GRF knows about it. Consecutively the extension might then enable custom GRF features and notify the GRF about their existance e.g. via variable 8D. Versions of OpenTTD without the extension will then just skip the "CSTM" chunk and return the usual value in variable 8D.

=== GRF name ("INFO" -> "NAME") and description ("INFO" -> "DESC") ===
{{ottdp|1.1|no|ottdrev=r20250}}
<pre>-1 * -1 14 "C" "INFO"
"T" "NAME" <language-id> "Translatable GRF name" 00
"T" "DESC" <language-id> "Translatable GRF description" 00
00
00</pre>

Below the top-level chunk "INFO" you can use the leaf-chunks "NAME" and "DESC" to define name and description for additional languages. The information provided in action 8 is used for "other" languages (id 7F).

=== GRF website ("INFO" -> "URL_") ===
{{ottdp|1.2|no|ottdrev=r23494}}
<pre>-1 * -1 14 "C" "INFO"
"T" "URL_" <language-id> "http://www.example.org" 00
00
00</pre>

You can use the "URL_" chunk to provide an url for this grf. You can translate this like the name and description to provide a localized website.

=== GRF palette ("INFO" -> "PALS") ===
{{ottdp|1.1|no|ottdrev=r20254}}
<pre>-1 * -1 14 "C" "INFO"
"B" "PALS" \w1 <palette>
00
00</pre>

Specifies the palette the sprites in the GRF are meant for.

{| class="wikitable"
|-
!'''<palette>'''
!'''Meaning'''
|-
|"D"
|DOS palette
|-
|"W"
|Windows palette
|-
|"A"
|Any palette. (e.g. when the GRF does not contain any sprites)
|}

=== GRF colour depth ("INFO" -> "BLTR") ===
{{ottdp|1.2|no|ottdrev=r23001}}
<pre>-1 * -1 14 "C" "INFO"
"B" "BLTR" \w1 <blitter>
00
00</pre>

Specifies the preferred blitter for a NewGRF. If not given, it will default to the 8 bpp blitter.

This is only a hint, OpenTTD may still select another blitter if necessary. Only 8 bpp sprites are guaranteed to work with any blitter.

{| class="wikitable"
|-
!'''<blitter>'''
!'''Meaning'''
|-
|"8"
|8 bpp blitter
|-
|"3"
|32 bpp blitter
|}

=== GRF version ("INFO" -> "VRSN") ===
{{ottdp|1.1|no|ottdrev=r20259}}
<pre>-1 * -1 14 "C" "INFO"
"B" "VRSN" \w4 \d<version>
00
00</pre>

Specifies the version of the GRF. This version is then used (by OpenTTD) to internally order GRFs with the same GRFID. That order will determine which GRF is loading as "compatible" GRF and which GRFs to show in the list of GRFs. By default a GRF has version 0.

If all GRFs (with the same GRFID) have version 0 all will be shown in the list of GRFs. If the highest version is shared by multiple GRFs one is randomly chosen as "compatible" GRF. As such it is important to prevent releasing multiple GRFs with the same version number.

If you set a version for the GRF, you should also set the 'minimal compatible version' MINV! Else it will default to the value of VRSN, which results in the GRF only being considered compatible to itself (resp. same version).

=== Minimal compatible GRF version ("INFO" -> "MINV") ===
{{ottdp|1.1|no|ottdrev=r20960}}
<pre>-1 * -1 14 "C" "INFO"
"B" "MINV" \w4 \d<version>
00
00</pre>

Specifies the minimal version of GRFs with the same GRFID this GRF is still compatible with.

You have to set MINV after VRSN, and MINV has to be smaller or equal to VRSN.

When loading a game which used an older version of your GRF which is no longer installed, the newest installed version of your GRF will be picked which is still compatible to the version used before. Older GRFs are never considered compatible to GRFs with newer versions though.

If you do not set MINV, but set VRSN, then the GRF is only considered compatible to GRFs with the same version.

If you set MINV to 0, the GRF is also considered compatible to old GRFs without any version information (VRSN).

=== GRF parameters ===

This section describes how to specify information about GRF parameters, and what settings are stored in them. By default a GRF comes with 128 settings, that is a dword setting for every of the 128 GRF parameters.

==== Number of settings ("INFO" -> "NPAR") ====
{{ottdp|1.1|no|ottdrev=r20251}}
<pre>-1 * -1 14 "C" "INFO"
"B" "NPAR" \w1 <number-of-settings>
00
00</pre>
Defines the number of settings a GRF provides. This is independant from the number of allowed GRF parameters, as multiple settings might go into the same GRF parameter (e.g. bitmasks).

==== Setting name ("INFO" -> "PARA" -> <setting-number> -> "NAME") and description ("INFO" -> "PARA" -> <setting-number> -> "DESC") ====
{{ottdp|1.1|no|ottdrev=r20255}}
<pre>-1 * -1 14 "C" "INFO"
"C" "PARA"
"C" \d<setting-number>
"T" "NAME" <language-id> "Name of setting" 00
"T" "DESC" <language-id> "Setting description" 00
00
00
00
00</pre>

Defines a name for a setting.

The settings are numbered and identified using <setting-number>. Valid values are 0 up to ("INFO" -> "NPAR") - 1.

==== Setting to GRF parameter mapping ("INFO" -> "PARA" -> <setting-number> -> "MASK") ====
{{ottdp|1.1|no|ottdrev=r20255}}
<pre>-1 * -1 14 "C" "INFO"
"C" "PARA"
"C" \d<setting-number>
"B" "MASK" \w<length> \b <grf-parameter> [ \b <first-bit> [ \b <num-bit> ] ]
00
00
00
00</pre>

Specifies which GRF parameter is used to store a setting in.

{| class="wikitable"
|-
|<length>
|A chunk length of 1 to 3 is allowed.
|-
|<grf-parameter>
|GRF parameter (0 to 127) to store the setting in. Default value is the same as <setting-number>.
|-
|<first-bit>
|First bit in the GRF parameter to use for the setting. Default value is "0".
|-
|<num-bit>
|Number of bits to use for the setting in the GRF parameter. Default value is "32".
|}

If you do not specify <first-bit> and <num-bit> the setting uses the whole GRF parameter by default. If you do not specify any "MASK" chunk at all, the setting will use the GRF parameter with the same number as <setting-number>.

So if you do not need to store multiple settings in one parameter, you do not need "MASK" chunks.

Note: You cannot store a setting across/using multiple GRF parameters.

==== Setting type ("INFO" -> "PARA" -> <setting-number> -> "TYPE") ====
{{ottdp|1.1|no|ottdrev=r20255}}
<pre>-1 * -1 14 "C" "INFO"
"C" "PARA"
"C" \d<setting-number>
"B" "TYPE" \w1 <setting-type>
00
00
00
00</pre>

Specifies the type of a setting.

{| class="wikitable"
|-
!'''<setting-type>
!'''Meaning'''
|-
|0
|Integer (unsigned) or enumeration. The GUI displays "<" and ">" buttons to change the setting resp. allows entering a value from a query window.
|-
|1
|Boolean. The GUI displays a toggle button to switch the setting on or off.
|}

The defaut value is "0".

==== Allowed value range ("INFO" -> "PARA" -> <setting-number> -> "LIMI") ====
{{ottdp|1.1|no|ottdrev=r20255}}
<pre>-1 * -1 14 "C" "INFO"
"C" "PARA"
"C" \d<setting-number>
"B" "LIMI" \w8 \d<minimum-value> \d<maximum-value>
00
00
00
00</pre>

Sets minimal and maximal allowed value for integer/enumeration settings.

The default values are "0" resp. "2^32 - 1".

==== Enumeration values ("INFO" -> "PARA" -> <setting-number> -> "VALU") ====
{{ottdp|1.1|no|ottdrev=r20255}}
<pre>-1 * -1 14 "C" "INFO"
"C" "PARA"
"C" \d<setting-number>
"C" "VALU"
"T" \d<setting-value> <language-id> "Enumeration value" 00
...
00
00
00
00
00</pre>

This chunk allows you to specify texts to display instead of the raw value for integer/enumeration. You can also specify texts only for some of the valid values. So if a setting e.g. allows values betweeen 0 to 42 you can instruct the GUI to show "none" instead of "0".

==== Default value ("INFO" -> "PARA" -> <setting-number> -> "DFLT") ====
{{ottdp|1.1|no|ottdrev=r20602}}
<pre>-1 * -1 14 "C" "INFO"
"C" "PARA"
"C" \d<setting-number>
"B" "DFLT" \w4 \d<value>
00
00
00
00</pre>

Sets the default value for a setting.

If you set "DFLT" for any setting the behavior of the "reset" functionality changes. Normally it would unset all parameters. If you have any "DFLT" field in your NewGRF then all parameters are unset after which all settings are set to their default value or to 0 if no default is provided. This means that using ActionD with opcode+80 doesn't work for any user-changeable parameter when you use a "DFLT" field.

This "reset" functionality happens when adding a NewGRF to a configuration or when the user presses the reset button in the parameter window.

NML:Vehicles

2011-11-22T20:45:25Z

Yexo: fixed link

{{NMLNavPropVarCB}}

==Properties common to all vehicle types==

{| class="t"
! property
! value range
! available for articulated vehicle
! comment
|-
| <code style="color:green">name</code>
| (string)
| yes
| for example <code style="color:darkgreen">string(STR_NAME_HEREFORD_TRAM)</code>
|-
| <code style="color:green">climates_available</code>
| bitmask(CLIMATE_XXX, CLIMATE_YYY, ...)
| set to <code style="color:green">NO_CLIMATES</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}} 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}} 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 articulated vehicle
! comment
|-
| <code style="color:green">sprite_id</code>
| <code style="color:green">SPRITE_ID_NEW_TRAIN</code>
| yes
| Set this property to enable new graphics
|-
| <code style="color:green">speed</code>
| 0 ... 65000 (float, speed units)
| no
| Max speed for engines, speed limit for wagons
|-
| <code style="color:green">misc_flags</code>
| bitmask(TRAIN_FLAG_XXX, ...)
| FLIP should not be set, TILT and MU 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
|
|-
| <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>
|-
| <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 articulated vehicle
! comment
|-
| sprite_id
| SPRITE_ID_NEW_ROADVEH
| yes
| Set this property to enable new graphics
|-
| speed
| 0 ... 514km/h (float, speed units)
| no
|
|-
| misc_flags
| bitmask(ROADVEH_FLAG_XXX, ...)
| partly; tram flag must the same
| The following flags are defined: ROADVEH_FLAG_TRAM, ROADVEH_FLAG_2CC, ROADVEH_FLAG_AUTOREFIT. Use 0 if you don't want to set any of these flags.
|-
| refit_cost
| 0 ... 255
| yes
| in 25% units of the purchase price cost base
|-
| callback_flags
| bitmask(VEH_CBF_XXX, ...)
| yes
|
Do not set this, unless you use [[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
|
|-
| 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
|
|-
| 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.
|}

==Plane 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)
|
|-
| 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
|
|-
| mail_capacity
| 0 ... 255
|
|-
| 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 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
|
[[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
|-
| vehicle_type_id
|
| No
| ID of 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_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
| Not valid before 1920 and after 2090.
|-
| 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 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==

{| 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
|-
| 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 0xFF
| 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 0xFF. 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 HEQS 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 0xFF
| Called when starting or stopping a vehicle. Mainly useful to prevent vehicles from leaving the depot unless a certain condition is met. Return 0xFF 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 0xFF
| With this callback, you can add articulated parts (e.g. tenders) to your vehicle. Called repeatedly, until 0xFF 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. Add 128 to the returned vehicle ID to display the vehicle backwards. This has the unfortunate side-effect of requiring the vehicle ID of the articulated part to be in the range 0 .. 127, currently there's no way around this limitation.
|-
| 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
|
|-
| 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
|}

NML:Vehicles

2011-11-22T20:44:36Z

Yexo:

{{NMLNavPropVarCB}}

==Properties common to all vehicle types==

{| class="t"
! property
! value range
! available for articulated vehicle
! comment
|-
| <code style="color:green">name</code>
| (string)
| yes
| for example <code style="color:darkgreen">string(STR_NAME_HEREFORD_TRAM)</code>
|-
| <code style="color:green">climates_available</code>
| bitmask(CLIMATE_XXX, CLIMATE_YYY, ...)
| set to <code style="color:green">NO_CLIMATES</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}} 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}} 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 articulated vehicle
! comment
|-
| <code style="color:green">sprite_id</code>
| <code style="color:green">SPRITE_ID_NEW_TRAIN</code>
| yes
| Set this property to enable new graphics
|-
| <code style="color:green">speed</code>
| 0 ... 65000 (float, speed units)
| no
| Max speed for engines, speed limit for wagons
|-
| <code style="color:green">misc_flags</code>
| bitmask(TRAIN_FLAG_XXX, ...)
| FLIP should not be set, TILT and MU 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
|
|-
| <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>
|-
| <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 articulated vehicle
! comment
|-
| sprite_id
| SPRITE_ID_NEW_ROADVEH
| yes
| Set this property to enable new graphics
|-
| speed
| 0 ... 514km/h (float, speed units)
| no
|
|-
| misc_flags
| bitmask(ROADVEH_FLAG_XXX, ...)
| partly; tram flag must the same
| The following flags are defined: ROADVEH_FLAG_TRAM, ROADVEH_FLAG_2CC, ROADVEH_FLAG_AUTOREFIT. Use 0 if you don't want to set any of these flags.
|-
| refit_cost
| 0 ... 255
| yes
| in 25% units of the purchase price cost base
|-
| callback_flags
| bitmask(VEH_CBF_XXX, ...)
| yes
|
Do not set this, unless you use [[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
|
|-
| 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
|
|-
| 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.
|}

==Plane 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)
|
|-
| 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
|
|-
| mail_capacity
| 0 ... 255
|
|-
| 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 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
|
[[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
|-
| vehicle_type_id
|
| No
| ID of 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_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
| Not valid before 1920 and after 2090.
|-
| 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 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==

{| 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
|-
| 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 0xFF
| 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 0xFF. 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 HEQS 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 0xFF
| Called when starting or stopping a vehicle. Mainly useful to prevent vehicles from leaving the depot unless a certain condition is met. Return 0xFF 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 0xFF
| With this callback, you can add articulated parts (e.g. tenders) to your vehicle. Called repeatedly, until 0xFF 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. Add 128 to the returned vehicle ID to display the vehicle backwards. This has the unfortunate side-effect of requiring the vehicle ID of the articulated part to be in the range 0 .. 127, currently there's no way around this limitation.
|-
| 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
|
|-
| 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
|}

NML:Add font glyphs

2011-11-20T14:38:18Z

Yexo:

{{NMLNavBlocksyntax}}

A <code style="color:darkgreen">font-glyph</code> block makes it possible to provide sprites for glyphs that don't have sprites in normal TTD. The syntax is as follows:

font_glyph (<font-size>, <base-char>, <image-file>) {
[[NML:Realsprites|list of realsprites]]
}

The first parameter (<code style="color:darkgreen"><font-size></code>) should be an identifier of the font size to use. Valid values are <code style="color:darkgreen">SMALL</code>, <code style="color:darkgreen">NORMAL</code>, <code style="color:darkgreen">LARGE</code> and <code style="color:darkgreen">MONO</code>.

The second parameter (<code style="color:darkgreen"><base-char></code>) is the number corresponding to the first character to provide a sprite for. Valid values are all unicode code points in the Basic Multilingual Plane (0-0xFFFF)

Parameter three <code style="color:darkgreen"><image-file></code> is a literal (quoted) string that specifies the file where the sprites are located.

<code style="color:darkgreen"><real-sprites></code> should be a list of real sprites. The first real sprite will be used for the character with code <code style="color:darkgreen">base-char;</code>, the second for <code style="color:darkgreen">base-char + 1</code> and so on. These sprites should only use colour palette indices 0 (transparent), 1 (foreground), and 2 (shadow).

Action0/Cargos

2011-11-05T12:32:50Z

Yexo: fix link to train prop. 28/29

== Introduction ==

The [[NewCargos]] switch of TTDPatch allows modifying the existing 12 cargos per climate, and allows adding 20 new cargos per climate as well. These cargo slots are numbered from 0 to 31, where slots 0-11 are used by default TTD cargos and slots 12-31 contain uninitialized garbage by default (so you can't trust them having meaningful information, you must set all of their properties).

== Properties ==

{| |-
!Number!![[GRFActionsDetailed|Size]]!!Version!!Description
|-
|08||B||{{ottdp|0.6|2.5}}||Bit number for bitmasks
|-
|09||W||{{ottdp|0.6|2.5}}||TextID for the cargo type name
|-
|0A||W||{{ottdp|0.6|2.5}}||TextID for the name of one unit from the cargo type
|-
|0B||W||{{ottdp|0.6|2.5}}||TextID to be displayed for 1 unit of cargo
|-
|0C||W||{{ottdp|0.6|2.5}}||TextID to be displayed for multiple units of cargo
|-
|0D||W||{{ottdp|0.6|2.5}}||TextID for cargo type abbreviation
|-
|0E||W||{{ottdp|0.6|2.5}}||Sprite number for the icon of the cargo
|-
|0F||B||{{ottdp|0.6|2.5}}||Weight of one unit of the cargo
|-
|10,11||B||{{ottdp|0.6|2.5}}||Penalty times
|-
|12||D||{{ottdp|0.6|2.5}}||Base price
|-
|13||B||{{ottdp|0.6|2.5}}||Color for the station list window
|-
|14||B||{{ottdp|0.6|2.5}}||Color for the cargo payment list window
|-
|15||B||{{ottdp|0.6|2.5}}||Freight status (for [[FreightTrains]] switch); 0=not freight, 1=is freight
|-
|16||W||{{ottdp|0.6|2.5}}||Cargo classes
|-
|17||D||{{ottdp|0.6|2.5}}||Cargo label
|-
|18||B||{{ottdp|0.6|2.5|ttdprev=alpha 72}}||Substitute type for town growth
|-
|19||W||{{ottdp|no|2.5|ttdprev=alpha 72}}||Multiplier for town growth
|-
|1A||B||{{ottdp|0.6|2.5|ttdprev=alpha 72}}||Callback flags
|-
|1B||W||{{ottdp|1.1|no|ottdrev=r21224}}||TextID for displaying the units of a cargo
|-
|1C||W||{{ottdp|1.1|no|ottdrev=r21224}}||TextID for displaying the amount of cargo
|}

== Descriptions ==

=== Bit number for bitmasks (08) ===

This value must be used in [[Action3]] and in cargo bit mask properties such as refit masks. Values 1C-1F should be safe to use (if they aren't already taken, of course) if you intend to maintain compatibility with GRFs unaware of the newcargos switch. Further assuming that no active GRFs support the toyland climate, you can use values 11-1A as well.

Additionally, you can use the value FFh to disable the given cargo slot. This way, it won't appear in cargo type lists, but it won't be removed from things already on the map. If you disable a cargo, you'll probably want to zero out the cargo label (property 17) as well.

This property only affects GRFs which do not have a [[Action0/Global Settings#Cargo_translation_table_.2809.29 | cargo translation table]]. GRFs with such a table generally use the index of the cargo in the table instead of the value of this property to access a cargo. As such this property is more or less a default value for GRFs without cargo translation table. If you are unsure what value to assign to this property, set it to the same value as the cargo slot ID.

=== TextID for the cargo type name (09) ===

This textID should refer to the name of the cargo, capitalized, to match the TTD style (e.g. "Passengers", "Coal", "Gold Ore", "Milk")

You can reuse existing [[TextIDs]] or create custom strings using [[Action4]] with an offset in the DCxx range. Note that you need to set language-id bit 7 as well in the Action4 for a custom string. (Also applies to properties 0A to 0D)

=== TextID for one unit of the type (0A) ===

This textID should refer to the cargo type name in the singular. Currently, this ID is used only in subsidy messages ("First Passenger service..." instead of "First Passengers service...", for example)

=== TextID for 1 unit of cargo (0B) ===

This textID will be used to display the amount of the cargo if there's exactly 1 unit waiting. Although there's only one unit waiting, you'll still have to use either the special character 7C (print signed word) or 87 (print amount in litres and add suffix " litres") so TTD removes the amount from its internal reference stack. For example, if you have a new cargo named "gold ore", this should be "\7C ton of gold ore", which will expand to "1 ton of gold ore". On the other hand, a liquid cargo named "milk" should be something like "\87 of milk", which will expand to either "100 litres of milk" or "1,000 litres of milk" (The multiplier for liquid cargos depends on miscmods.dontfixlitres. If it's on, the multiplier is 100, otherwise it's 1000)

=== TextID for multiple units of cargo (0C) ===

This textID will be used to display the amount of cargo if the amount waiting isn't exactly 1. You'll need the same special characters as above, but now they will be expanded according to the actual cargo waiting. Sticking to the example above, you'll need "\7C tons of gold ore" and "\87 of milk", which can expand to "42 tons of gold ore" and "42,000 litres of milk", accordingly. You will note that liquid cargos can have the same textID for both property 0B and 0C since they always use the plural form.

=== TextID for cargo type abbreviation (0D) ===

This textID will be used in the station list window to represent the cargo waiting. It should be a two-letter abbreviation prefixed by the special character 0E to switch to the microscopic font. The microscopic font has every letter capitalized, so capitalization isn't important here. Continuing the above example, gold ore could have this as "GO" and milk as "MK" ("ML" is already taken by mail).

=== Sprite number for icon (0E) ===

This is a sprite number of an old TTD sprite to be displayed in the station window for this cargo, or FFFFh if the icon should be found by following the action 3 associated with this cargo. The icon must not be bigger than 10x10 pixels. One icon will be shown for every 10 units of the cargo waiting, up to 23 icons, which is the maximum.

=== Weight of one unit of the cargo (0F) ===

This property defines the weight of 1 unit from the cargo, which will be used to calculate the weight of the vehicles when loaded. The unit is 1/16 ton (which is 62.5 kg). With the examples above, gold ore should have this as 16 (since 1 ton of gold ore should weigh exactly 1 ton), while milk should have this slightly above 16 (milk is denser than water).

=== Penalty times and price factor (10,11,12) ===

These three values define how much is paid for the delivery of the cargo type. The price factor is subject to inflation, but GRFs needn't care about this, the programme will adjust the price for them.

The income generated from cargo delivery is calculated as:

income=((((distance/2) * timefactor * amount_moved) >> 7) * cargopricefactor) >> 13

where

; a >> b : means a is arithmetically shifted right by b bits
; distance : is the Manhattan distance between the two station signs
; amount_moved : is the number of cargo units moved
; cargopricefactor : is the value you set in property 12. Inflation will be applied automatically on it.
; timefactor : is a multiplier in the range 0..255, calculated in the following way: (T1 is the value of property 10, T2 is the value of property 11, t is the time the delivery took, the unit is 185 game ticks (roughly 2.5 game days) )

if t<=T1 then timefactor=255
else if t<=(T1+T2) then timefactor=255-(t-T1)
else timefactor=255-(t-T1)-(t-T1-T2)
if the above rules result in a timefactor less than 31, 31 is used instead.

=== Color for the station list window (13) ===

This color index will be used to draw the rectangle representing the amount waiting from the current cargo type in the station list window. The index should be given for the DOS palette. OpenTTD and TTDPatch will automatically translate the index for the Windows palette, if they use the windows base graphics.

=== Color for the cargo payment list window (14) ===

The graph of the current cargo will be drawn using this color in the cargo payment rates graph. The index should be given for the DOS palette, the Windows version of TTDPatch will automatically translate the index for the Windows palette.

=== CargoClasses (16) ===

See [[Action0Trains#Cargo classes .2828.2C_29.29|train prop. 28/29]] for a description of the utility of this property.

This is a bit mask of all cargo classes to which this cargo belongs, out of the following:

{| |-
!Bit!!Value!!Cargo class
|-
|0||1||Passengers
|-
|1||2||Mail
|-
|2||4||Express cargo (any prioritised cargo)
|-
|3||8||Armored cargo (needing security measures, e.g. valuables or gold)
|-
|4||10||Bulk freight (any non-packaged cargo suitable for pouring, e.g. coal, grain, ore, cement, ...)
|-
|5||20||Piece goods (any unitised cargo, packed or unpacked)
|-
|6||40||Liquids (any liquid or gaseous cargo, food or chemical)
|-
|7||80||Refrigerated cargo (any goods needing temperature-controlling, e.g. perishable goods, food, or chemicals needing cooling/heating)
|-
|8||100||Hazardous cargo (explosives, acids, radioactive material, ...)
|-
|9||200||covered/sheltered freight (any cargo needing moisture protection, i.e. transportation in box vans, silo wagons or containers required)
|-
|10||400||Oversized and/or overweight cargo (any cargo needing special means of transportation, e.g. industrial equipment, machinery, large format glass, ... )
|-
|15||8000||Special (used for livery refit tricks rather than actual cargos)
|}

Only cargos which are in class 0 (passengers) will appear in bus stations. Only cargos which are ''not'' in class 0 will appear in truck stations.

=== Cargo label (17) ===

Cargo labels are globally [[CargoTypes#Cargo Labels|unique identifiers]] for a cargo type. They are used to allow vehicle grfs to easily support many cargo types, whether they are active or not and no matter what slot or bit they are using.

Read about the [[Action0/Global Settings#Cargo translation table 09|cargo translation table]] for further info.

=== Substitute type and multiplier for town growth (18, 19) ===

These properties allow you to modify how a cargo type affects town growth. Property 18 can contain one of the following values:

{| |-
!Value!!Meaning!!{{ottdp|0.7|no}} Details<ref>This is the interpretation of OpenTTD. For TTDPatch see [http://www.tt-wiki.net/wiki/NewTownGrowthSwitches NewTownGrowthMechanism], which is quite different/unrelated.</ref>
|-
|00||Affect towns as passengers do||Cargo produced by houses is added to the statistics in the town GUI.
|-
|02||Affect towns as mail does||Cargo produced by houses is added to the statistics in the town GUI.
|-
|05||Affect towns as goods/candy does||See note about subsidies below.
|-
|09||Affect towns as water does||Second required cargo for towngrowth in the desert
|-
|0B||Affect towns as food/fizzy drinks do||First required cargo for towngrowth in desert/above snowline. Alse see note about subsidies below.
|-
|FF||Don't affect town growth (default)||
|}

<references />

The incoming cargo amount is multiplied by property 19, then divided by 256 before it is added to the town statistics. This allows you to have smaller or bigger impact than original cargoes do. Please note that cargoes accepted by industries affect the closest town as well; for example, if you have an industry that accepts passengers, every passenger brought to the industry affects the town just like if they were transported to the town directly. Usually, it's not a good idea to have industries that process such cargoes; they should be accepted by towns only.

{{ottdp|0.6|no}} In OpenTTD property 18 also affects the creation of subsidies. Usually subsidies apply to cargo transportation between two industries. For cargos with substitution-type 05 or 0B the destination will be a town instead. Independent of property 18 subsidies from town to town are only created for cargo slot 0 (Passengers).

=== Callback flags (1A) ===

{| |-
!Bit!!Value!!Var. 0C!!Callback
|-
|0||1||39||Custom profit calculation
|-
|1||2||145||Custom station rating calculation
|}

=== TextID for displaying the units of a cargo (1B) ===

This textID is used by OpenTTD to show the "short cargo" form for cargo units, e.g. "10 litres" or "10 tonnes". This textID must be set after property 0B. The text this textID refers to should properly handle plurals, e.g. "\7B item\9A\15\80\9A\10\9A\11s\9A\12".

The default for this textID depends on the default for property 0B; if the default 0B string has "litre", then the default for this textID will be the unit for litres. OpenTTD maps the following textIDs so you don't need to provide translations:

{| |-
!textID!!String
|-
|004f||<num> passenger(s)
|-
|0050||<num> tonne(s)
|-
|0051||<num> bag(s)
|-
|0052||<num> litre(s)
|-
|0053||<num> item(s)
|-
|0054||<num> crate(s)
|}

The "tonne" and "litre" strings (textID 0050 and 0052) are automatically updated based on the user settings of unit display, e.g. they "tonne" might become "kg". The "(s)" is for display purposes; in reality that is a choice list.

=== TextID for displaying the amount of cargo (1C) ===

This textID is used by OpenTTD to show the "long cargo" form for cargo units, e.g. "10 litres of water" or "10 tonnes of coal". This textID must be set after property 0c. The text this textID refers to should properly handle plurals, e.g. "\7B item\9A\15\80\9A\10\9A\11s\9A\12 of livestock".

The default for this textID depends on the default for property 0C, but with support for plurals. For "X litre(s)" or "X tonne(s)" you should respectively use string codes 87 and 9A 0D.

== Example ==

Storages

2011-11-01T20:00:37Z

Yexo: /* Persistent storage accessed by GRFID */

==Introduction==

Storages are arrays of registers that can be accessed when using [[VariationalAction2]]. Registers (temporary and persistent alike) always have a size of 4 bytes. If you're writing them using smaller sizes (anything but type 89/8A), the given value will be sign-extended to 4 bytes. Therefore, be careful when you read a register using a bigger size than it was written with. This also applies to registers read by TTDPatch; if not indicated specifically, TTDPatch reads all 4 bytes of the register.

==Description==
===Temporary storage===
{{ottdp|0.6|2.6}}

'''Size:''' 00 - FF (256) (from TTDPatch r1246 to r1301) or 00 - 10F (272) (since TTDPatch r1301 and OpenTTD r9707)

'''Data storage:''' [[VarAction2Advanced#operator|Operator \2sto (0E)]] allows to store values inside the registers of this storage.

'''Data access:''' The first 256 registers 00 to FF can be read using [[VariationalAction2#Variable|variable 7C]]. The rest of the values (100 to 10F) are write only: they are used to pass extra data to some 4x and 6x variables, as well as for returning extra data from callbacks.

Temporary storage contains values local to the current [[VariationalAction2]] chain. When a new chain starts, the values inside the temporary storage are undefined. Therefore, they should not be used unless they have been properly initialized. During the execution of a chain, only that chain can modify the values in the temporary storage.

===Persistent storage===
{{ottdp|0.6|2.6}}

'''Size:''' 00 - 0F (16)

'''Data storage:''' [[VarAction2Advanced#operator|Operator \2psto (10)]] allows to store values inside the registers of this storage.

'''Data access:''' The registers can be read using [[VariationalAction2#Variable|variable 7D]]. Note that it is possible to access the persistent storage of related objects (see [[VariationalAction2#Type]]).

'''Features that support it:''' Industries (0A)

Persistent storage is associated to a single item. When the item is created, all of the values of the persistent storage are set to zero. Persistent storage values cannot be accessed or modified by items that are being created. Persistent storage should not be read if the current feature doesn't support it.

===Persistent storage accessed by GRFID===
{{ottdp|1.2|ottdrev=r22569}}

'''Size:''' 00 - 0F (16) for each GRFID

'''Data storage:''' [[VarAction2Advanced#operator|Operator \2psto (10)]] allows to store values inside the registers of this storage. The GRFID to access must be stored in temporary register 0x100 before using Operator 10. 0xFFFFFFFF can be used to access the GRFID of the item using the current [[VariationalAction2]] chain.

'''Data access:''' The registers can be read using [[VariationalAction2#Variable|variable 7D]]. Note that it is possible to access the persistent storage of related objects (see [[VariationalAction2#Type]]). The GRFID to access must be stored in temporary register 0x100 before checking variable 7C. 0xFFFFFFFF can be used to access the GRFID of the item using the current [[VariationalAction2]] chain.

'''Features that support it:''' Towns (since OpenTTD r22569)

Features supporting persistent storage accessed by GRFID are not restricted to a single persistent storage; there is a persistent storage associated to every GRFID. An item only has write access to the persistent storage associated to its own GRFID, but it can read the registers of any GRFID. Persistent storage values cannot be accessed or modified by items that are being created. Persistent storage should not be read if the current feature doesn't support it.

NML:Language files

2011-10-29T21:12:02Z

Yexo: /* String parameters */

{{NMLNavNoSubpages}}
== Introduction ==
Language files are usually found in the <code style="color:darkgreen">lang</code> sub-folder of the project, but the place NML looks for the language files can be changed via command line parameter to any directory desired:

nmlc -l path/to/lang-dir path/to/nml-source-file.nml
nmlc --lang-dir=path/to/lang-dir path/to/nml-source-file.nml

Language files MUST have the extension <code style="color:darkgreen">.lng</code> The language files themselves follow a certain structure:

##grflangid <number>
<string-name> :<text>
<string-name> :<text>
...

where the first line must give the language code for the language this file describes (see below). The following lines each describe a string. The translated string follows immediately the colon. An NML project has exactly one fallback language, by default this is english.lng. You can change this with the command line parameter --default-lang. Example for a valid language file:

<pre class=example>
##grflangid 0x01
STR_GRF_NAME :{TITLE} 0.1.0 - {VERSION}
STR_GRF_DESCRIPTION :{TITLE} contains pimped ground tiles.
STR_NAME_MYVEHICLE :General Robotics Anti-Grav UFO Mark X
</pre>

== String codes ==

Strings may contain a number of special string codes which control how the string is being printed or which values to insert into the string. Custom replacements can be stored in the plain text file <code>custom_tags.txt</code> (for example a newgrf version which is written by your build script). In the case above the <code>custom_tags.txt</code> could, for example read

<pre class=example>
VERSION :alpha-r88
TITLE :Example NewGRF
</pre>

Additionally to custom-defined tags, NML comes with a number of default tags:
{|
!width="150pt"|Tag
!width="600pt"|Meaning
!Example
|-
| ||empty tag, written as {} is used to create a newline
|-
|NBSP || non-breaking space
|-
|{ || Display a left curly bracket. You write this as {{}. If you'd include it without surrounding it by { and } it'd be seen as the start of a tag and the rest of the string would be read as name of the tag.
|-
|COPYRIGHT || copyright symbol || ©
|-
|TRAIN || display train symbol
|-
|LORRY || display lorry symbol
|-
|BUS || display bus symbol
|-
|PLANE || display plane symbol
|-
|SHIP || display ship symbol
|-
|TINYFONT || switch to small font
|-
|BIGFONT || switch to big font
|-
|BLUE || switch to blue text
|-
|SILVER || switch to silver text
|-
|GOLD || switch to golden text
|-
|RED || switch to red text
|-
|PURPLE || switch to purple text
|-
|LTBROWN || switch to light brown text
|-
|ORANGE || switch to orange text
|-
|GREEN || switch to green text
|-
|YELLOW || switch to yellow text
|-
|DKGREEN || switch to dark green text
|-
|CREAM || switch to cream-coloured text
|-
|BROWN || switch to brown text
|-
|WHITE || switch to white text
|-
|LTBLUE || switch to light blue text
|-
|GRAY || switch to gray text
|-
|DKBLUE || switch to dark blue text
|-
|BLACK || switch to black text
|}
== String parameters ==
The above tags can be used in almost all strings. There are also a number of tags that need an argument they'll read from the textstack. The textstack is only available for certain callbacks an properties.
{|
!width="150pt"|Tag
!width="600pt"|Meaning
!Size (number of bytes read from stack)
!Example
|-
|COMMA || signed number with decimal separator between 1000's. || 4
|-
|SIGNED_WORD || signed number with decimal separator between 1000's. || 2
|-
|UNSIGNED_WORD || unsigned number with decimal separator between 1000's. || 2
|-
|CURRENCY || money in proper currency units || 4 || 24,492 €
|-
|VELOCITY || velocity in proper units || 2 || 35 km/h
|-
|VOLUME || volume in proper units || 2 || 29,000 litres
|-
|VOLUME_SHORT || volume in proper units in short form || 2 || 29,000l
|-
|POWER || power in proper units || 2 || 2,030 kW
|-
|WEIGHT || weight in proper units || 2 || 5 tonnes
|-
|WEIGHT_SHORT || weight in proper units in short form || 2 || 5t
|-
|HEX || hexadecimal presentation || 4 || F0 3D D4 33
|-
|STRING || include other string || 2
|-
|DATE1920_LONG || days since 1920 as long date || 2 || 12 August 1935
|-
|DATE1920_SHORT|| days since 1920 as short date || 2 || 12 Aug 1935
|-
|DATE_LONG || days since 0 as long date || 4 || 12 August 1610
|-
|DATE_SHORT || days since 0 as short date || 4 || 12 Aug 3049
|-
|POP_WORD || Remove 2 bytes from the top of the stack || 2
|-
|STRING || Station name of station with given ID || 2
|}

In case you don't want to use the first 2 (or 4) bytes from the stack but rather another variable, you can prefix the tag name with the number, like {1:COMMA} to use the second (indexing starts at 0) argument from the stack. You can also use this in translations that require a different order, for example (in english.lng):

STR_SOME_STRING :{COMMA} items cost {CURRENCY}

And the same string in dutch.lng:

STR_SOME_STRING ;{!:CURRENCY} is de prijs van {0:COMMA} items.

The string parameters itself are assigned in units of dwords (4 bytes), starting with temporary storage 256, up to 259 or 261. Thus if you use parameters which are not of dword size (e.g. strings or word-sized numbers), you have to construct the text stack via bit arithmetic:
<pre class=example>
switch(FEAT_INDUSTRIES, SELF, extra_text_switch, [
STORE_TEMP(
( (LOAD_PERM(var_supply_efficiency_factor) == 1) * string(STR_EXTRA_PRIMARY_EFFICIENT1) ) +
( (LOAD_PERM(var_supply_efficiency_factor) == 2) * string(STR_EXTRA_PRIMARY_EFFICIENT2) ) +
( (LOAD_PERM(var_supply_efficiency_factor) == 3) * string(STR_EXTRA_PRIMARY_EFFICIENT3) ) +
( (LOAD_PERM(var_supply_efficiency_factor) == 4) * string(STR_EXTRA_PRIMARY_EFFICIENT4) ) |
LOAD_PERM(var_supply_requirement) << 16,
256
),
return string(STR_EXTRA_PRIMARY);
}
</pre>

for a language file which reads
<pre class=example>
STR_EXTRA_PRIMARY_EFFICIENT1 :{YELLOW}very efficient{BLACK}ly
STR_EXTRA_PRIMARY_EFFICIENT2 :{YELLOW}efficient{BLACK}ly
STR_EXTRA_PRIMARY_EFFICIENT3 :in a {YELLOW}normal{BLACK} way
STR_EXTRA_PRIMARY_EFFICIENT4 :{YELLOW}wasteful{BLACK}ly
STR_EXTRA_PRIMARY :{BLACK}This industry needs {YELLOW}supplies{BLACK}.{}They use them {STRING}{}{}Monthly demand: {YELLOW}{UNSIGNED_WORD} crate{P "" s} of engineering supplies{BLACK}.
</pre>

== Defining cases ==
Similar to OpenTTD's language files, NML can also make use of cases, genders and plural forms. In order to utilize them, they have to be defined in the language file's header and have to match the definition as used in OpenTTD's language files:
<pre>
##case pragma

STR_NAME :Utas
STR_NAME.pragma :utast
</pre>

e.g. for Hungarian you'd have
<pre class=example>
##case t ba

STR_CARGO_PLURAL_PASSENGERS :Utas
STR_CARGO_PLURAL_PASSENGERS.t :utast
</pre>

== Defining genders ==
Genders just like cases are defined in the header of the language file and have to match the definition as found within OpenTTD's language files. The gender of a word or expression is declared within the string's text itself by a tag of the form <code>{G=gendername}</code>:
<pre>
##gender pragma

STR_NAME :{G=gendername}String which requires gender 'gendername'
</pre>
where the string with the defined gender then will trigger the correct usage in a string which includes it and which has to take provisions to show the proper gender:
<pre>
STR_OTHER :Some text {G gender1 gender2 ...} {STRING}
</pre>

for example in German
<pre class=example>
##gender m w n p

STR_CARGO_NAME_BAUXITE :{G=n}Bauxit
</pre>
which then will be used with the correct gender by a string which includes it:
<pre class=example>
STR_NEWS_STATION_NO_LONGER_ACCEPTS_CARGO :{WHITE}{STATION} akzeptiert kein{G "en" "e" "" "e"} {STRING} mehr.
</pre>

== LanguageIDs ==

Valid language IDs are listed in the table below. The cases, genders and number of plural forms is only given as reference. Authorative are the definitions in OpenTTD's language file for each language.

{| class="t"
! ID
! language
! cases
! genders
! plurals
|-
| 00
| American
|
|
|
|-
| 01
| English
|
|
|
|-
| 02
| German
|
| m w n p
|
|-
| 03
| French
|
| m m2 f
| 2
|-
| 04
| Spanish
|
| m f
|
|-
| 05
| Esperanto
|
| n
|
|-
| 06
| Ido
|
|
|
|-
| 07
| Russian
| m f n p nom gen dat acc abl pre
| m f n p
| 6
|-
| 08
| Irish
|
|
| 4
|-
| 09
| Maltese
|
|
| 12
|-
| 0A
| Tamil
|
|
|
|-
| 0B
| Chuvash
|
|
|
|-
| 0C
| Chinese (Traditional)
|
|
| 1
|-
| 0D
| Serbian
| nom big gen dat aku vok lok ins
| muški ženski srednji
| 6
|-
| 0E
| Norwegian (Nynorsk)
| small
| masculine feminine neuter
|
|-
| 0F
| Welsh
|
|
|
|-
| 10
| Belarusian
| m f n p nom gen dat acc abl pre
| m f n p
| 6
|-
| 11
| Marathi
|
|
|
|-
| 12
| Faroese
|
| m f n
|
|-
| 14
| Arabic (Egypt)
|
|
| 1
|-
| 15
| Czech
| nom gen dat acc voc loc ins big small
| m f n map mnp fp np
| 10
|-
| 16
| Slovak
| g
| m z s
| 10
|-
| 18
| Bulgarian
| m f n p
| m f n p
|
|-
| 1B
| Afrikaans
|
| male
|
|-
| 1E
| Greek
| subs date geniki
| m f n
| 2
|-
| 1F
| Dutch
|
|
|
|-
| 21
| Basque
|
|
|
|-
| 22
| Catalan
|
| Masculin Femenin
|
|-
| 23
| Luxembourgish
|
|
|
|-
| 24
| Hungarian
| t ba
|
| 2
|-
| 26
| Macedonian
|
|
|
|-
| 27
| Italian
| ms mp fs fp
| m ma f
|
|-
| 28
| Romanian
|
|
|
|-
| 29
| Icelandic
|
| karlkyn kvenkyn hvorugkyn
|
|-
| 2A
| Latvian
| kas
| m f
| 3
|-
| 2B
| Lithuanian
| kas ko kam ka kuo kur kreip
| vyr mot
| 5
|-
| 2C
| Slovenian
| r d t
|
| 8
|-
| 2D
| Danish
|
|
|
|-
| 2E
| Swedish
|
|
|
|-
| 2F
| Norwegian (Bokmal)
| small
| masculine feminine neuter
|
|-
| 30
| Polish
| d c b n m w
| m f n
| 7
|-
| 31
| Galician
|
| m f n
|
|-
| 32
| Frisian
|
|
|
|-
| 33
| Ukrainian
| r d z
| m f s mn
| 6
|-
| 34
| Estonian
| g in sü
|
|
|-
| 35
| Finnish
|
|
|
|-
| 36
| Portuguese
|
| n m f mp fp
|
|-
| 37
| Brazilian Portuguese
|
| m f
| 2
|-
| 38
| Croatian
| nom gen dat aku vok lok ins
| male female middle
| 6
|-
| 39
| Japanese
|
|
| 1
|-
| 3A
| Korean
|
| m f
| 11
|-
| 3C
| Malay
|
|
|
|-
| 3E
| Turkish
| tamlanan
|
| 1
|-
| 42
| Thai
|
|
| 1
|-
| 54
| Vietnamese
|
|
| 1
|-
| 56
| Chinese (Simplified)
|
|
| 1
|-
| 5A
| Indonesian
|
|
| 1
|-
| 5C
| Urdu
|
| m f
|
|-
| 61
| Hebrew
| singular plural gen
| m f
|
|-
| 62
| Persian
|
|
|
|}

In case a language is not in this list, check the [[Action4#language IDs|master language list]] (for GRFv7) in the NewGRF Specs. This master list is always leading. NFO language ID 7F has no meaning in NML (set --default-lang instead) and setting bit 16 will break your language file.

StringCodes

2011-10-29T21:00:45Z

Yexo: stringcodes 9A 19 and 9A 1A

=String Codes=

Texts in TTD are mostly in the Latin-1 (ISO-8859-1) character set (except when using UTF-8 encoding; see below), however a few characters are different. Also, some characters have special meaning. These are explained in the following table.

{| |-
!Range, hex!!Version!!Meaning
|-
|00..1F||||Control characters, unused except for the following:
|-
|||{{ottdp|0.6|2.0}}||01 X offset in next byte of string (variable space)
|-
|||{{ottdp|0.6|2.0}}||0D New line
|-
|||{{ottdp|0.6|2.0}}||0E Set small font size
|-
|||{{ottdp|0.6|2.0}}||0F Set large font size
|-
|||{{ottdp|0.6|2.0}}||1F X and Y offsets in next two bytes of string
|-
|20..7A||{{ottdp|0.6|2.0}}|| Latin-1/ASCII characters, from space " " up to lower case "z"
|-
|7B..87|||| Formatting instructions, all take their argument from the stack if not otherwise specified
|-
|||{{ottdp|0.6|2.0}}||7B Print signed dword
|-
|||{{ottdp|0.6|2.0}}||7C Print signed word
|-
|||{{ottdp|0.6|2.0}}||7D Print signed byte
|-
|||{{ottdp|0.6|2.0}}||7E Print unsigned word
|-
|||{{ottdp|0.6|2.0}}||7F Print dword in currency units
|-
|||{{ottdp|0.6|2.0}}||80 Print substring (text ID from stack)
|-
|||{{ottdp|0.6|2.0}}||81 Print substring (text ID in next 2 bytes of string)
|-
|||{{ottdp|0.6|2.0}}||82 Print date (day, month, year) (based on year 1920)
|-
|||{{ottdp|0.6|2.0}}||83 Print short date (month and year) (based on year 1920)
|-
|||{{ottdp|0.6|2.0}}||84 Print signed word in speed units
|-
|||{{ottdp|0.6|2.0}}||85 Discard next word from stack
|-
|||{{ottdp|0.6|2.0}}||86 Rotate down top 4 words on stack
|-
|||{{ottdp|0.6|2.0}}||87 Print signed word in litres
|-
|88..98||||Colour codes
|-
|||{{ottdp|0.6|2.0}}||88 Blue
|-
|||{{ottdp|0.6|2.0}}||89 Light Gray
|-
|||{{ottdp|0.6|2.0}}||8A Light Orange ("Gold")
|-
|||{{ottdp|0.6|2.0}}||8B Red
|-
|||{{ottdp|0.6|2.0}}||8C Purple
|-
|||{{ottdp|0.6|2.0}}||8D Gray-Green
|-
|||{{ottdp|0.6|2.0}}||8E Orange
|-
|||{{ottdp|0.6|2.0}}||8F Green
|-
|||{{ottdp|0.6|2.0}}||90 Yellow
|-
|||{{ottdp|0.6|2.0}}||91 Light Green
|-
|||{{ottdp|0.6|2.0}}||92 Red-Brown
|-
|||{{ottdp|0.6|2.0}}||93 Brown
|-
|||{{ottdp|0.6|2.0}}||94 White
|-
|||{{ottdp|0.6|2.0}}||95 Light Blue
|-
|||{{ottdp|0.6|2.0}}||96 Dark Gray
|-
|||{{ottdp|0.6|2.0}}||97 Mauve (grayish purple)
|-
|||{{ottdp|0.6|2.0}}||98 Black
|-
|99||{{ottdp|no|2.5|ttdprev=2.0.1 alpha 1}}||Switch to company colour that follows in next byte (enabled by enhancegui)
|-
|9A||||Extended format code in next byte:
|-
|||{{ottdp|0.6|2.5}}||00 -or- 01 Display 64-bit value from stack in currency units
|-
|||{{ottdp|no|2.6}}||02 Ignore next colour byte. Multiple instances will skip multiple colour bytes.
|-
|||{{ottdp|0.6|2.6}}||03 WORD Push WORD onto the textref stack
|-
|||{{ottdp|0.6|2.6}}||04 BYTE Un-print the previous BYTE characters.
|-
|||{{ottdp|no|2.6}}||05 For internal use only. Not valid in GRF files.
|-
|||{{ottdp|0.7|2.6|ttdprev=r2007}}||06 Print byte in hex
|-
|||{{ottdp|0.7|2.6|ttdprev=r2007}}||07 Print word in hex
|-
|||{{ottdp|0.7|2.6|ttdprev=r2007}}||08 Print dword in hex
|-
|||{{ottdp|no|2.6|ttdprev=r2128}}||09 For internal use only. Usage in NewGRFs will most likely crash TTDPatch.
|-
|||{{ottdp|no|2.6|ttdprev=r2128}}||0A For internal use only. Usage in NewGRFs will most likely crash TTDPatch.
|-
|||{{ottdp|1.0|2.6|ttdprev=r2178}}||0B Print 64-bit value in hex
|-
|||{{ottdp|1.1|2.6|ttdprev=r2178}}||0C Print name of station with id in next textrefstack word
|-
|||{{ottdp|1.1|ottdrev=r21086}}||0D Print unsigned word in tonnes
|-
|||{{ottdp|1.1|ottdrev=r21209}}||0E Set gender of string, NewGRF internal ID in next byte. Must be first in a string. <ref name="gendercasedef">See [[#Setting_genders_and_cases|Setting genders and cases]].</ref>
|-
|||{{ottdp|1.1|ottdrev=r21209}}||0F Select case for next substring, NewGRF internal ID in next byte. <ref name="gendercasedef"/>
|-
|||{{ottdp|1.1|ottdrev=r21211}}||10 Begin choice list value, NewGRF internal ID in next byte. <ref name="choices">See [[#Choosing_strings_depending_on_required_gender_or_case|Choosing strings depending on required gender or case]].</ref>
|-
|||{{ottdp|1.1|ottdrev=r21211}}||11 Begin choice list default <ref name="choices"/>
|-
|||{{ottdp|1.1|ottdrev=r21211}}||12 End choice list <ref name="choices"/>
|-
|||{{ottdp|1.1|ottdrev=r21211}}||13 Begin gender choice list, stack offset of substring to get gender from in next byte. <ref name="choices"/>
|-
|||{{ottdp|1.1|ottdrev=r21211}}||14 Begin case choice list <ref name="choices"/>
|-
|||{{ottdp|1.1|ottdrev=r21216}}||15 Begin plural choice list, stack offset of value to get plural for in next byte. <ref>See [[#Using_plural_forms|Using plural forms]].</ref>
|-
|||{{ottdp|1.2|ottdrev=r22778}}||16 Print dword as date (day, month, year) (based on year 0)
|-
|||{{ottdp|1.2|ottdrev=r22778}}||17 Print dword as short date (month and year) (based on year 0)
|-
|||{{ottdp|1.2|ottdrev=r22779}}||18 Print unsigned word in horse power
|-
|||{{ottdp|1.2|ottdrev=r23063}}||19 Print unsigned word as short volume
|-
|||{{ottdp|1.2|ottdrev=r23063}}||1A Print unsigned word as short weight
|-
|9B..9D||||Reserved
|-
|9E..FF||{{ottdp|0.6|2.0}}||Latin-1 characters, except for the following:
|-
|||{{ottdp|0.6|2.0}}||9E Euro character "€"
|-
|||{{ottdp|0.6|2.0}}||9F Capital Y umlaut "&Yuml;"
|-
|||{{ottdp|0.6|2.0}}||A0 Scroll button up
|-
|||{{ottdp|0.6|2.0}}||AA Scroll button down
|-
|||{{ottdp|0.6|2.0}}||AC Tick mark
|-
|||{{ottdp|0.6|2.0}}||AD X mark
|-
|||{{ottdp|0.6|2.0}}||AF Scroll button right
|-
|||{{ottdp|0.6|2.0}}||B4 Train symbol
|-
|||{{ottdp|0.6|2.0}}||B5 Truck symbol
|-
|||{{ottdp|0.6|2.0}}||B6 Bus symbol
|-
|||{{ottdp|0.6|2.0}}||B7 Plane symbol
|-
|||{{ottdp|0.6|2.0}}||B8 Ship symbol
|-
|||{{ottdp|0.6|2.0}}||B9 Superscript -1
|-
|||{{ottdp|0.6|2.0}}||BC Small scroll button up
|-
|||{{ottdp|0.6|2.0}}||BD Small scroll button down
|}
<references/>

The formatting instructions must not be used except in strings that expect them, and then they may not be out of order (with the possible exception of code 86 shuffling the internal stack). When used improperly, they will most likely crash TTD. Code 81 is always safe to use (provided that the referenced text ID uses no unsafe formatting instructions either), and will insert the given text ID (e.g. "\81\3D\A0" will insert text ID A03D, "\98Refit Aircraft"). Note however that if you want to include e.g. ID D000/D400, the 00 byte will be considered the end of string, and this will therefore break if additional texts are supposed to follow in the action 4. DCxx IDs must not be included; neither codes 80 nor 81 correctly access DCxx IDs.

Each formatting instructions removes its argument from the stack, so that the next one will receive the following bytes as arguments. Code 86 takes the top four words from the stack, let's call them W1 through W4, and reorders them as W4 W1 W2 W3. This is used for languages in which industries or stations should be named not "Flinfingbury Power Plant" but "Power Plant Flinfingbury".

==Using genders and cases==
{{ottdp|1.1}} When multiple strings are combined to form a single sentence, the parts affect each other in various languages. E.g. you might have some string "The <industrytype> closes due to next month.", where <industrytype> is replaced by a name of some industry (e.g "brewery", "textile mill"). In German however the gender of the <industrytype> affects the string it is inserted into. For "brewery" ("Brauerei") the article "The" is translated with "Die", for "textile mill" ("Textilwerk") "The" is translated with "Das".

In OpenTTD these interactions of strings are called "genders" and "cases". While these names refer to the common grammatical constructions in various languages, there is a technical definition of these term wrt. OpenTTD. These might match the grammatical usages of genders and cases in some languages, or they might be used to deal with other grammatical constructions.

Generally, when a string I is inserted into a string O:
* If the inner string I affects the outer O:
** I is said to have a gender, and
** O chooses different texts depending on that gender.
* If the outer string O affects the inner I:
** O sets a case for I, and
** I chooses different texts depending on the required case.

===Setting genders and cases===
{{ottdp|1.1}} String codes 9A 0E and 9A 0F map a NewGRF internal gender or case ID to an OpenTTD gender or case. The internal ID is resolved to the appropriate OpenTTD gender or case at load time by means of the mapping. The first internal ID in the mapping that matches the ID from the string and has an existing OpenTTD gender or case is taken, i.e. the list of mappings is filtered by internal ID and existance of the OpenTTD gender/case and then the top element is used. When the gender or case ID is not known, or there is no existing OpenTTD gender or case with the mapped names the whole mapping is ignored and the default gender or case is taken.

'''Example of gender translation table'''

<pre>
// Gender translation table
// Current OpenTTD German translation uses m, w, n and p but
// support a (fictitious) previous version that used masculine,
// feminine, neuter and plural as gender names.
0 * 56 00 08 01 01 02
13
01 "m" 00
01 "masculine" 00
02 "w" 00
02 "feminine" 00
03 "n" 00
03 "neuter" 00
04 "p" 00
04 "plural" 00
00

// Brauerei is a female word in German; this sets it as female.
1 * 40 04 0A 82 01 73 DC C3 9E 9A 0E 02 "Brauerei" 00
</pre>

In this case OpenTTD would look for NewGRF internal ID 2 in the gender table. This would yield "w" and "feminine" as OpenTTD gender names. In current OpenTTD this would match "w", in the fictitious older version of OpenTTD it will match "feminine".

===Choosing strings depending on required gender or case===
{{ottdp|1.1}} String codes 9A 10 to 9A 14 map an OpenTTD gender or case to the NewGRF internal gender or case ID. The mapping is resolved at load time by going through all cases or genders OpenTTD's translation knows an mapping these to NewGRF internal IDs. If mapping is found the default choice list item is chosen. This happens by filtering the mapping on the gender or case name and then the NewGRF internal ID of the top element is used.

The choice list string codes are related and must be used in a specific manner:

Genders: 9A 13 <offset> (9A 10 <index> <string>)+ 9A 11 <default> 9A 12

Cases: 9A 14 (9A 10 <ndex> <string>)+ 9A 11 <default> 9A 12

Plurals: 9A 13 <offset> (9A 10 <index> <string>)+ 9A 11 <default> 9A 12

The offset is the stack location of the substring/value you want to get the gender/plural for. This is the real offset plus 80, i.e. an offset of 0 becomes 80 and an offset of 1 becomes 81 in the NFO.

'''Example of gender-dependent string'''

<pre>
// Assuming the translation table of the previous example
// A string with a gender choice list and a stack item that gets resolved
2 * 29 04 0A FF 01 1A DC "D" 9A 13 80 9A 10 1 "er" 9A 10 3 "as" 9A 11 "ie" 9A 12 " " 80 00
</pre>

Imagine the "Brauerei" from the previous example being, as substring, on the stack. Then this string would resolve to "Die Brauerei".

What happens in OpenTTD is that whenever the "begin gender choice list" string code is found it will resolve the string at the given stack location. Of that resolved string the first character is compared to the "set gender" string code and if that is the case the (mapped) OpenTTD gender is retrieved. When there is "set gender" string code the first OpenTTD gender is used. After resolving the OpenTTD gender that gender is reverse mapped to a NewGRF internal ID. If that NewGRF internal ID exists in one of the "choice list values" that (sub)string is taken (up till the next choice list value/default). If there is no reverse mapping the string at the "choice list default" string code is used up till the "end choice list" string code. Further processing of the string happens after the choice list, i.e. the (sub)strings in the choice list may not contain any special string codes except colour codes.

Case choice lists work in a similar matter, except that instead of resolving a case from a (sub)string we "are" the substring; the string that includes this substring has set a case using the "select case" string code. As such no offset has to be given to the choice list, but the rest works in the same way as gender choice lists.

==Using plural forms==
{{ottdp|1.1}} The plural list works like a gender list, however you have to choose one "mapping" from value to plural index by setting the plural form using [[Action0/Global Settings]] property 15.

If, for example, plural form 0 is chosen using the [[Action0/Global Settings]] property 15, then there are 2 plural indices. If the value at the stack with the given offset equals 1 you get plural index 1, otherwise plural index 2. These plural indices are the indices that are used in the choice lists.

{| |-
!Plural form!!Plural index!!Description
|-
|0||Two forms:
|-
|||1||1
|-
|||2||rest
|-
|1||Only one form:
|-
|||1||every form
|-
|2||Two forms:
|-
|||1||0 or 1
|-
|||2||rest
|-
|3||Three forms:
|-
|||1||ending in 1, but not ending in 11
|-
|||2||0
|-
|||3||rest
|-
|4||Five forms:
|-
|||1||1
|-
|||2||2
|-
|||3||3-6
|-
|||4||7-10
|-
|||5||rest
|-
|5||Three forms:
|-
|||1||ending in 1, but not ending in 11
|-
|||2||ending in 2-9, but not ending in 1[2-9]
|-
|||3||rest
|-
|6||Three forms:
|-
|||1||ending in 1, but not ending in 11
|-
|||2||ending in 2-4, but not ending in 1[2-4]
|-
|||3||rest
|-
|7||Three forms:
|-
|||1||0
|-
|||2||ending in 2-4, but not ending in 1[2-4]
|-
|||3||rest
|-
|8||Four forms:
|-
|||1||ending in 01
|-
|||2||ending in 02
|-
|||3||ending in 03 or ending in 04
|-
|||4||rest
|-
|9||Two forms:
|-
|||1||ending in 1, but not ending in 11
|-
|||2||ret
|-
|10||Three forms:
|-
|||1||1
|-
|||2||2-4
|-
|||3||rest
|-
|11||Two forms:
|-
|||1||ending in 0, 1, 3, 6, 7 and 8
|-
|||2||ending in 2, 4, 5 and 9
|-
|12||Four forms:
|-
|||1||1
|-
|||2||0 or ending in 02-10
|-
|||3||ending in 11-19
|-
|||4||rest
|}

'''Example of string using plural forms'''

<pre>
// Set the plural type to type 0
0 * 7 00 08 01 01 02 15 00
// In case of the first stack item being 1 use "Tonne", otherwise use "Tonnen"
1 * 34 04 0B 82 01 1A DC C3 9E "\UE07C Tonne" 9A 15 80 9A 10 01 "" 9A 11 "n" 9A 12 " Sand" 00
</pre>

=UTF-8 support=
{{ottdp|0.6|2.5|ttdprev=2.0.1 alpha 68}}
Since TTDPatch 2.0.1 alpha 68, TTDPatch supports UTF-8 encoded input strings. Use [[Action12|action 12]] to define glyphs for the characters which do not exist in TTD's .grf files (possible since TTDPatch 2.0.1 alpha 73).

To indicate that a given string is in UTF-8 encoding, start it with a capital thorn (U+00DE, "Þ"), encoded in UTF-8 as usual with the bytes C3 9E. Everything in that string is then assumed to be in UTF-8 encoding, with the following exception: if characters appear that are not valid UTF-8 sequences, they are assumed to be one of the above control codes. This way, it is still possible to write, e.g. "ÞCapacity: " 87 "litres", without encoding the 87 in UTF-8 (which would instead refer to a character installed at codepoint U+0087).

In addition, this allows using the non-Unicode characters 9E, 9F, A0, AA, AC, AD, AF, B4..B9, BC and BD from the above list, which when encoded with UTF-8 would refer to their respective Unicode characters instead. To use the TTD characters, simply do not encode them using UTF-8 but enter them directly as bytes. This causes them to be an invalid UTF-8 sequence and allows TTDPatch to use the correct symbol from TTD's fonts.

Alternatively, these symbols (in fact, the TTD character set from 20 to FF) are also mapped into the Unicode Private Use Area at U+E0xx, so to encode the truck symbol, you may use character U+E0B5 as well, although this will probably be an unprintable character in most text editors.

Finally, characters 7B..7F no longer function as the above formatting instructions, but will display regular glyphs instead (provided they are installed; by default TTD has none at these codepoints). Instead, to use these formatting instructions in UTF-8 mode, you need to use their Private Use Area codepoint at U+E0xx.

Basically there are three possibilities:
# Characters U+E020..U+E0FF in the E0xx Private Use Area do what their respective character xx would do in TTD, as do the control characters below U+0020
# All other valid UTF-8 sequences display actual glyphs, if they are available
# All invalid UTF-8 sequences do what their individual bytes would do in TTD

To summarize, here's a handy table:

{| |-
!Character!!Encoding in UTF-8 mode!!Meaning
|-
|7E||7E||Unicode Character 'TILDE' (~)
|-
|82||82 (invalid UTF-8)||Print date (day, month, year)
|-
|82||C2 82||Display glyph for U+0082
|-
|AC||AC (invalid UTF-8)||Tick mark
|-
|AC||C2 AC||Unicode Character 'NOT SIGN' (¬)
|-
|E07E||EE 81 BE||Print unsigned word
|-
|E082||EE 82 82||Print date (day, month, year)
|-
|E0AC||EE 82 AC||Tick mark
|}

NML:Vehicles

2011-10-20T17:15:22Z

Yexo: small paragraph about sorting vehicles in the purchase list.

{{NMLNavPropVarCB}}

==Properties common to all vehicle types==

{| class="t"
! property
! value range
! available for articulated vehicle
! comment
|-
| <code style="color:green">name</code>
| (string)
| yes
| for example <code style="color:darkgreen">string(STR_NAME_HEREFORD_TRAM)</code>
|-
| <code style="color:green">climates_available</code>
| bitmask(CLIMATE_XXX, CLIMATE_YYY, ...)
| set to <code style="color:green">NO_CLIMATES</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">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
|}

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 articulated vehicle
! comment
|-
| <code style="color:green">sprite_id</code>
| <code style="color:green">SPRITE_ID_NEW_TRAIN</code>
| yes
| Set this property to enable new graphics
|-
| <code style="color:green">speed</code>
| 0 ... 65000 (float, speed units)
| no
| Max speed for engines, speed limit for wagons
|-
| <code style="color:green">misc_flags</code>
| bitmask(TRAIN_FLAG_XXX, ...)
| FLIP should not be set, TILT and MU the same value
| XXX=[TILT <nowiki>|</nowiki> 2CC <nowiki>|</nowiki> MU <nowiki>|</nowiki> FLIP] which allows the train to enjoy the tilt bonus, use the 2nd company colour, act as a multiple unit (used for livery selection only) or allow the vehicle to be flipped (reversed) in the depot
|-
| <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
|
|-
| <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>
|-
| <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 articulated vehicle
! comment
|-
| sprite_id
| SPRITE_ID_NEW_ROADVEH
| yes
| Set this property to enable new graphics
|-
| speed
| 0 ... 514km/h (float, speed units)
| no
|
|-
| misc_flags
| bitmask(ROADVEH_FLAG_XXX, ...)
| partly; tram flag must the same
| The following flags are defined: ROADVEH_FLAG_TRAM, ROADVEH_FLAG_2CC. 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
|
|-
| 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)
| Bitmask with (currently) only one possible flag, set to 0 to disable
|-
| refit_cost
| 0 ... 255
| in 1/32 of the default refit cost base
|-
| callback_flags
| bitmask(VEH_CBF_XXX, ...)
|
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
|
|-
| 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.
|}

==Plane 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)
|
|-
| misc_flags
| bitmask(AIRCRAFT_FLAG_2CC)
| Bitmask with (currently) only one possible flag, set to 0 to disable
|-
| refit_cost
| 0 ... 255
| in 1/32 of default refit cost base
|-
| callback_flags
| bitmask(VEH_CBF_XXX, ...)
|
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
|
|-
| mail_capacity
| 0 ... 255
|
|-
| 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 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
|
[[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
|-
| vehicle_type_id
|
| No
| ID of 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_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
| Not valid before 1920 and after 2090.
|-
| 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 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==

{| 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
|-
| 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 0xFF
| 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 0xFF. 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 HEQS 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 0xFF
| Called when starting or stopping a vehicle. Mainly useful to prevent vehicles from leaving the depot unless a certain condition is met. Return 0xFF 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 0xFF
| With this callback, you can add articulated parts (e.g. tenders) to your vehicle. Called repeatedly, until 0xFF 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. Add 128 to the returned vehicle ID to display the vehicle backwards. This has the unfortunate side-effect of requiring the vehicle ID of the articulated part to be in the range 0 .. 127, currently there's no way around this limitation.
|-
| 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
|
|-
| 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
|
|-
| 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
|}

Action4

2011-10-19T11:15:51Z

Yexo: /* Syntax */

==Introduction==
Define strings, e.g vehicle, house or industry names

When making new vehicle graphics, you also need to name the new vehicles, or they'll show up with their original name from TTD.
However, custom vehicle names assigned by the player in-game (or for TTDPatch also via TTD's vehicle.dat) will always take precendence.

In TTDPatch you can also use this action to change most of TTD's text strings.

== Syntax ==

The data looks as follows:

<Sprite-number> * <Length> '''04''' <feature> <language-id> <num-ent> <offset> <text>

{| |-
!Element!![[GRFActionsDetailed|Size]]!!Description
|-
|<Sprite-number>||dec||A sequential sprite number
|-
|<length>||dec||The total number of bytes used in this action.
|-
|04||B||Defines action 04
|-
|<feature>||B||For what type of vehicle/station should this definition be used?
|-
|<language-id>||B||Which of TTD's languages this name is for
|-
|<num-ent>||B||Number of consecutive strings to change
|-
|<offset>||B/W||First ID to change
|-
|<text>||S||New text strings
|}

Whether <offset> is a '''BYTE''' (extended byte in openttd for vehicles) or a '''WORD''' is decided by bit 7 of <language-id>, see below.

== Descriptions ==

=== 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
|-
|07||Houses
|-
|0A||Industries
|-
|0B||Cargos
|-
|0D||Airports
|-
|0F||Objects
|-
|10||Railtypes
|-
|48||Original strings; see [[TextIDs]] for a list of TTD's text IDs.
|}

=== language IDs ===
The meaning of this byte depends on the GRF version of the .grf file as set in [[Action8#version|action 8]].

{{grf|6}} Up to version 6, this is a bit mask of the following bits:

{| |-
!Bit!!Value!!Meaning
|-
|0||01||American or "other"
|-
|1||02||English
|-
|2||04||German
|-
|3||08||French
|-
|4||10||Spanish
|-
|7||80||Flag for 16 bit string IDs
|}

Add the bits of all languages for which the following strings apply. Bit 7 controls, whether the following string ID consists of 16 or 8 bit. Unknown languages will use the American strings as fallback. Otherwise the string would remain undefined for these languages. To actually define strings for any new language, you must use grf version 7.

{{grf|7}} For version 7 and higher, it is a simple language ID from the list below. (This has changed with TTDPatch 2.5 beta 4). Bit 7 has the same meaning as in the earlier versions above.

In either scheme, you can use the value 7F or FF, respectively, to define strings shown for languages that you do not provide translation for. First set all strings to a default value using this, and later override the language specific ones if they exist.

Currently, the scheme is to use international phone codes as language IDs, unless they're out of range, in which case pick a number vaguely related in some way. Or something else.

{| |-
!ID (hex)!!Language!!Plural form <ref>For a list of plural forms see [[StringCodes]]. As the assignment of plural forms to languages is in fact not as fixed as one might expect, the used plural form is defined by each GRF separately for its strings using [[Action0GeneralVariables]] property 15.</ref>
|-
|00||American||0
|-
|01||English||0
|-
|02||German||0
|-
|03||French||2
|-
|04||Spanish||0
|-
|05||Esperanto||0
|-
|06||Ido||0
|-
|07||Russian||6
|-
|08||Irish||4
|-
|09||Maltese||12
|-
|0A||Tamil||0
|-
|0B||Chuvash||0
|-
|0C||Chinese (Traditional)||1
|-
|0D||Serbian||6
|-
|0E||Norwegian (Nynorsk)||0
|-
|0F||Welsh||0
|-
|10||Belarusian||6
|-
|11||Marathi||0
|-
|12||Faroese||0
|-
|14||Arabic (Egypt)||1
|-
|15||Czech||10
|-
|16||Slovak||10
|-
|18||Bulgarian||0
|-
|1B||Afrikaans||0
|-
|1E||Greek||2
|-
|1F||Dutch||0
|-
|21||Basque||0
|-
|22||Catalan||0
|-
|23||Luxembourgish||0
|-
|24||Hungarian||2
|-
|26||Macedonian||0
|-
|27||Italian||0
|-
|28||Romanian||0
|-
|29||Icelandic||0
|-
|2A||Latvian||3
|-
|2B||Lithuanian||5
|-
|2C||Slovenian||8
|-
|2D||Danish||0
|-
|2E||Swedish||0
|-
|2F||Norwegian (Bokmal)||0
|-
|30||Polish||7
|-
|31||Galician||0
|-
|32||Frisian||0
|-
|33||Ukrainian||6
|-
|34||Estonian||0
|-
|35||Finnish||0
|-
|36||Portuguese||0
|-
|37||Brazilian Portuguese||2
|-
|38||Croatian||6
|-
|39||Japanese||1
|-
|3A||Korean||11
|-
|3C||Malay||0
|-
|3E||Turkish||1
|-
|42||Thai||1
|-
|54||Vietnamese||1
|-
|56||Chinese (Simplified)||1
|-
|5A||Indonesian||1
|-
|5C||Urdu||0
|-
|61||Hebrew||0
|-
|62||Persian||0
|-
|80||Flag 16 bit string IDs (added to language ID)||
|-
|7F||any (will be applied no matter what language is active)||
|}

<references/>

When translating for a new language, please simply edit this document and add the new definition here.

=== num-ent ===

How many consecutive entries to change.

=== offset ===

The ID of the first string to change.

When language-id bit 7 is clear, this is a byte value; For OpenTTD since r13482, where it is an extended byte value for vehicles.

When language-id bit 7 is set, this is a word value in little endian notation, e.g. 8134 becomes 34 81.

The 8 bit version is only allowed for vehicles to set their name, in which case the text ID is just the vehicle ID.
To replace original texts, or to define texts for usage in callbacks or properties of vehicles, stations, houses or industries you have to use the 16 bit version. However, town names are changed with [[ActionF|Action F]].

For the usable 16 bit text IDs see the table below, resp. for feature 48 see [[TextIDs]].

Though these ranges are shared across all features, you should still set the proper feature you are using them for.

{| |-
!ID!!Content
|-
|C4xx||Set name of station class associated with station ID xx; this is the text above the preview (where otherwise TTD shows "Orientation")
|-
|C5xx||New station names, this changes the text "number of platforms" into the given text when the station with this ID from the current set is selected (i.e. xx=station-id from action 3 and 0)
|-
|C9xx||Name of the house type of this ID. If both property 12 and this is set, the latest definition is used always. You should prefer setting property 12 instead of this, so executables translated with TTD Translator will show the name in the current language. However, if you can't find any suitable old TTD texts, this can be used to specify your custom name. Don't forget to set the same text for all parts of a multi-tile building.
|-
|D0xx||Miscellaneous graphics texts, unique to each .grf file. Used for newobjects and several callbacks. Some callbacks as well as newobjects support IDs up to D3FF.
|-
|D4xx||'''Never use in Action4''', only for displaying textids in range D000-D3FF (grf specific), see [[TextIDs]]
|-
|D8xx||'''Never use in Action4''', only usable in Action0 features, see [[TextIDs]]
|-
|DCxx||Set miscellaneous persistent GRF texts. Unlike the D0xx GRF texts, these IDs can be used to set properties. The text ID must be set before any action 0 references it.
|}

The DCxx IDs are allocated internally when defined, and are persistent in the savegame data. Each .grf file gets its own separate map of these internal IDs and thus may set all 256 of them.  However, only 1024 IDs are available in total, to be shared by all .grf files ever activated in the savegame. This means these IDs should be used as sparingly as possible. But use them when they are useful!

=== text ===

This is a list of zero-terminated strings, there must be as many strings as num-ent specifies.

Grfcodec version 0.9.6 or later accepts literal strings in the .nfo. These are encoded exactly as written, in whatever encoding your text editor uses; if you need a 00, put it immediately after the literal string.
For the supported encodings, format, and restrictions on what characters you may use, please see [[GRFActionsDetailed#Strings|GRFActionsDetailed]] and StringCodes.

A large number of original TTD strings require a colour code in front of the actual string. You can also use these colour codes in most of your custom strings. Use them wisely! In case a string requires a colour code, the string will have the code displayed in front of the default text as listed in [[TextIDs]].Typically, a colour coded string starts with the escape character (backslash), followed by hex byte and then the actual text string itself. I.e. string 0001 ("\94Off edge of map") has colour code 0x94 in front of the text string, which will colour it white. You can also put the plain hex byte outside the quoted string without having to escape it. ''94 "Off edge of map"'' would be the same as ''"\94Off edge of map"''

The following 16 colour codes are available for use:

{| |-
!'''Code'''!!'''Colour'''
|-
|88||Blue
|-
|89||Light Grey
|-
|8A||Yellow
|-
|8B||Red
|-
|8C||Light Purple
|-
|8D||Beige
|-
|8E||Light Orange
|-
|90||Light Yellow
|-
|91||Light Green
|-
|92||Light Pink
|-
|93||Brown
|-
|94||White
|-
|95||Light Blue
|-
|96||Grey
|-
|97||Purple
|-
|98||Black
|}

==Example==

ActionE

2011-10-07T23:11:30Z

Yexo: /* Notes */

== Introduction ==

Deactivate other graphics files or force activation of current file.

Normally, graphics files should use [[Action7]] to deactivate themselves, if they find that other incompatible graphics have been loaded.

However, when new sets come out, it is often not feasible to change all existing sets so that they can detect the new set. This action therefore allows the new graphics set to deactivate older sets with which it is incompatible.

== Syntax ==

The data looks as follows:

<Sprite-number> * <Length> 0E <num> <GRFIDs...>

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

|-
|<Sprite-number>||dec||A sequential sprite number

|-
|<length>||dec||The total number of bytes used in this action.

|-
|0E||B||Defines action 0E

|-
|<num>||B||Number of sets which should be deactivated

|-
|<GRFIDs...>||4*B||GRFIDs of the sets to deactivate
|}

== Description ==

=== Sprite-number ===

This is just the number you are at.

=== Length ===

Count the number of bytes in this action.

=== num ===

This is the number of sets you want to deactivate.

=== GRFIDs ===

Here you give the list of GRFIDs, in the same format as in [[Action8]], which should be deactivated.

=== Notes ===

Note that it is invalid to attempt the deactivation of already active graphics files. You can only prevent files lower down the newgrf(w).cfg from becoming active later. Therefore, you must check that none of the GRFIDs in this list are active already using the appropriate action 7. If the deactivation of an already active set is attempted, the current set is considered invalid and will be disabled.

If you attempt to deactivate a set that isn't loaded, nothing happens.

To handle the cases of incompatible sets being loaded and activated earlier, you can either attempt to overwrite all their settings and graphics, or simply deactivate this set in turn.

If the given GRFID is identical to the GRFID of the file currently being processed, the current file is force-activated. This is most useful for making changes to the title screen menu, which would otherwise not be possible. It is strongly recommended not to use this feature in any way other than in combination with an action 7 that checks variable 92 (game mode) so that the activation only happens in the title screen. Otherwise the GRF Status Windows (de)activation is bypassed entirely.

It is best to limit this forced activation to as few actions as possible for maximum compatibility. Forced activation is not supported by OpenTTD.

In principle, there can be four cases and your .grf file must be able to handle all of them properly:
* The .grf file is active and can not be deactivated.
: You cannot use action E in this case.
* The .grf file is inactive but will be activated.
: This is the only case in which action E is useful, the .grf file coming below the current one in newgrf(w).cfg but being set to be activated. Action E will set it to not be activated when it is processed.
* The .grf file is inactive and will not be activated.
: This can happen because it has been processed already (it comes earlier in newgrf(w).cfg) and was deactivated, either by default or manually.

== Example ==

The following is an example to deactivate GRFID 54570105 if possible, and deactivate the current file instead if not.

47 * 9 07 88 04 06 54 57 01 05 02
48 * 9 07 88 04 08 54 57 01 05 03
49 * 6 07 83 01 03 7F 04
50 * x 0B 01 1F FF ... (e.g. "This file is deactivated because incompatible graphics are active.")
51 * 6 07 83 01 03 7F 00
52 * x 0B 01 1F FF ... (e.g. "Deactivating GRFID 54570105.")
53 * 6 0E 01 54 57 01 05

This carries out the following instructions:

<pre>47: if (GRFID 54570105 is active) goto 50

48: if (GRFID 54570105 is inactive but will be activated) goto 52

49: goto 54

50: showmessage("This file is deactivated because incompatible graphics are active.")

51: deactivate_current_file

52: showmessage("Deactivating GRFID 54570105.")

53: deactivate(54570105);

continue_with_current_file;</pre>

The reason for this particular order of pseudo-sprites is that action 7 will not take a branch if the queried GRFID is not present at all. In that case, both sprites 47 and 48 fall through, which means the jump in 49 is carried out and the file resumes processing. The unconditional gotos in 49 and 51 are actually conditional on the climate not being 7F, which it never can be.

Conceptually, without goto-logic, the code could be described by

<pre>if (GRFID 54570105 is active) {

showerror("This file is deactivated because incompatible graphics are active.")

deactivate_current_file

} else if (GRFID 54570105 is inactive but will be activated) {

showmessage("Deactivating GRFID 54570105.")

deactivate(54570105);

}</pre>

NML:Alternative sprites

2011-10-03T15:17:04Z

Yexo: Name of block is "alternative_sprites", not "alt_sprites"

{{NMLNavBlocksyntax}}

A <code style="color:darkgreen">alternative_sprites</code> block allows you to specify alternative 32bpp sprites that are drop-in replacements for some real sprites in your grf. The syntax is as follows:

alternative_sprites(block_name, zoom_level[, filename]) {
[[NML:Realsprites|list of realsprites]]
}

block_name is the name of the replace/replace_new/fontglyph/spriteset-block for which you want to provide 32bpp sprites. zoom_level can be one of <code style="color:darkgreen">ZOOM_LEVEL_NORMAL, ZOOM_LEVEL_Z0, ZOOM_LEVEL_Z1 or ZOOM_LEVEL_Z2</code>. Please note that <code style="color:darkgreen">ZOOM_LEVEL_NORMAL</code> and <code style="color:darkgreen">ZOOM_LEVEL_Z2</code> are exactly the same, and that <code style="color:darkgreen">ZOOM_LEVEL_Z0</code> and <code style="color:darkgreen">ZOOM_LEVEL_Z1</code> are for the [http://wiki.openttd.org/32bpp_Extra_Zoom_Levels extra zoom project] only (3rd party project, not officially supported). Specifying a filename is optional, it's only useful if you have multiple sprites in the same file. If every sprite is in a separate file you'll have to specify the filename for each realsprite anyway, so you can leave it out of the alternative_sprites-block.

NML:GRF

2011-09-13T14:07:39Z

Yexo:

{{NMLNavBlocksyntax}}

== GRF block ==

Syntax:

grf {
grfid: <literal-string>;
name: <string>;
desc: <string>;
version: <expression>;
min_compatible_version: <expression>;
<param { ... }>
}

== GRF parameters ==

As part of the grf block you can specify some parameter settings that the user will be able to change as part of the newgrf configuration. These can for example be used to disable parts of your NewGRF or to change between multiple graphics in case that's not possible at runtime. In general the settings (sub-)block looks like

param <num> {
<name> {
type: <type>;
name: <string>;
desc: <string>;
min_value: <expression>;
max_value: <expression>;
def_value: <expression>;
bit: <expression>;
names: {
0: <string>;
1: <string>;
.
.
.
};
}
}

Looking at the single entries:

<num>

Optional, you can specify in which param number this setting should be stored.

type

This defines the parameter type. Possible values are <code style="color:darkgreen">bool</code> for on/off statements or <code style="color:darkgreen">int</code> for positive integer values

name

This gives the parameter name as shown in the parameter configuration dialogue of OpenTTD.

desc

This gives the description which is displayed when the parameter is selected. Here you can explain the meaning and impact it will have

min_value

The minimum acceptable value for the parameter (only valid for type int), default of min_value is 0

max_value

The maximum acceptable value for the parameter (only valid for type int), default of max_value = 0xFFFFFFFF

def_value

This sets the default value for this parameter. If left out, the default value of 0 will be used.

bit

Only valid for settings with type "bool". The value is the bit in which this setting should be stored.

names

If you chose type <code style="color:darkgreen">int</code> and the numbers themselves are only used internally, have no direct numerical meaning and are better explained in words, you can use this to associate the single numbers with a string which describes it and is shown to the user instead of the value.

== A simple example ==

<pre style=example>
grf {
grfid: "AB\03\02";
name: string(STR_GRF_NAME);
desc: string(STR_GRF_DESC);
version: 1;
min_compatible_version: 0;
param {
param_provide {
type: int;
name: string(STR_PARAM_PROVIDE);
desc: string(STR_PARAM_PROVIDE_DESC);
min_value: 0;
max_value: 1;
def_value: 0;
names: {
0: string(STR_PARAM_PROVIDE_ENGINES_AND_WAGONS);
1: string(STR_PARAM_PROVIDE_WAGONS_ONLY);
};
}
}
}</pre>

NML:Towns

2011-09-11T10:58:11Z

Yexo: Created page with "{{NMLNavPropVarCB}} Towns aren't a NewGRF feature of their own but town variables can be accessed via the parent scope of stations, houses and industries. ==Town variables== …"

{{NMLNavPropVarCB}}

Towns aren't a NewGRF feature of their own but town variables can be accessed via the parent scope of stations, houses and industries.

==Town variables==

{| class="t"
! name
! value range
! comment
|-
| is_city
| [0 <nowiki>|</nowiki> 1]
| 1 if this town is marked as a "city", 0 if it's not.
|-
| cities_enabled
| [0 <nowiki>|</nowiki> 1]
| 1 if the advanced setting for cities is enabled, 0 otherwise.
|-
| has_church
| [0 <nowiki>|</nowiki> 1]
| 1 if there is a church in the town.
|-
| has_stadium
| [0 <nowiki>|</nowiki> 1]
| 1 if there is a stadium in the town.
|-
| population
| 0..65536
| Population of the town
|-
| num_houses
| 0..65536
| Number of houses
|-
| percent_transported_passengers
| 0..100
| Percentage of all passengers available for transported that were transported.
|-
| percent_transported_mail
| 0..100
| Percentage of all mail available for transported that was transported.
|-
| town_zone_0_radius_square
| 0..65536
| rowspan="5" | See [http://newgrf-specs.tt-wiki.net/wiki/TownZones TownZones page in NFO specs]
|-
| town_zone_1_radius_square
| 0..65536
|-
| town_zone_2_radius_square
| 0..65536
|-
| town_zone_3_radius_square
| 0..65536
|-
| town_zone_4_radius_square
| 0..65536
|}

NML:Properties and variables and callbacks

2011-09-11T10:30:55Z

Yexo: add link to town variables

{{NMLNavPropVarCB}}

Select a topic from the table below or use the navigation pane at the right.

{|
|[[NML:General|General]] || || [[NML:General#General variables|variables]] ||
|-
|[[NML:Vehicles|Vehicles]] || [[NML:Vehicles#Properties common to all vehicle types|common properties]] || [[NML:Vehicles#Vehicle variables|variables]] || [[NML:Vehicles#Vehicle callbacks|callbacks]]
|-
| || [[NML:Vehicles#Train properties|train properties]] || ||
|-
| || [[NML:Vehicles#Road vehicle properties|road vehicle properties]] || ||
|-
| || [[NML:Vehicles#Ship properties|ship properties]] || ||
|-
| || [[NML:Vehicles#Plane properties|aircraft properties]] || ||
|-
|[[NML:Stations|Stations]] || [[NML:Stations#Station properties|properties]] || [[NML:Stations#Station variables|variables]] || [[NML:Stations#Station callbacks|callbacks]]
|-
|[[NML:Canals|Canals]] || [[NML:Canals#Canal properties|properties]] || [[NML:Canals#Canal variables|variables]] || [[NML:Canals#Canal callbacks|callbacks]]
|-
|[[NML:Bridges|Bridges]] || [[NML:Bridges#Bridge properties|properties]] || [[NML:Bridges#Bridge variables|variables]] || [[NML:Bridges#Bridge callbacks|callbacks]]
|-
|[[NML:Towns|Towns]] || || [[NML:Towns@Town variables|variables]] ||
|-
|[[NML:Houses|Houses]] || [[NML:Houses#House properties|properties]] || [[NML:Houses#House variables|variables]] || [[NML:Houses#House callbacks|callbacks]]
|-
|[[NML:Industries|Industries]]|| || [[NML:Industries#Common variables|common variables]] ||
|-
| || [[NML:Industries#Industry properties|industry properties]] || [[NML:Industries#Industry variables|industry variables]] || [[NML:Industries#Industry callbacks|industry callbacks]]
|-
| || [[NML:Industries#Industry tile properties|tile properties]] || [[NML:Industries#Industry tile variables|tile variables]] || [[NML:Industries#Industry tile callbacks|tile callbacks]]
|-
|[[NML:Cargos|Cargos]] || [[NML:Cargos#Cargo properties|properties]] || [[NML:Cargos#Cargo variables|variables]] || [[NML:Cargos#Cargo callbacks|callbacks]]
|-
|[[NML:Airports|Airports]] || [[NML:Airports#Airport properties|properties]] || [[NML:Airports#Airport variables|variables]] || [[NML:Airports#Airport callbacks|callbacks]]
|-
| || [[NML:Airports#Airport tile properties|tile properties]] || [[NML:Airports#Airport tile variables|tile variables]] || [[NML:Airports#Airport tile callbacks|tile callbacks]]
|-
|[[NML:Objects|Objects]] || [[NML:Objects#Object properties|properties]] || [[NML:Objects#Object variables|variables]] || [[NML:Objects#Object callbacks|callbacks]]
|-
|[[NML:Railtypes|Railtypes]] || [[NML:Railtypes#Railtype properties|properties]] || [[NML:Railtypes#Railtype variables|variables]] || [[NML:Railtypes#Railtype callbacks|callbacks]]
|}

NML:Realsprites

2011-09-08T18:11:04Z

Yexo:

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

The following table contains a list of compression flags. Multiple flags may be combined using the binary-OR (|) operator.

{| 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:Language files

2011-08-31T12:17:25Z

Yexo: /* String codes */

{{NMLNavNoSubpages}}
== Introduction ==
Language files are usually found in the <code style="color:darkgreen">lang</code> sub-folder of the project, but the place NML looks for the language files can be changed via command line parameter to any directory desired:

nmlc -l path/to/lang-dir path/to/nml-source-file.nml
nmlc --lang-dir=path/to/lang-dir path/to/nml-source-file.nml

Language files MUST have the extension <code style="color:darkgreen">.lng</code> The language files themselves follow a certain structure:

##grflangid <number>
<string-name> :<text>
<string-name> :<text>
...

where the first line must give the language code for the language this file describes (see below). The following lines each describe a string. The translated string follows immediately the colon. An NML project has exactly one fallback language, by default this is english.lng. You can change this with the command line parameter --default-lang. Example for a valid language file:

<pre class=example>
##grflangid 0x01
STR_GRF_NAME :{TITLE} 0.1.0 - {VERSION}
STR_GRF_DESCRIPTION :{TITLE} contains pimped ground tiles.
STR_NAME_MYVEHICLE :General Robotics Anti-Grav UFO Mark X
</pre>

== String codes ==

Strings may contain a number of special string codes which control how the string is being printed or which values to insert into the string. Custom replacements can be stored in the plain text file <code>custom_tags.txt</code> (for example a newgrf version which is written by your build script). In the case above the <code>custom_tags.txt</code> could, for example read

<pre class=example>
VERSION :alpha-r88
TITLE :Example NewGRF
</pre>

Additionally to custom-defined tags, NML comes with a number of default tags:
{|
!width="150pt"|Tag
!width="600pt"|Meaning
!Example
|-
| ||empty tag, written as {} is used to create a newline
|-
|NBSP || non-breaking space
|-
|{ || Display a left curly bracket. You write this as {{}. If you'd include it without surrounding it by { and } it'd be seen as the start of a tag and the rest of the string would be read as name of the tag.
|-
|COPYRIGHT || copyright symbol || ©
|-
|TRAIN || display train symbol
|-
|LORRY || display lorry symbol
|-
|BUS || display bus symbol
|-
|PLANE || display plane symbol
|-
|SHIP || display ship symbol
|-
|TINYFONT || switch to small font
|-
|BIGFONT || switch to big font
|-
|BLUE || switch to blue text
|-
|SILVER || switch to silver text
|-
|GOLD || switch to golden text
|-
|RED || switch to red text
|-
|PURPLE || switch to purple text
|-
|LTBROWN || switch to light brown text
|-
|ORANGE || switch to orange text
|-
|GREEN || switch to green text
|-
|YELLOW || switch to yellow text
|-
|DKGREEN || switch to dark green text
|-
|CREAM || switch to cream-coloured text
|-
|BROWN || switch to brown text
|-
|WHITE || switch to white text
|-
|LTBLUE || switch to light blue text
|-
|GRAY || switch to gray text
|-
|DKBLUE || switch to dark blue text
|-
|BLACK || switch to black text
|}

The above tags can be used in almost all strings. There are also a number of tags that need an argument they'll read from the textstack. The textstack is only available for certain callbacks an properties.
{|
!width="150pt"|Tag
!width="600pt"|Meaning
!Size (number of bytes read from stack)
!Example
|-
|COMMA || signed number with decimal separator between 1000's. || 4
|-
|SIGNED_WORD || signed number with decimal separator between 1000's. || 2
|-
|UNSIGNED_WORD || unsigned number with decimal separator between 1000's. || 2
|-
|CURRENCY || money in proper currency units || 4 || 24,492 €
|-
|VELOCITY || velocity in proper units || 2 || 35 km/h
|-
|VOLUME || volume in proper units || 2 || 29,000 l
|-
|POWER || power in proper units || 2 || 2,030 kW
|-
|WEIGHT || weight in proper units || 2
|-
|HEX || hexadecimal presentation || 4 || F0 3D D4 33
|-
|STRING || include other string || 2
|-
|DATE1920_LONG || days since 1920 as long date || 2 || 12 August 1935
|-
|DATE1920_SHORT|| days since 1920 as short date || 2 || 12 Aug 1935
|-
|DATE_LONG || days since 0 as long date || 4 || 12 August 1610
|-
|DATE_SHORT || days since 0 as short date || 4 || 12 Aug 3049
|-
|POP_WORD || Remove 2 bytes from the top of the stack || 2
|-
|STRING || Station name of station with given ID || 2
|}

In case you don't want to use the first 2 (or 4) bytes from the stack but rather another variable, you can prefix the tag name with the number, like {1:COMMA} to use the second (indexing starts at 0) argument from the stack. You can also use this in translations that require a different order, for example (in english.lng):

STR_SOME_STRING :{COMMA} items cost {CURRENCY}

And the same string in dutch.lng:

STR_SOME_STRING ;{!:CURRENCY} is de prijs van {0:COMMA} items.

== Defining cases ==
Similar to OpenTTD's language files, NML can also make use of cases, genders and plural forms. In order to utilize them, they have to be defined in the language file's header and have to match the definition as used in OpenTTD's language files:
<pre>
##case pragma

STR_NAME :Utas
STR_NAME.pragma :utast
</pre>

e.g. for Hungarian you'd have
<pre class=example>
##case t ba

STR_CARGO_PLURAL_PASSENGERS :Utas
STR_CARGO_PLURAL_PASSENGERS.t :utast
</pre>

== Defining genders ==
Genders just like cases are defined in the header of the language file and have to match the definition as found within OpenTTD's language files. The gender of a word or expression is declared within the string's text itself by a tag of the form <code>{G=gendername}</code>:
<pre>
##gender pragma

STR_NAME :{G=gendername}String which requires gender 'gendername'
</pre>
where the string with the defined gender then will trigger the correct usage in a string which includes it and which has to take provisions to show the proper gender:
<pre>
STR_OTHER :Some text {G gender1 gender2 ...} {STRING}
</pre>

for example in German
<pre class=example>
##gender m w n p

STR_CARGO_NAME_BAUXITE :{G=n}Bauxit
</pre>
which then will be used with the correct gender by a string which includes it:
<pre class=example>
STR_NEWS_STATION_NO_LONGER_ACCEPTS_CARGO :{WHITE}{STATION} akzeptiert kein{G "en" "e" "" "e"} {STRING} mehr.
</pre>

== LanguageIDs ==

Valid language IDs are listed in the table below. The cases, genders and number of plural forms is only given as reference. Authorative are the definitions in OpenTTD's language file for each language.

{| class="t"
! ID
! language
! cases
! genders
! plurals
|-
| 00
| American
|
|
|
|-
| 01
| English
|
|
|
|-
| 02
| German
|
| m w n p
|
|-
| 03
| French
|
| m m2 f
| 2
|-
| 04
| Spanish
|
| m f
|
|-
| 05
| Esperanto
|
| n
|
|-
| 06
| Ido
|
|
|
|-
| 07
| Russian
| m f n p nom gen dat acc abl pre
| m f n p
| 6
|-
| 08
| Irish
|
|
| 4
|-
| 09
| Maltese
|
|
| 12
|-
| 0A
| Tamil
|
|
|
|-
| 0B
| Chuvash
|
|
|
|-
| 0C
| Chinese (Traditional)
|
|
| 1
|-
| 0D
| Serbian
| nom big gen dat aku vok lok ins
| muški ženski srednji
| 6
|-
| 0E
| Norwegian (Nynorsk)
| small
| masculine feminine neuter
|
|-
| 0F
| Welsh
|
|
|
|-
| 10
| Belarusian
| m f n p nom gen dat acc abl pre
| m f n p
| 6
|-
| 11
| Marathi
|
|
|
|-
| 12
| Faroese
|
| m f n
|
|-
| 14
| Arabic (Egypt)
|
|
| 1
|-
| 15
| Czech
| nom gen dat acc voc loc ins big small
| m f n map mnp fp np
| 10
|-
| 16
| Slovak
| g
| m z s
| 10
|-
| 18
| Bulgarian
| m f n p
| m f n p
|
|-
| 1B
| Afrikaans
|
| male
|
|-
| 1E
| Greek
| subs date geniki
| m f n
| 2
|-
| 1F
| Dutch
|
|
|
|-
| 21
| Basque
|
|
|
|-
| 22
| Catalan
|
| Masculin Femenin
|
|-
| 23
| Luxembourgish
|
|
|
|-
| 24
| Hungarian
| t ba
|
| 2
|-
| 26
| Macedonian
|
|
|
|-
| 27
| Italian
| ms mp fs fp
| m ma f
|
|-
| 28
| Romanian
|
|
|
|-
| 29
| Icelandic
|
| karlkyn kvenkyn hvorugkyn
|
|-
| 2A
| Latvian
| kas
| m f
| 3
|-
| 2B
| Lithuanian
| kas ko kam ka kuo kur kreip
| vyr mot
| 5
|-
| 2C
| Slovenian
| r d t
|
| 8
|-
| 2D
| Danish
|
|
|
|-
| 2E
| Swedish
|
|
|
|-
| 2F
| Norwegian (Bokmal)
| small
| masculine feminine neuter
|
|-
| 30
| Polish
| d c b n m w
| m f n
| 7
|-
| 31
| Galician
|
| m f n
|
|-
| 32
| Frisian
|
|
|
|-
| 33
| Ukrainian
| r d z
| m f s mn
| 6
|-
| 34
| Estonian
| g in sü
|
|
|-
| 35
| Finnish
|
|
|
|-
| 36
| Portuguese
|
| n m f mp fp
|
|-
| 37
| Brazilian Portuguese
|
| m f
| 2
|-
| 38
| Croatian
| nom gen dat aku vok lok ins
| male female middle
| 6
|-
| 39
| Japanese
|
|
| 1
|-
| 3A
| Korean
|
| m f
| 11
|-
| 3C
| Malay
|
|
|
|-
| 3E
| Turkish
| tamlanan
|
| 1
|-
| 42
| Thai
|
|
| 1
|-
| 54
| Vietnamese
|
|
| 1
|-
| 56
| Chinese (Simplified)
|
|
| 1
|-
| 5A
| Indonesian
|
|
| 1
|-
| 5C
| Urdu
|
| m f
|
|-
| 61
| Hebrew
| singular plural gen
| m f
|
|-
| 62
| Persian
|
|
|
|}

In case a language is not in this list, check the [[Action4#language IDs|master language list]] (for GRFv7) in the NewGRF Specs. This master list is always leading. NFO language ID 7F has no meaning in NML (set --default-lang instead) and setting bit 16 will break your language file.