GRFSpecs - User contributions [en-gb]

NML:Railtypetable-Roadtypetable-Tramtypetable

2019-12-28T13:22:14Z

Andrew350: added note about road and tramtypes, also label usage

{{NMLNavBlocksyntax}}

'''Note:''' The syntax for <code style="color:darkgreen">roadtypetable</code> and <code style="color:darkgreen">tramtypetable</code> are identical to that of <code style="color:darkgreen">railtypetable</code> as described below

railtypetable {
ITEM [, ITEM]*
}

Each <code style="color:darkgreen">ITEM</code> can be either a 4-byte long Identifier or string or it can have this format:

ID : [ ID[, ID]* ]

The first ID is the name (doesn't have to be 4-bytes long), the other IDs are a list of labels that are assigned to the given name if they are available.

<pre style="color:blue">
railtypetable {
RAIL,
ELRL,
"3RDR",
RT_SHINY_RAIL: [SHNY, RAIL]
}
</pre>

The label 3RDR is written as a string because an identifier can't start with a numeric value. To reference it later you can write <code style="color:darkgreen">railtype("3RDR")</code>. If another grf defines a railtype with label SHNY then RT_SHINY_RAIL will refer to that track type. If the railtype SHNY is not available then trains using RT_SHINY_RAIL as track type will fallback to RAIL.

The default railtype labels are "RAIL", "ELRL", "MONO", "MGLV". See the [[RailtypeLabels|List of railtype labels]] in the NewGRF Specs for currently defined custom labels.
Similarly, the default roadtype labels are "ROAD" and "ELRD", and the default tramtype labels are "RAIL" and "ELRL"

Note that labels are not shared between features, so the same label can be used for multiple items. For example, the label "RAIL" can be used for a railtype, roadtype, tramtype, and cargotype simultaneously without conflict.

Action4

2019-12-28T12:37:20Z

Andrew350: /* Feature */ added roadtypes / tramtypes

==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
|-
|12||Roadtypes
|-
|13||Tramtypes
|-
|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]].

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

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

Set bit7 (add 0x80 to the languageID as in the table below) in order to use 16 bit string IDs.

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 [[Action0/Global Settings]] property 15.

{{:language_IDs}}

When translating for a new language, please simply edit the [[language_IDs|language list]] 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 [[Action0/Houses#Building name ID (12)|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 several callbacks. Some callbacks support IDs up to D3FF.
|-
|D4xx||'''Never use in Action4''', only for displaying textids in range D000-D3FF (grf specific), see [[TextIDs]]
|-
|D8xx
|{{ottd|1.7|rev=r27769}} Useable like DCxx in Action 0 and for inclusion via string codes 0x80 and 0x81.
{{ttdp|}}'''Never use in Action4''', only usable in Action0 features, see [[TextIDs]]
|-
|DCxx||Set miscellaneous persistent GRF texts. Useable in Action 0 and for inclusion via string codes 0x80 and 0x81.
{{ttdp|}} Unlike the D0xx GRF texts, these IDs can be used to set properties. The text ID must be set before any [[Action0/Houses|action 0]] references it.
|}

{{ttdp|}} 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 colour codes are available for use:

{| |-
!'''Code'''!!'''Colour'''!!'''Pallete Colour'''
|-
|88||Blue|| <div style="background:#3890E8;width:2em;"> </div>
|-
|89||Silver|| <div style="background:#C8C8C8;width:2em;"> </div>
|-
|8A||Golden|| <div style="background:#FCC000;width:2em;"> </div>
|-
|8B||Red|| <div style="background:#FC0000;width:2em;"> </div>
|-
|8C||Purple|| <div style="background:#A888E0;width:2em;"> </div>
|-
|8D||Light Brown|| <div style="background:#B0B084;width:2em;"> </div>
|-
|8E||Orange|| <div style="background:#FCB030;width:2em;"> </div>
|-
|8F||Green|| <div style="background:#90E05C;width:2em;"> </div>
|-
|90||Yellow|| <div style="background:#FCF880;width:2em;"> </div>
|-
|91||Dark Green|| <div style="background:#B4CC7C;width:2em;"> </div>
|-
|92||Cream|| <div style="background:#D49480;width:2em;"> </div>
|-
|93||Brown|| <div style="background:#A46040;width:2em;"> </div>
|-
|94||White|| <div style="background:#FCFCFC;width:2em;"> </div>
|-
|95||Light Blue|| <div style="background:#80C4FC;width:2em;"> </div>
|-
|96||Grey|| <div style="background:#626562;width:2em;"> </div>
|-
|97||Dark Blue|| <div style="background:#8484A4;width:2em;"> </div>
|-
|98||Black|| <div style="background:#101010;width:2em;"> </div>
|}

==Example==

Action1

2019-12-28T12:33:27Z

Andrew350: /* Feature */ added roadtypes / tramtypes

==Introduction==
Defining a set of real sprites.
Action 01 is used to define sets of real sprites (as opposed to pseudo-sprites). It can be put anywhere in the .nfo file after [[Action8|Action 8]].

== Syntax ==

=== Basic format ===
{{ottdp|0.6|2.0}}
<sprite-number> * <length> '''01''' <feature> <num-sets> <num-ent>

{| |-
!Element!![[GRFActionsDetailed|Size]]!!Description
|-
|<sprite-number>||dec||A sequential sprite number
|-
|<length>||dec||The total number of bytes used in this action
|-
|01||B||Defines action 01
|-
|<feature>||B||The feature that following sprites should be used for (s.b.)
|-
|<num-sets>||B||The number of sprite sets you have (one sprite set is one vehicle/station/ship etc). Setting this to 00 makes it an extended format (see below).
|-
|<num-ent>||B*||The number of views the sprite has
|}

The block of data that always follows after action 01 should consist of num-sets * num-ent RealSprites or RecolorSprites.

=== Extended format ===
{{ottdp|1.2.2|no|ottdrev=r24361}}
<sprite-number> * <length> '''01''' <feature> '''00''' <first-set> <num-sets> <num-ent>

{| |-
!Element!![[GRFActionsDetailed|Size]]!!Description
|-
|<sprite-number>||dec||A sequential sprite number
|-
|<length>||dec||The total number of bytes used in this action
|-
|01||B||Defines action 01
|-
|<feature>||B||The feature that following sprites should be used for (s.b.)
|-
|00||B||Identfies the extended format.
|-
|<first-set>||B*||The ID of the first spriteset to define
|-
|<num-sets>||B*||The number of sprite sets you have (one sprite set is one vehicle/station/ship etc)
|-
|<num-ent>||B*||The number of views the sprite has
|}

The block of data that always follows after action 01 should consist of num-sets * num-ent RealSprites or RecolorSprites.

== Description ==

=== sprite-number ===

This is just the number you are at.

=== length ===

Count the number of bytes in this action.

===Feature===

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

{|- |
!Value!![[Features|Feature]]
|-
|00||Trains
|-
|01||Road Vehicles
|-
|02||Ships
|-
|03||Aircraft
|-
|04||Stations
|-
|05||Canals/Rivers
|-
|07||Houses
|-
|09||Industry Tiles
|-
|0A||Industries
|-
|0B||Cargos
|-
|0D||Airports
|-
|0F||Objects
|-
|10||Railtypes
|-
|11||Airport Tiles
|-
|12||Roadtypes
|-
|13||Tramtypes
|}

=== first-set ===
This specifies the first set ID to define.

{{ottdp|1.2|no|ottdrev=r22925}} Since OpenTTD r22925 spritesets stay valid across multiple Action1. That is, if one Action1 defines spritesets 0 to 4, and later a second Action1 redefines spriteset 0, spritesets 1 to 4 still refer to the first Action1. Spritesets are feature-specific, each feature maintains its own mapping of ids to Action1 spritesets. (Prior to OpenTTD r22925 and in TTDPatch only spritesets from a single Action1 are referencible from an Action2 at a time. Referencing an Action1 with a different feature than the Action2 is an error.)

This behaviour of Action1 applies to both the basic as well as the extended format.

{{ottdp|1.2|no|ottdrev=r22926}} In addition the extended format allows to specify an ID for the first spriteset to define. That way individual spritesets and be redefined individually.

There are no restriction on the order the spritesets are defined. If you define spritesets 23..25 in one Action 1, define spritesets 0..5 in another Action 1, then an Action 2 can access sets 0..5 and 23..25. Later another Action 1 can redefine spritesets 2..3, and following Action 2 could access spritesets 0..1, 2..3, 4, 23..25 from various Action 1.

Note that all spriteset defined in a single Action1 have the same amount of sprites per spriteset. Using multiple Action1 you can define spriteset with different amounts of sprites per set. Action2 will individually use the size of each referenced spriteset. There is no requirement for consistent numbers of sprites in Action2 or spritelayouts.

=== num-sets ===
The amount of stations, vehicles, ships, etc that the following sprites represent (be warned, one spriteset can be used for more as one vehicle, or truck; you will see this when you reach [[Action2|Action 2]] and [[Action3|Action 3]])

=== num-ent ===

This sets how many different views each entry has.

For vehicles, this corresponds to the different directions it can be in. If your vehicle is symmetrical you need 4 views, and if it isn't symmetrical then use 8 views.

A station should normally be 12 (hex) because a station is made out of 18 (decimal) sprites, although if you use a different sprite layout for your station this number may vary.
For canals, it depends on the canal feature, see [[Action3|Action 3]].

For houses and industry tiles, this should be between 1 and 4 and specifies the number of different construction stages. Sprites after the first four are always ignored. See also action 2 and 3.

For cargos, this should always be 1. The following sprites should be no larger than 10x10 pixels or they won't fit into the station window correctly.

{{ottdp|0.6|2.5|ttdprev=2.0.1 alpha 49}} Since TTDPatch 2.0.1 alpha 49, this value is a so-called "extended byte" (see [[GRFActionsDetailed]]).

{{ottdp|0.6|2.5|ttdprev=2.0.1 alpha 63}} Since TTDPatch 2.0.1 alpha 63, it is possible to have <num-ent>=0. This is useful for defining an action 1/2 combination that only serves as invalid callback result. If the .grf file defines no graphics otherwise, this way callbacks can return an explicit failure code without needing any actual sprites to be allocated. This is also needed if the feature has [[Action2/Only_Callback_Failure | no graphics at all]].

== Example ==

Below is an example of what a real Action 1 pseudo-sprite could look like with the sprite entries under it.

2 * 4 01 00 01 08
3 C:\TTD\SPRITES\mytrain.pcx 66 8 01 18 8 -3 -10
4 C:\TTD\SPRITES\mytrain.pcx 82 8 09 15 20 -14 -6
5 C:\TTD\SPRITES\mytrain.pcx 114 8 01 12 28 -14 -6
6 C:\TTD\SPRITES\mytrain.pcx 162 8 09 16 20 -4 -8
7 C:\TTD\SPRITES\mytrain.pcx 194 8 01 18 8 -3 -10
8 C:\TTD\SPRITES\mytrain.pcx 210 8 09 16 20 -14 -7
9 C:\TTD\SPRITES\mytrain.pcx 242 8 01 12 28 -14 -6
10 C:\TTD\SPRITES\mytrain.pcx 290 8 09 15 20 -4 -7

{| |-
!'''Byte'''!!'''Meaning'''
|-
|2||<sprite-number>
|-
|4||<length> of the action in bytes; start counting at 01 (<action>)
|-
|01||<action>: sets this pseudo-sprite to function as action 1
|-
|00||<feature>: In this case Train
|-
|01||<num-sets>: 1 Set of views
|-
|08||<num-ent>: 8 views of this train

Action2/Single Set

2019-12-28T12:31:51Z

Andrew350: /* Introduction */ added roadtypes and tramtypes

== Introduction ==
{| |-
!Feature !! Version !! Associated graphics
|-
|Canals || {{ottdp|0.6|2.5}} || Depends on [[Action3#ids | Action3 ID]]; see [[Action0/Canals | Action0]]
|-
|Cargos || {{ottdp|0.6|2.5}} || Single icon sprite
|-
|Airports || {{ottdp|1.1|no}} || Single preview image
|-
|Railtypes || {{ottdp|1.0|no|ottdrev=r19056}} || Depends on [[Action3/Railtypes#cargo-type| Action3 'cargo' type]]
|-
|Roadtypes || {{ottdp|1.10}} || Depends on [[Action3/Roadtypes#cargo-type| Action3 'cargo' type]]
|-
|Tramtypes || {{ottdp|1.10}} || Depends on [[Action3/Tramtypes#cargo-type| Action3 'cargo' type]]
|}

The Action2 for these features defines only a single spriteset, therefore the action2 you need isn't too complicated.

The only graphics associated to cargoes is their icon that is shown in the station window.

The graphics associated with railtypes, roadtypes, and tramtypes are somewhat more complicated, but all their logic is in variational action2s and the action3; the standard action2 is again not complicated.

The only graphics associated with airports is their preview sprite. The default size for the preview sprite is 230x140. The airport build GUI will automatically scale if you have a smaller or larger image, but it will probably look best if you make sure it is no larger than the default size.

Do not skip an Action2 using [[Action9]] (unless it skips the whole file). Action2 must not be skipped by Action9 or TTDPatch will most likely crash. Skip or modify [[Action3]] instead. Skipping an Action2 with an [[Action7]] has no effect.

== Syntax ==

<Sprite-number> * <Length> 02 <feature> <set-id> 01 00 <set>

{|
!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 action2
|-
|<feature>||B||[[Features | Feature]] being defined
|-
|<set-id>||B||What set-ID this action2 defines
|-
|01||B||A literal 01 byte
|-
|00||B||A literal 00 byte
|-
|<set>||W||Number of set to use from the last action 1
|}

You may note that this is the same as the action2 entry for vehicles, but with num_loadtypes=1 and num_loadingtypes=0, and only one set number.

== Description ==

=== Sprite-number ===

This is just the number you are at.

=== Length ===

Count the number of bytes in this action.

=== set-id ===

This defines the ID of the current action 2. This ID will later be referred to by [[Action3|action 3]], or a variational/random action 2.

You can reuse action 2 IDs, and there's no restriction on the order in which they are defined.

=== set ===

The sprite set to use for displaying. Entry is a WORD value in little endian format, and refers to the most recent action1 set. For example, action1 set 3 would be encoded as 03 00. Note the additional 00 which is needed because it must be a word value here.
(Don't forget that sprite set numbering starts from zero)

Action2

2019-12-28T12:27:43Z

Andrew350: /* Feature */ added roadtypes / tramtypes

== Introduction ==

Defining graphics set IDs.

Action2 is used to group sets of sprites from the previous [[Action1]] together, and make them accessible by a [[VariationalAction2|variational]] or [[RandomAction2|random action 2]] (chain) or an [[Action3]].

Do not skip an Action2 using [[Action9]] (unless it skips the whole file). Action2 must not be skipped by Action9 or TTDPatch will most likely crash. Skip or modify [[Action3]] instead. Skipping an Action2 with an [[Action7]] has no effect.

== Syntax ==

In general, the data looks as follows. Some features use a different syntax though (see table below).

<Sprite-number> * <Length> 02 <feature> <set-id> <num-ent1> <num-ent2> <entries...>

{|
!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 feature should the following sprites be used?
|-
|<set-id>||B||What set-ID this action 2 defines
|-
|<num-ent1>||B||First number of entries, depends on feature
|-
|<num-ent2>||B||Second number of entries, depends on feature
|-
|<entries...>||W||Entry numbers, depends on the feature
|}

== 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||[[Action2/Vehicles | Trains]]
|-
|01||[[Action2/Vehicles | Road Vehicles]]
|-
|02||[[Action2/Vehicles | Ships]]
|-
|03||[[Action2/Vehicles | Aircraft]]
|-
|04||[[Action2/Stations | Stations]]
|-
|05||[[Action2/Single_Set | Canals/Rivers]]
|-
|07||[[Action2/Sprite_Layout | Houses]] (special Sprite Layout format)
|-
|09||[[Action2/Sprite_Layout | Industry Tiles]] (special Sprite Layout format)
|-
|0A||[[Action2/Industries | Industries]] (special Production Callback format)
|-
|0B||[[Action2/Single_Set | Cargos]]
|-
|0C||[[Action2/Only_Callback_Failure | Sound Effects]] (callback failure only)
|-
|0D||[[Action2/Single_Set | Airports]]
|-
|0E||[[Action2/Only_Callback_Failure | Signals]] (callback failure only)
|-
|0F||[[Action2/Sprite_Layout | Objects]] (special Sprite Layout format)
|-
|10||[[Action2/Single_Set | Railtypes]]
|-
|11||[[Action2/Sprite_Layout | Airport Tiles]] (special Sprite Layout format)
|-
|12||[[Action2/Single_Set | Roadtypes]]
|-
|13||[[Action2/Single_Set | Tramtypes]]
|}

=== set-id ===

This defines the ID of the current action 2. This ID will later be referred to by [[Action3|action 3]], or a variational/random action 2.

You can reuse action 2 IDs, and there's no restriction on the order in which they are defined.

=== num-ent1, num-ent2 ===

Each feature has two different graphics ranges, but their exact meaning differs from feature to feature. For example, for vehicles, the first set is used while moving, and the second while loading/unloading in a station.

=== entries ===

This is the list of action 1 sets to use, first num-ent1 for the first range, then num-ent2 entries for the second range.

==Example==

VariationalAction2

2019-12-28T12:25:50Z

Andrew350: added roadtypes / tramtypes

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

The size of <varadjust> depends on <type> as well as the adjustments to be performed and must always provide an AND mask. For <type> 81, a "do nothing" <varadjust> would be 00 FF.

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/Roadtypes | Roadtypes]]
|-
|13||[[VariationalAction2/Tramtypes | Tramtypes]]
|}

=== 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<br/>Access lowest byte !! {{ottdp|0.6|2.5}} W<br/>Access lowest word !! {{ottdp|0.6|2.5}} D<br/>Access lowest doubleword
|-
!align="left"| Access general variable or<br/>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/Roadtypes | Roadtypes]]||N/A
|-
|13||[[VariationalAction2/Tramtypes | Tramtypes]]||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>

Action3

2019-12-28T12:21:51Z

Andrew350: /* cargo-type */ added note about road/tramtypes

== Introduction ==

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

== Format ==

The format of the data is feature-dependent.

The data is:

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

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

== Description ==

=== Sprite-number ===

This is just the number you are at.

=== Length ===

Count the number of bytes in this action.

=== Feature ===

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

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

=== n-id ===

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

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

=== ids ===

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

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

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

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

=== num-cid ===

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

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

=== cargo-type ===

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

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

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

If defined, cargo-type FF is used for graphics shown in the purchase or construction window.
: Note that for dual-headed trains (prop 13) special rules for the purchase menu sprite apply: two sprites are drawn (for front and back) as if the vehicle is normally constructed. If you supply one purchase menu sprite, it will be used for both vehicle parts in the purchase menu. Provide a set of 8 sprites, and the 7th resp. 3rd sprite will be drawn; provide a set of 8 blank sprites except the 7th if you want to fully control a single purchase menu sprite for a dual-headed engine.

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

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

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

Since OpenTTD 1.10 this is also the case for [[Action3/Roadtypes|Roadtypes]] and [[Action3/Tramtypes|Tramtypes]]

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

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

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

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

=== default set-ID ===

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

== Example ==

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

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

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

Action3

2019-12-28T12:17:57Z

Andrew350: /* Feature */ added roadtypes / tramtypes

== Introduction ==

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

== Format ==

The format of the data is feature-dependent.

The data is:

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

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

== Description ==

=== Sprite-number ===

This is just the number you are at.

=== Length ===

Count the number of bytes in this action.

=== Feature ===

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

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

=== n-id ===

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

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

=== ids ===

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

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

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

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

=== num-cid ===

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

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

=== cargo-type ===

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

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

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

If defined, cargo-type FF is used for graphics shown in the purchase or construction window.
: Note that for dual-headed trains (prop 13) special rules for the purchase menu sprite apply: two sprites are drawn (for front and back) as if the vehicle is normally constructed. If you supply one purchase menu sprite, it will be used for both vehicle parts in the purchase menu. Provide a set of 8 sprites, and the 7th resp. 3rd sprite will be drawn; provide a set of 8 blank sprites except the 7th if you want to fully control a single purchase menu sprite for a dual-headed engine.

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

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

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

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

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

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

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

=== default set-ID ===

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

== Example ==

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

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

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

Action3/Tramtypes

2019-12-28T12:15:45Z

Andrew350: initial creation

== Introduction ==

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

{{ottdp|1.10}} Tramtypes are available only in OpenTTD > 1.10

== Format ==

The format of the data is feature-dependent. For tramtypes it looks like

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

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

== Description ==

=== Sprite-number ===

This is just the number you are at.

=== Length ===

Count the number of bytes in this action.

=== n-id ===

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

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

=== ids ===

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

=== num-cid ===

Number of "cargo" type definitions that follow.

=== cargo-type ===

Tramtypes re-uses in its Action3 the 'cargo'-type definition in order to assign the type of graphics defined by the associated set-ID:

{| class="wikitable"
|-
!'Cargo' Type
!Sprite Type
!#Sprites
!Useage
|-
|00
|Icons and cursors
|12
|4 rail directions, autorail, depot, tunnel and convert rail. First all icons, then all cursors.
|-
|01
|Track overlays<ref name=leftout>Either all or none of these sprites should be provided.</ref>
|19
|11 trackbit combinations, 4 slopes, and 4 dead ends. These sprites are '''required''' for tramtypes.
|-
|02
|Underlay<ref name=leftout />
|19
|11 trackbit combinations, 4 slopes, and 4 dead ends. These sprites are required.

|-
|04
|Catenary front
|29
|11 trackbit combinations, 4 slopes, 4 dead ends, 4 tunnels, 2 bridge middle, 4 bridge ramps
|-
|05
|Catenary back
|29
|11 trackbit combinations, 4 slopes, 4 dead ends, 4 tunnels (unused), 2 bridge middle, 4 bridge ramps
|-
|06
|Bridge surfaces<ref name=leftout />
|6
|2 bridge middle, 4 bridge ramps
|-
|08
|Depots
|6
|Follows the original layout for depot sprites. If not present, the default depot sprites (depending on catenary flag) plus track overlay are drawn. If present, the depot sprites are expected to include track overlay graphics.

|}

<references />

==== GUI sprites (00) ====

[[File:Nrt_gui.png]]

==== Track overlay (01) ====

[[File:Nrt_overlay.png]]

==== Track underlay (02) ====

[[File:Nrt_underlay.png]]

==== Catenary front (04)====

[[File:Nrt_catenary_front.png]]

==== Catenary back (05) ====

[[File:Nrt_catenary_back.png]]

==== Depot sprites (08) ====

[[File:Nrt_depot.png]]

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

==== Bridge surfaces (06) ====

[[File:Nrt_bridge.png]]


=== default set-ID ===

The default set-ID would be used for tramtype callbacks. However, since there are currently no callbacks for tramtypes it should always result in a [[Action2/Only_Callback_Failure|callback-failure]].

== Example ==

Action3/Roadtypes

2019-12-28T12:03:55Z

Andrew350: corrected the feature byte

== Introduction ==

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

{{ottdp|1.10}} Roadtypes are available only in OpenTTD > 1.10

== Format ==

The format of the data is feature-dependent. For roadtypes it looks like

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

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

== Description ==

=== Sprite-number ===

This is just the number you are at.

=== Length ===

Count the number of bytes in this action.

=== n-id ===

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

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

=== ids ===

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

=== num-cid ===

Number of "cargo" type definitions that follow.

=== cargo-type ===

Roadtypes re-uses in its Action3 the 'cargo'-type definition in order to assign the type of graphics defined by the associated set-ID:

{| class="wikitable"
|-
!'Cargo' Type
!Sprite Type
!#Sprites
!Useage
|-
|00
|Icons and cursors
|12
|4 road directions, autoroad, depot, tunnel and convert road. First all icons, then all cursors.
|-
|01
|Track overlays<ref name=leftout>Either all or none of these sprites should be provided.</ref>
|19
|11 roadbit combinations, 4 slopes, and 4 dead ends. These sprites are optional for roadtypes.
|-
|02
|Underlay<ref name=leftout />
|19
|11 roadbit combinations, 4 slopes, and 4 dead ends. These sprites are required.

|-
|04
|Catenary front
|29
|11 roadbit combinations, 4 slopes, 4 dead ends, 4 tunnels, 2 bridge middle, 4 bridge ramps
|-
|05
|Catenary back
|29
|11 roadbit combinations, 4 slopes, 4 dead ends, 4 tunnels (unused), 2 bridge middle, 4 bridge ramps
|-
|06
|Bridge surfaces<ref name=leftout />
|6
|2 bridge middle, 4 bridge ramps
|-
|08
|Depots
|6
|Follows the original layout for depot sprites. If not present, the default depot sprites (depending on catenary flag) plus track overlay are drawn. If present, the depot sprites are expected to include track overlay graphics.

|-
|0A?
|Road stops
|4
|Overlays for drive-in road stops
|}

<references />

==== GUI sprites (00) ====

[[File:Nrt_gui.png]]

==== Road underlay (02) ====

[[File:Nrt_underlay.png]]

==== Catenary front (04)====

[[File:Nrt_catenary_front.png]]

==== Catenary back (05) ====

[[File:Nrt_catenary_back.png]]

==== Depot sprites (08) ====

[[File:Nrt_depot.png]]

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

==== Bridge surfaces (06) ====

[[File:Nrt_bridge.png]]

==== Road stops (0A?)====

[[File:Nrt_drivein.png]]


=== default set-ID ===

The default set-ID would be used for roadtype callbacks. However, since there are currently no callbacks for roadtypes it should always result in a [[Action2/Only_Callback_Failure|callback-failure]].

== Example ==

Action3/Roadtypes

2019-12-28T12:03:00Z

Andrew350: initial creation

== Introduction ==

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

{{ottdp|1.10}} Roadtypes are available only in OpenTTD > 1.10

== Format ==

The format of the data is feature-dependent. For roadtypes it looks like

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

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

== Description ==

=== Sprite-number ===

This is just the number you are at.

=== Length ===

Count the number of bytes in this action.

=== n-id ===

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

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

=== ids ===

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

=== num-cid ===

Number of "cargo" type definitions that follow.

=== cargo-type ===

Roadtypes re-uses in its Action3 the 'cargo'-type definition in order to assign the type of graphics defined by the associated set-ID:

{| class="wikitable"
|-
!'Cargo' Type
!Sprite Type
!#Sprites
!Useage
|-
|00
|Icons and cursors
|12
|4 road directions, autoroad, depot, tunnel and convert road. First all icons, then all cursors.
|-
|01
|Track overlays<ref name=leftout>Either all or none of these sprites should be provided.</ref>
|19
|11 roadbit combinations, 4 slopes, and 4 dead ends. These sprites are optional for roadtypes.
|-
|02
|Underlay<ref name=leftout />
|19
|11 roadbit combinations, 4 slopes, and 4 dead ends. These sprites are required.

|-
|04
|Catenary front
|29
|11 roadbit combinations, 4 slopes, 4 dead ends, 4 tunnels, 2 bridge middle, 4 bridge ramps
|-
|05
|Catenary back
|29
|11 roadbit combinations, 4 slopes, 4 dead ends, 4 tunnels (unused), 2 bridge middle, 4 bridge ramps
|-
|06
|Bridge surfaces<ref name=leftout />
|6
|2 bridge middle, 4 bridge ramps
|-
|08
|Depots
|6
|Follows the original layout for depot sprites. If not present, the default depot sprites (depending on catenary flag) plus track overlay are drawn. If present, the depot sprites are expected to include track overlay graphics.

|-
|0A?
|Road stops
|4
|Overlays for drive-in road stops
|}

<references />

==== GUI sprites (00) ====

[[File:Nrt_gui.png]]

==== Road underlay (02) ====

[[File:Nrt_underlay.png]]

==== Catenary front (04)====

[[File:Nrt_catenary_front.png]]

==== Catenary back (05) ====

[[File:Nrt_catenary_back.png]]

==== Depot sprites (08) ====

[[File:Nrt_depot.png]]

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

==== Bridge surfaces (06) ====

[[File:Nrt_bridge.png]]

==== Road stops (0A?)====

[[File:Nrt_drivein.png]]


=== default set-ID ===

The default set-ID would be used for roadtype callbacks. However, since there are currently no callbacks for roadtypes it should always result in a [[Action2/Only_Callback_Failure|callback-failure]].

== Example ==

VariationalAction2/Tramtypes

2019-12-28T11:29:28Z

Andrew350: initial creation

==Introduction==

== Variables ==

{| |-
!Variable !![[GRFActionsDetailed|Size]]!!Version !! Description
|-
|40||B||{{ottdp|1.10}}||Terrain type: 0 normal, 1 desert, 2 rainforest, 4 on or above snowline.
|-
|41||B||{{ottdp|1.10}}||Enhanced tunnels; entrance has track above. Always 0 in OpenTTD.
|-
|42||B||{{ottdp|1.10}}||Level crossing status: 0 if open (or not a crossing), 1 if closed.
|-
|43||D||{{ottdp|1.10}}||Depot construction date (long format, 0 based); other: current date
|-
|44||B||{{ottdp|1.10}}||[[TownZones|Town zone]] of the tile.
|}

== Description ==
=== Terrain type (40) ===

'''Format:''' byte

{| |-
!value!!Meaning
|-
|0||normal tile
|-
|1||desert tile
|-
|2||rain forest tile
|-
|4||tile on or above snow line
|}

=== Enhanced tunnels (41) ===

'''Format:''' byte

This variable will always return 0 and is reserved for future use with enhanced tunnels.

=== Level crossing status (42) ===

'''Format:''' byte

This variable returns 1, if a crossing is closed. If the crossing is open or the tile is no level crossing, the return value is 0.

==Example==

VariationalAction2/Roadtypes

2019-12-28T11:27:59Z

Andrew350: initial creation

Action0

2019-12-28T11:16:16Z

Andrew350: /* Feature */ split tramtypes from roadtypes

==Introduction==

Action 0 allows to change the feature properties of 'features', i.e. vehicles, stations, bridges, houses and more.
Each feature has its own very specific properties. These are explained in detail in their separate pages.

You will also find the minimum version requirements for properites on the pages.
Note, that due to the nature of Action 0 unknown properties cannot be ignored. Only a whole Action 0 can be skipped.
OpenTTD and TTDPatch will disable GRFs once they encounter an unknown property. So, if you use some properties for optional features, which you want to disable for older versions of OpenTTD or TTDPatch, you have to skip the Action 0 using [[Action9|Action 9]].

== Syntax ==

The data for Action 0 looks as follows:

<Sprite-number> * <Length> 00 <Feature> <Num-props> <Num-info> <Id> (<Property <New-info>)...

Here is a short overview of what every term means:

{| |-
!Element!![[GRFActionsDetailed|Size]]!!Description
|-
|<Sprite-number> ||dec||A sequential sprite number
|-
|<Length> ||dec||The total number of bytes in the action
|-
|00 ||B||Action type. In this case, 00
|-
|<Feature> ||B||Which type of feature you would like to change
|-
|<Num-props> ||B||How many properties you would like to change per vehicle or station
|-
|<Num-info> ||B||How many vehicles/stations you would like to change
|-
|<Id> ||B*||The ID of the first vehicle/station to change
|-
|<Property> ||B||What property to change for each vehicle/station
|-
|<New-info> ||V||The new value of the property
|}
You can put an Action 0 anywhere after [[Action8|Action 8]] in the GRF file.

{{ottdp|0.6|2.5|ttdprev=2.0.1 alpha 61}} The <Id> is an extended byte since TTDPatch 2.0.1 alpha 61, to support the definition of >255 sound effects.

{{ottdp|0.7|ottdrev=r13482}} {{grf|7|<7}} In OpenTTD since r13482, extended IDs (up to 65535) can be used for vehicles as well. However there is currently a caveat that articulated parts must be below 128.
{{ottdp|1.2}} {{grf|8}} In OpenTTD 1.2, extended IDs (up to 65535) can be used for vehicles as well. The ID for articulated vehicles must be below 8192.

== Descriptions ==

=== Sprite-number ===

Action 0 can appear anywhere in the GRF file, so set it to the sprite number you are currently at.

=== Length ===

The total number of bytes in Action 0. Start counting from <Action>, the bit that sets the pseudo-sprite to act as the specified action.

=== Action ===

The type of action this pseudo-sprites defines. It should be 00 here because we want this pseudo-sprite to act as Action 0.

=== Feature ===

This sets the type of [[Features|feature]] that you wish to change. Set it to:
{|
!Value
!colspan="2"|[[Features|Feature]]
|-
|00 || [[Action0/Vehicles/Trains|Trains]]
|rowspan="4"|[[Action0/Vehicles|Common vehicle properties]]
|-
|01 || [[Action0/Vehicles/RoadVehicles|Road Vehicles]]
|-
|02 || [[Action0/Vehicles/Ships|Ships]]
|-
|03 || [[Action0/Vehicles/Planes|Aircraft]]
|-
|04
|colspan="2"| [[Action0/Stations|Stations]]
|-
|05
|colspan="2"| [[Action0/Canals|Canals]]
|-
|06
|colspan="2"| [[Action0/Bridges|Bridges]]
|-
|07
|colspan="2"| [[Action0/Houses|Houses]] (see [[DefaultHouseProps|defaults]])
|-
|08
|colspan="2"| [[Action0/Global Settings|Global Settings]]
|-
|09
|colspan="2"| [[Action0/Industry Tiles|Industry Tiles]] (see [[IndustryTileDefaultProps|defaults]])
|-
|0A
|colspan="2"| [[Action0/Industries|Industries]] (see [[IndustryDefaultProps|defaults]])
|-
|0B
|colspan="2"| [[Action0/Cargos|Cargos]] (see [[CargoDefaultProps|defaults]])
|-
|0C
|colspan="2"| [[Action0/Sound Effects|Sound Effects]]
|-
|0D
|colspan="2"| [[Action0/Airports|Airports]]
|-
|0F
|colspan="2"| [[Action0/Objects|Objects]]
|-
|10
|colspan="2"| {{ottdp|1.0|no|ottdrev=r18969}} [[Action0/Railtypes|Railtypes]]
|-
|11
|colspan="2"| {{ottdp|1.1|no|ottdrev=r19204}} [[Action0/Airport Tiles|Airport Tiles]]
|-
|12
|colspan="2"| {{ottdp|1.10|no|ottdrev=gc02ef3e456}} [[Action0/Roadtypes|Roadtypes]]
|-
|13
|colspan="2"| {{ottdp|1.10|no|ottdrev=gc02ef3e456}} [[Action0/Tramtypes|Tramtypes]]
|}

=== Num-props ===

This is the number of properties that you wish to change per vehicle or station. Note: even if you wish to set the same properties to the same value for different vehicles then you must still repeat the properties and their values for each vehicle.

=== Num-info ===

Simply the number of vehicles that you will change using this action 0.

=== Id ===
The [[VehicleIDs|Vehicle ID]] of the first vehicle or station to change. If num-info is greater than one, this vehicle/station and the following vehicles/stations will be changed.

=== Property ===

The number of the property that will be changed. This and the New-info section are repeated as many times as there are properties to set; in total, there are <
num-props> property bytes.

See relevant sub-section (links at the bottom) for more details.

=== New-info ===

The new information that will replace the previous information for the specified property. This is a variable size; dependent upon the property. Each property byte is followed by <num-info> new-info sections.
The appropriate \b, \w, and \d escape sequences can be quite useful for most <
new-info>s. See [[GRFActionsDetailed#Byte order|the discussion of escape sequences]] for further information.

==Example==

NML:Roadtypes

2019-12-28T11:10:19Z

Andrew350: /* Roadtype properties */ updated TOWN_BUILD

{{NMLNavPropVarCB}}

Roadtypes can only be defined in OpenTTD {{ottd|1.10}} and {{nml|0.5}} or later.

==Roadtype IDs==
Roadtypes and Tramtypes share a pool of 64 IDs. Either feature can use as many IDs as needed (i.e. it is not limited to 32 per type), but both features combined are limited to 64 in total. NewGRF-local IDs may freely be chosen, but must be in the 0..63 range. If other roadtype/tramtype GRFs are loaded, it may be that there are not enough 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 (roadtype_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 roadtypes.

== 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 property <code style="color:green">road_type</code>) is defined. Otherwise the vehicle is disabled.
* When a vehicle is introduced, it always introduces its roadtype (road vehicle property <code style="color:green">road_type</code>).
* A roadtype is introduced, if at least one of the following conditions is met:
** A vehicle is introduced, that references the roadtype (road vehicle property <code style="color:green">road_type</code>).
** Another roadtype is introduced, that references the roadtype via the introduced roadtype list (roadtype property <code style="color:green">introduces_roadtype_list</code>).
** The introduction date (roadtype property <code style="color:green">introduction_date</code>) is passed and all required roadtypes (roadtype property <code style="color:green">requires_roadtype_list </code>) are available.

Via roadtype property <code style="color:green">powered_roadtype_list</code> multiple roadtypes can be defined, which shall be considered equivalent to a roadtype.
This affects the interpretation of road vehicle property <code style="color:green">road_type</code>. If road vehicle property <code style="color:green">road_type</code> references an undefined roadtype, then
roadtype property <code style="color:green">powered_roadtype_list</code> is checked for all defined roadtypes, whether the vehicle can be reassigned to some other roadtype.
Otherwise the vehicle is disabled.

==Roadtype properties==

{| class="t"
! property
! value range
! comment
|-
| label
| 4-byte string
| names of default road types: "ROAD" and "ELRD". See the [[RoadtypeLabels|List of roadtype labels]] in the NewGRF Specs for currently defined custom labels.
|-
| introduction_date
| date(yyyy,mm,dd)
| Valid range for yyyy is 0 ... 5000000.
|-
| name
| string
| Name of this roadtype
|-
| toolbar_caption
| string
| Caption of the build road toolbar
|-
| menu_text
| string
| Shown in the dropdown menu for all roadtypes
|-
| 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 <road type> engine" news message
|-
| powered_roadtype_list
| list of roadtype labels
| Provide a list of road types that road vehicles of this type are powered on, e.g. ["ROAD", "ELRD"]. Note that there is no "compatible_roadtype_list" since there is no difference between "powered" and "compatible" for roadtypes
|-
| roadtype_flags
| bitmask(ROADTYPE_FLAG_XXX, ...)
|
;CATENARY
:Enable catenary
;NO_LEVEL_CROSSING
:Disable level crossings
;NO_HOUSES
:Disallows house construction
;HIDDEN
:Hides the roadtype from players, but remains available to towns
;TOWN_BUILD
:Enables the roadtype to be built by towns, picked by highest speed (defaults to ROAD if no speed limits?)
|-
| construction_cost
| 0 ... 65525
| Per piece of road as multiplier to PR_BUILD_ROAD base cost. Default cost factors are 8 and 16 for ROAD and ELRD, respectively.
|-
| speed_limit
| 0 ... 65525 km/h (speed units)
| A speed limit of 0 means unlimited speed
|-
| map_colour
| 0 ... 255
| Entry in the colour palette.
|-
| requires_roadtype_list
| list of roadtype labels
| List of road types 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.
|-
| introduces_roadtype_list
| list of roadtype labels
| 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.
|-
| sort_order
| 0 ... 255
| Number which defines the sort order among road types. If this entry is not defined, it gets assigned sort order n*10+7 for the n-th roadtype.
|-
| maintenance_cost
| 0 ... 255
| Maintenance cost factor for each piece of road of this roadtype. Default cost factors are 16 and 24 for ROAD and ELRD, respectively.
|-
| alternative_roadtype_list
| list of roadtype labels
| List of road types which this road type will act as fallback for, if the corresponding road type is not defined separately
|}

===Sort order===

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

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

==Roadtype variables==

{| class="t"
! name
! value range
! comment
|-
| terrain_type
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|
|-
| enhanced_tunnels
| 0
| Reserved for future use, always returns 0 in OpenTTD. Should custom tunnel entrances be implemented, 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
|-
| random_bits
|
| 2 pseudo random bits, based on tile location
|}

==Roadtype callbacks==

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

{| class="t"
! callbacks
! number of sprites
! meaning
|-
| gui
| 12
| 6 gui icons, 6 cursors
|-
| track_overlay<ref name=leftout>Either all or none of these sprites should be provided.</ref>
| 19
| 11 roadbit combinations, 4 slopes, and 4 dead ends. These sprites are optional for roadtypes.
|-
| underlay<ref name=leftout />
| 19
| 11 roadbit combinations, 4 slopes, and 4 dead ends. These sprites are required.

|-
| catenary_front
| 29
| 11 roadbit combinations, 4 slopes, 4 dead ends, 4 tunnels, 2 bridge middle, 4 bridge ramps
|-
| catenary_back
| 29
| 11 roadbit combinations, 4 slopes, 4 dead ends, 4 tunnels (unused), 2 bridge middle, 4 bridge ramps
|-
| bridge_surfaces<ref name=leftout />
| 6
| 2 bridge middle, 4 bridge ramps
|-
| depots
| 6
| If not present, the default depot sprites (depending on catenary flag) plus track overlay are drawn.
If present, the depot sprites are expected to include track overlay graphics.

|-
| roadstops
| 4
| Overlays for drive-in road stops
|}

<references />
Note that there is no "default" graphics callback.

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

[[File:Nrt_gui.png]]

==== underlay ====

[[File:Nrt_underlay.png]]

==== catenary_front ====

[[File:Nrt_catenary_front.png]]

==== catenary_back ====

[[File:Nrt_catenary_back.png]]

==== depots ====

[[File:Nrt_depot.png]]

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

==== bridge_surfaces ====

[[File:Nrt_bridge.png]]

==== roadstops ====

[[File:Nrt_drivein.png]]


===Example code===

A typical implementation for roadtypes can look like:

<pre style="color:blue">
item(FEAT_ROADTYPES, highway, 0x01) {
property {
label: "HWY_";
name: string(STR_HWY);
menu_text: string(STR_HWY);
build_window_caption: string(STR_BUILD_CAPTION);
autoreplace_text: string(STR_AUTOREPLACE);
new_engine_text: string(STR_NEW_ENGINE);
powered_roadtype_list: ["HWY_","ROAD"]; // Highways are compatible with other roads
roadtype_flags: bitmask(ROADTYPE_FLAG_NO_LEVEL_CROSSING, ROADTYPE_FLAG_NO_HOUSES); // Highways should not have level crossings or houses
construction_cost: 32; // Highways are expensive
speed_limit: 100 km/h;
}
graphics {
underlay: ground_switch_underlay; // defines the usual roads
tunnels: tunnel_switch; // defines the roads drawn on a tunnel tile
depots: depot_switch; // defines the depot sprites
bridge_surfaces: bridge_terrain_switch; // defines the overlay drawn over bridges depending on climate
roadstops: roadstops_switch; // defines the look of roadstop pavement
}
}
</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.

Action0/Tramtypes

2019-12-28T11:07:50Z

Andrew350: initial tramtype spec

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

= Action 0 - Properties for tram types =

Defining properties of tram types.

Up to 64 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 64 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*1.6 (approx. km/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

Main Page

2019-12-28T10:52:34Z

Andrew350: split tramtypes from roadtypes

== Sprite types ==
;[[Action0]] - Defines new properties for anything added or changed by the NewGRF
:{| |-
|rowspan="5" align="center" style="width:3em"|'''0'''
| [[Action0/Vehicles | Vehicles]]
| [[Action0/Vehicles/Trains | Trains]]
| [[Action0/Vehicles/RoadVehicles | RoadVehicles]]
| [[Action0/Vehicles/Ships | Ships]]
| [[Action0/Vehicles/Planes | Aircraft]]
|-
| [[Action0/Stations | Stations]]
| [[Action0/Canals | Canals & Rivers]]
| [[Action0/Bridges | Bridges]]
| [[Action0/Houses | Houses]]
| [[Action0/Global Settings | Global Settings]]
|-
| [[Action0/Industry Tiles | Industry Tiles]]
| [[Action0/Industries | Industries]]
| [[Action0/Cargos | Cargos]]
| [[Action0/Sound Effects | Sound Effects]]
| [[Action0/Airports | Airports]]
|-
| ''Signals''
| [[Action0/Objects | Objects]]
| [[Action0/Railtypes | Railtypes]]
| [[Action0/Airport Tiles | Airport Tiles]]
| [[Action0/Roadtypes | Roadtypes]]
|-
| [[Action0/Tramtypes | Tramtypes]]
| ''Towns''
|
|
|
|}
;[[Action1]] - Defines one or more graphics sets
;[[Action2]] - Defines graphics set IDs
* Basic Action2
:{| |-
|rowspan="5" align="center" style="width:3em"|'''2'''
|colspan=5| [[Action2/Vehicles | Vehicles]]
|-
| [[Action2/Stations | Stations]]
| [[Action2/Single Set | Canals & Rivers]]
| ''Bridges''
| [[Action2/Sprite Layout | Houses]]
| ''Global Settings''
|-
| [[Action2/Sprite Layout | Industry Tiles]]
| [[Action2/Industries | Industries]]
| [[Action2/Single Set | Cargos]]
| [[Action2/Only Callback Failure | Sound Effects]]
| [[Action2/Single Set | Airports]]
|-
| [[Action2/Only Callback Failure | Signals]]
| [[Action2/Sprite Layout | Objects]]
| [[Action2/Single Set | Railtypes]]
| [[Action2/Sprite Layout | Airport Tiles]]
| [[Action2/Single Set | Roadtypes]]
|-
| [[Action2/Single Set | Tramtypes]]
| ''Towns''
|
|
|
|}
* [[VariationalAction2]] - A conditional switch that determines a [[Callbacks|callback]] result or chains to another Action 2
: [[VarAction2Advanced]] - Advanced features of Variational Action 2
: [[GlobalVariables | Global Variables]]
:{| |-
|rowspan="5" align="center" style="width:3em"|'''VA2'''
|colspan=5| [[VariationalAction2/Vehicles | Vehicles]]
|-
| [[VariationalAction2/Stations | Stations]]
| [[VariationalAction2/Canals | Canals & Rivers]]
| [[VariationalAction2/Bridges | Bridges]]
| [[VariationalAction2/Houses | Houses]]
| ''Global Settings''
|-
| [[VariationalAction2/Industry Tiles | Industry Tiles]]
| [[VariationalAction2/Industries | Industries]]
| [[VariationalAction2/Cargos | Cargos]]
| ''Sound Effects''
| [[VariationalAction2/Airports | Airports]]
|-
| [[VariationalAction2/Signals | Signals]]
| [[VariationalAction2/Objects | Objects]]
| [[VariationalAction2/Railtypes | Railtypes]]
| [[VariationalAction2/Airport Tiles | Airport Tiles]]
| [[VariationalAction2/Roadtypes | Roadtypes]]
|-
| [[VariationalAction2/Tramtypes | Tramtypes]]
| [[VariationalAction2/Towns | Towns]]
|
|
|
|}
* [[RandomAction2]] - A randomized Variational Action 2
:{| |-
|rowspan="5" align="center" style="width:3em"|'''R'''
|colspan=5| [[RandomAction2#Vehicles | Vehicles]]
|-
| [[RandomAction2#Stations | Stations]]
| [[RandomAction2#Canals | Canals & Rivers]]
| ''Bridges''
| [[RandomAction2#Town_building_triggers | Houses]]
| ''Global Settings''
|-
| [[RandomAction2#Industry_tile_triggers | Industry Tiles]]
| [[RandomAction2#Industry_tile_triggers | Industries]]
| ''Cargos''
| ''Sound Effects''
| [[RandomAction2#Stations | Airports]]
|-
| ''Signals''
| [[RandomAction2#Objects | Objects]]
| [[RandomAction2#Rail_types | Railtypes]]
| [[RandomAction2#Stations | Airport Tiles]]
| [[RandomAction2#Road_types | Roadtypes]]
|-
| [[RandomAction2#Tram_types | Tramtypes]]
| ''Towns''
|
|
|
|}

* [[Callbacks]] - List of available callbacks

;[[Action3]] - Associates Action 2s with an Action 0
:{| |-
|rowspan="5" align="center" style="width:3em"|'''3'''
|colspan=5| [[Action3 | Vehicles]]
|-
| [[Action3 | Stations]]
| [[Action3/Canals | Canals & Rivers]]
| ''Bridges''
| [[Action3 | Houses]]
| ''Global Settings''
|-
| [[Action3 | Industry Tiles]]
| [[Action3 | Industries]]
| [[Action3 | Cargos]]
| [[Action3 | Sound Effects]]
| [[Action3 | Airports]]
|-
| [[Action3 | Signals]]
| [[Action3 | Objects]]
| [[Action3/Railtypes | Railtypes]]
| [[Action3 | Airport Tiles]]
| [[Action3/Roadtypes | Roadtypes]]
|-
| [[Action3/Tramtypes | Tramtypes]]
| ''Towns''
|
|
|
|}
: [[Action3LiveryOverride]] - Change wagon livery to match the engine
;[[Action4]] - Defines text strings
;[[Action5]] - Replaces base set sprites not present in the original TTD.
;[[Action6]] - Modifies the contents of the following sprite
;[[Action7]] - Conditionally skips sprites or jumps to a label
: [[TTDPatchFlags| GameConfigFlags]] - Configuration flags for Action 7/9 Variable 85
;[[Action8]] - Defines GRFID, Name and Description
;[[Action9]] - (see action 7 above)
;[[ActionA]] - Replaces TTD base set sprites
;[[ActionB]] - Generates an error message
;[[ActionC]] - Does nothing (can be used to embed comments)
;[[ActionD]] - Assigns parameters and calculates results
* [[ReadingOtherGRFParameters]] - Reading another GRF file's parameters
* [[ReadingPatchVariables| ReadingGameSettings]] - Reading game configuration settings
* [[GRFResourceManagement]] - Preventing conflicts with limited resources
;[[ActionE]] - Deactivates a NewGRF file
;[[ActionF]] - Defines new town name styles
;[[Action10]] - Defines a label for action 7/9
;[[Action11]] - Defines new sounds
;[[Action12]] - Adds Unicode font glyphs
;[[Action13]] - Translates GRF-specific strings
;[[Action14]] - Static NewGRF information (OpenTTD only)
;[[RealSprites]] - Sprites that actually are drawn on the screen
;[[RecolorSprites]] - Changing other sprites' colors

== Graphics properties ==
* [[PalettesAndCoordinates#Palettes | Palettes]] - Palettes used by the game
* [[PalettesAndCoordinates#Coordinates | Coordinates]] - Coordinates used for sprite alignement

== TTD defaults ==
* [[DefaultHouseProps]] - Default property values for TTD's houses
* [[IndustryTileDefaultProps]] - Default property values for TTD's industry tiles
* [[IndustryDefaultProps]] - Default properties values for TTD's industries
* [[CargoDefaultProps]] - Default property values for TTD's cargo types
* [[VehicleIDs]] - Default vehicle IDs
* [[NML:Default_Vehicle_Properties]] - Default Vehicle Properties (NML)
* [[AirportTypes]] - Default Airport IDs
* [[AirportTileDefaultProps]] - Default airport tile properties

== NewGRF commons ==
* [[Action0Cargos#CargoClasses_.2816.29 | Cargo classes]] - Commonly used cargo classes
* [[CargoTypes | Cargo labels]] - Commonly used cargo labels
* [[ObjectLabels | Object classes]] - Commonly used object clases
* [[RailtypeLabels | Railtype labels]] - Commonly used railtype labels

== Misc ==
* [[Features]] - List of all features and feature-specific actions.
* [[BaseCosts | Base Costs]]
* [[VehicleRefitting | Vehicle Refitting]]
* [[GrfLoadingStages | GRF loading stages]]
* [[GlobalVariables | Global variables]]
* [[Storages | Storages]]
* [[StringCodes | String control codes]]
* [[TextIDs | Text IDs (TTD + TTDPatch + NewGRF defined)]]
* [[GRFActionsDetailed | Syntax details]]
* [[Version numbers | Types of version numbers used throughout the specs]]
* [[DebuggingGRFCode | Debugging NewGRFs]]
* [[SpriteErrors | TTDPatch error codes on loading NewGRFs]]

== Game mechanics ==
* [[TownZones | Town zones]]
* [[NMLMain | NML]]

Features

2019-12-28T10:48:02Z

Andrew350: /* List of features and feature-specific Actions */ split tram types from road types

==List of features and feature-specific Actions==

{| |-
!colspan="2"|Feature || [[Action0]] || [[Action1]] || [[Action2]] || [[VariationalAction2 | VarAction2]] || [[RandomAction2]] || [[Callbacks]] || [[Action3]] || [[Action4]]
|-
|00 || Trains || [[Action0/Vehicles/Trains | yes]] || [[Action1 | yes]] || [[Action2/Vehicles | yes]] || [[VariationalAction2/Vehicles | yes]] || [[RandomAction2#Vehicles | yes]] || [[Callbacks | yes]] || [[Action3 | yes]] || [[Action4 | yes]]
|-
|01 || Road Vehicles || [[Action0/Vehicles/RoadVehicles | yes]] || [[Action1 | yes]] || [[Action2/Vehicles | yes]] || [[VariationalAction2/Vehicles | yes]] || [[RandomAction2#Vehicles | yes]] || [[Callbacks | yes]] || [[Action3 | yes]] || [[Action4 | yes]]
|-
|02 || Ships || [[Action0/Vehicles/Ships | yes]] || [[Action1 | yes]] || [[Action2/Vehicles | yes]] || [[VariationalAction2/Vehicles | yes]] || [[RandomAction2#Vehicles | yes]] || [[Callbacks | yes]] || [[Action3 | yes]] || [[Action4 | yes]]
|-
|03 || Aircraft || [[Action0/Vehicles/Planes | yes]] || [[Action1 | yes]] || [[Action2/Vehicles | yes]] || [[VariationalAction2/Vehicles | yes]] || [[RandomAction2#Vehicles | yes]] || [[Callbacks | yes]] || [[Action3 | yes]] || [[Action4 | yes]]
|-
|04 || Stations || [[Action0/Stations | yes]] || [[Action1 | yes]] || [[Action2/Stations | yes]] || [[VariationalAction2/Stations | yes]] || [[RandomAction2#Stations | yes]] || [[Callbacks | yes]] || [[Action3 | yes]] || [[Action4 | yes]]
|-
|05 || Canals || [[Action0/Canals | yes]] || [[Action1 | yes]] || [[Action2/Single Set | yes]] || [[VariationalAction2/Canals | yes]] || [[RandomAction2#Canals | yes]] || [[Callbacks | yes]] || [[Action3 | yes]] || ''no''
|-
|06 || Bridges || [[Action0/Bridges | yes]] || ''no'' || ''no'' || [[VariationalAction2/Bridges | no-ish]] || ''no'' || ''no'' || ''no'' || [[Action0/Bridges#Purchase_text_.2810.29 | yes-ish]]
|-
|07 || Houses || [[Action0/Houses | yes]] || [[Action1 | yes]] || [[Action2/Sprite Layout | yes]] || [[VariationalAction2/Houses | yes]] || [[RandomAction2#Town_building_triggers | yes]] || [[Callbacks | yes]] || [[Action3 | yes]] || [[Action4 | yes]]
|-
|08 || Global Settings || [[Action0/Global Settings | yes]] || ''no'' || ''no'' || ''no'' || ''no'' || ''no'' || ''no'' || ''no''
|-
|09 || Industry Tiles || [[Action0/Industry Tiles | yes]] || [[Action1 | yes]] || [[Action2/Sprite Layout | yes]] || [[VariationalAction2/Industry Tiles | yes]] || [[RandomAction2#Industry_tile_triggers | yes]] || [[Callbacks | yes]] || [[Action3 | yes]] || ''no''
|-
|0A || Industries || [[Action0/Industries | yes]] || [[Action1 | yes]] || [[Action2/Industries | yes]] || [[VariationalAction2/Industries | yes]] || [[RandomAction2#Industry_tile_triggers | yes]] || [[Callbacks | yes]] || [[Action3 | yes]] || [[Action4 | yes]]
|-
|0B || Cargos || [[Action0/Cargos | yes]] || [[Action1 | yes]] || [[Action2/Single Set | yes]] || [[VariationalAction2 | yes-ish]] <ref name="novars">No feature specific variables though</ref> || ''no'' || [[Callbacks | yes]] || [[Action3 | yes]] || [[Action4 | yes]]
|-
|0C || Sound Effects || [[Action0/Sound Effects | yes]] || ''no'' || [[Action2/Only Callback Failure | yes-ish]] <ref name="failonly">Callback failure only</ref> || [[VariationalAction2 | yes-ish]] <ref name="novars"/> || ''no'' || [[Callbacks | yes]] || [[Action3 | yes]] || ''no''
|-
|0D || Airports || [[Action0/Airports | yes]] || [[Action1 | yes]] || [[Action2/Single Set | yes]] || [[VariationalAction2/Airports | yes]] || [[RandomAction2#Stations | yes]] || [[Callbacks | yes]] || [[Action3 | yes]] || [[Action4 | yes]]
|-
|0E || Signals || ''no'' || [[Action5#0E_New_Signals | Action5]] || [[Action2/Only Callback Failure | yes-ish]] <ref name="failonly"/> || [[VariationalAction2/Signals | yes]] || ''no'' || [[Callbacks | yes]] || [[Action3 | yes]] || ''no''
|-
|0F || Objects || [[Action0/Objects | yes]] || [[Action1 | yes]] || [[Action2/Sprite Layout | yes]] || [[VariationalAction2/Objects | yes]] || [[RandomAction2#Objects | yes]] || [[Callbacks | yes]] || [[Action3 | yes]] || [[Action4 | yes]]
|-
|10 || Railtypes || [[Action0/Railtypes | yes]] || [[Action1 | yes]] || [[Action2/Single Set | yes]] || [[VariationalAction2/Railtypes | yes]] || [[RandomAction2#Rail_types | yes]] || ''no'' || [[Action3 | yes]] || [[Action4 | yes]]
|-
|11 || Airport Tiles || [[Action0/Airport Tiles | yes]] || [[Action1 | yes]] || [[Action2/Sprite Layout | yes]] || [[VariationalAction2/Airport Tiles | yes]] || [[RandomAction2#Stations | yes]] || [[Callbacks | yes]] || [[Action3 | yes]] || ''no''
|-
|12 || Roadtypes || [[Action0/Roadtypes | yes]] || [[Action1 | yes]] || [[Action2/Single Set | yes]] || [[VariationalAction2/Roadtypes | yes]] || [[RandomAction2#Road_types | yes]] || ''no'' || [[Action3 | yes]] || [[Action4 | yes]]
|-
|13 || Tramtypes || [[Action0/Tramtypes | yes]] || [[Action1 | yes]] || [[Action2/Single Set | yes]] || [[VariationalAction2/Tramtypes | yes]] || [[RandomAction2#Tram_types | yes]] || ''no'' || [[Action3 | yes]] || [[Action4 | yes]]
|-
|N/A 
| Towns || ''no'' || ''no'' || ''no'' || [[VariationalAction2/Towns | yes]] || ''no'' || ''no'' || ''no'' || [[ActionF]]
|-
|48 || Original Strings <ref>This is a pseudo-feature only used in Action4 to assign original strings. The value 0x48 originates from the way old TTDPatch versions checked for switches enabling/disabling features. NewTrains (feature 0x00) are activated by [[TTDPatchFlags | switch 0x37]]. Adding 0x48 to that results in 0x7F - a switch which is always set when TTDPatch is active. Thus feature 0x48 was not disabled by any switch. (today TTDPatch does not depend on the switches being in order of the features)</ref> || ''no'' || ''no'' || ''no'' || ''no'' || ''no'' || ''no'' || ''no'' || [[Action4 | yes]]
|}
<references/>

Action0/Roadtypes

2019-12-28T10:34:39Z

Andrew350: initial roadtype spec

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

= Action 0 - Properties for road types =

Defining properties of road types.

Up to 64 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 64 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*1.6 (approx. km/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

NML:Tramtypes

2019-12-28T08:39:25Z

Andrew350: /* Tramtype IDs */ typo

{{NMLNavPropVarCB}}

Tramtypes can only be defined in OpenTTD {{ottd|1.10}} and {{nml|0.5}} or later.

==Tramtype IDs==
Tramtypes and Roadtypes share a pool of 64 IDs. Either feature can use as many IDs as needed (i.e. it is not limited to 32 per type), but both features combined are limited to 64 in total. NewGRF-local IDs may freely be chosen, but must be in the 0..63 range. If other tramtype/roadtype GRFs are loaded, it may be that there are not enough 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 (tramtype_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 tramtypes.

== 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.
* Remember that the road vehicle flag 'ROADVEH_FLAG_TRAM' must be set in order for a road vehicle to be considered a tram.
* A vehicle exists, if its tramtype (road vehicle property <code style="color:green">tram_type</code>) is defined. Otherwise the vehicle is disabled.
* When a vehicle is introduced, it always introduces its tramtype (road vehicle property <code style="color:green">tram_type</code>).
* A tramtype is introduced, if at least one of the following conditions is met:
** A vehicle is introduced, that references the tramtype (road vehicle property <code style="color:green">tram_type</code>).
** Another tramtype is introduced, that references the tramtype via the introduced tramtype list (tramtype property <code style="color:green">introduces_tramtype_list</code>).
** The introduction date (tramtype property <code style="color:green">introduction_date</code>) is passed and all required tramtypes (tramtype property <code style="color:green">requires_tramtype_list </code>) are available.

Via tramtype property <code style="color:green">powered_tramtype_list</code> multiple tramtypes can be defined, which shall be considered equivalent to a tramtype.
This affects the interpretation of road vehicle property <code style="color:green">tram_type</code>. If road vehicle property <code style="color:green">tram_type</code> references an undefined tramtype, then tramtype property <code style="color:green">powered_tramtype_list</code> is checked for all defined tramtypes, whether the vehicle can be reassigned to some other tramtype. Otherwise the vehicle is disabled.

==Tramtype properties==

{| class="t"
! property
! value range
! comment
|-
| label
| 4-byte string
| names of default tram types: "RAIL" and "ELRL". See the [[TramtypeLabels|List of tramtype labels]] in the NewGRF Specs for currently defined custom labels.
|-
| introduction_date
| date(yyyy,mm,dd)
| Valid range for yyyy is 0 ... 5000000.
|-
| name
| string
| Name of this tramtype
|-
| toolbar_caption
| string
| Caption of the build tram toolbar. In earlier versions this is the same as the 'name'
|-
| menu_text
| string
| Shown in the dropdown menu for all tramtypes
|-
| 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 <tram type> engine" news message
|-
| powered_tramtype_list
| list of tramtype labels
| Provide a list of tram types that tram vehicles of this type are powered on, e.g. ["RAIL", "ELRL"]. Note that there is no "compatible_tramtype_list" since there is no difference between "powered" and "compatible" for tramtypes
|-
| tramtype_flags
| bitmask(TRAMTYPE_FLAG_XXX, ...)
|
;CATENARY
:Enable catenary
;NO_LEVEL_CROSSING
:Disable level crossings
;NO_HOUSES
:Disallows house construction
;HIDDEN
:Hides the tramtype from players, but remains available to towns...which can't use them
;TOWN_BUILD
:Towns don't build tramtracks...so not sure what the purpose of this is
|-
| construction_cost
| 0 ... 65525
| Per piece of track as multiplier to PR_BUILD_ROAD base cost. Default cost factors are 8 and 16 for RAIL and ELRL, respectively.
|-
| speed_limit
| 0 ... 65525 km/h (speed units)
| A speed limit of 0 means unlimited speed
|-
| map_colour
| 0 ... 255
| Entry in the colour palette.
|-
| requires_tramtype_list
| list of tramtype labels
| List of tram types 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.
|-
| introduces_tramtype_list
| list of tramtype labels
| 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.
|-
| sort_order
| 0 ... 255
| Number which defines the sort order among tram types. If this entry is not defined, it gets assigned sort order n*10+7 for the n-th tramtype.
|-
| maintenance_cost
| 0 ... 255
| Maintenance cost factor for each piece of tram of this tramtype. Default cost factors are 16 and 24 for RAIL and ELRL, respectively.
|-
| alternative_tramtype_list
| list of tramtype labels
| List of tram types which this tram type will act as fallback for, if the corresponding tram type is not defined separately
|}

===Sort order===

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

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

==Tramtype variables==

{| class="t"
! name
! value range
! comment
|-
| terrain_type
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|
|-
| enhanced_tunnels
| 0
| Reserved for future use, always returns 0 in OpenTTD. Should custom tunnel entrances be implemented, 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
|-
| random_bits
|
| 2 pseudo random bits
|}

==Tramtype callbacks==

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

{| class="t"
! callbacks
! number of sprites
! meaning
|-
| gui
| 12
| 6 gui icons, 6 cursors
|-
| track_overlay<ref name=leftout>Either all or none of these sprites should be provided.</ref>
| 19
| 11 track combinations, 4 slopes, and 4 dead ends. These sprites are required
|-
| underlay<ref name=leftout />
| 19
| 11 track combinations, 4 slopes, and 4 dead ends. These sprites are required

|-
| catenary_front
| 29
| 11 track combinations, 4 slopes, 4 dead ends, 4 tunnels, 2 bridge middle, 4 bridge ramps
|-
| catenary_back
| 29
| 11 track combinations, 4 slopes, 4 dead ends, 4 tunnels (unused), 2 bridge middle, 4 bridge ramps
|-
| bridge_surfaces<ref name=leftout />
| 6
| 2 bridge middle, 4 bridge ramps
|-
| depots
| 6
| If not present, the default depot sprites (depending on catenary flag) plus track overlay are drawn.
If present, the depot sprites are expected to include track overlay graphics.

|}

<references />
Note that there is no "default" graphics callback.

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

[[File:Nrt_gui.png]]

==== underlay ====

[[File:Nrt_underlay.png]]

==== overlay ====

[[File:Nrt_overlay.png]]

==== catenary_front ====

[[File:Nrt_catenary_front.png]]

==== catenary_back ====

[[File:Nrt_catenary_back.png]]

==== depots ====

[[File:Nrt_depot.png]]

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

==== bridge_surfaces ====

[[File:Nrt_bridge.png]]


===Example code===

A typical implementation for tramtypes can look like:

<pre style="color:blue">
item(FEAT_TRAMTYPES, dctram, 0x01) {
property {
label: "DCTM";
name: string(STR_DC_TRAM);
menu_text: string(STR_DC_TRAM);
build_window_caption: string(STR_BUILD_CAPTION);
autoreplace_text: string(STR_AUTOREPLACE);
new_engine_text: string(STR_NEW_ENGINE);
powered_tramtype_list: ["DCTM","ELRL"]; // These trams are compatible with other electric trams
tramtype_flags: bitmask(TRAMTYPE_FLAG_CATENARY); // These tramways require catenary
construction_cost: 24; // Electric tramways are pricey
speed_limit: 50 km/h;
}
graphics {
underlay: ground_switch_underlay; // defines the tramtrack underlay
overlay: track_overlay_switch; // defines the tramtrack overlay
tunnels: tunnel_switch; // defines the track drawn on a tunnel tile
depots: depot_switch; // defines the depot sprites
bridge_surfaces: bridge_terrain_switch; // defines the overlay drawn over bridges depending on climate
}
}
</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:Tramtypes

2019-12-28T08:37:56Z

Andrew350: various fixes and clean up

{{NMLNavPropVarCB}}

Tramtypes can only be defined in OpenTTD {{ottd|1.10}} and {{nml|0.5}} or later.

==Tramtype IDs==
Tramtypes and Roadtypes share a pool of 64 IDs. Either feature can use as many IDs as needed (i.e. it is not limited to 32 per type), but both features combined are limited to 64 in total. NewGRF-local IDs may freely be chosen, but must be in the 0..63 range. If other tramtype/tramtype GRFs are loaded, it may be that there are not enough 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 (tramtype_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 tramtypes.

== 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.
* Remember that the road vehicle flag 'ROADVEH_FLAG_TRAM' must be set in order for a road vehicle to be considered a tram.
* A vehicle exists, if its tramtype (road vehicle property <code style="color:green">tram_type</code>) is defined. Otherwise the vehicle is disabled.
* When a vehicle is introduced, it always introduces its tramtype (road vehicle property <code style="color:green">tram_type</code>).
* A tramtype is introduced, if at least one of the following conditions is met:
** A vehicle is introduced, that references the tramtype (road vehicle property <code style="color:green">tram_type</code>).
** Another tramtype is introduced, that references the tramtype via the introduced tramtype list (tramtype property <code style="color:green">introduces_tramtype_list</code>).
** The introduction date (tramtype property <code style="color:green">introduction_date</code>) is passed and all required tramtypes (tramtype property <code style="color:green">requires_tramtype_list </code>) are available.

Via tramtype property <code style="color:green">powered_tramtype_list</code> multiple tramtypes can be defined, which shall be considered equivalent to a tramtype.
This affects the interpretation of road vehicle property <code style="color:green">tram_type</code>. If road vehicle property <code style="color:green">tram_type</code> references an undefined tramtype, then tramtype property <code style="color:green">powered_tramtype_list</code> is checked for all defined tramtypes, whether the vehicle can be reassigned to some other tramtype. Otherwise the vehicle is disabled.

==Tramtype properties==

{| class="t"
! property
! value range
! comment
|-
| label
| 4-byte string
| names of default tram types: "RAIL" and "ELRL". See the [[TramtypeLabels|List of tramtype labels]] in the NewGRF Specs for currently defined custom labels.
|-
| introduction_date
| date(yyyy,mm,dd)
| Valid range for yyyy is 0 ... 5000000.
|-
| name
| string
| Name of this tramtype
|-
| toolbar_caption
| string
| Caption of the build tram toolbar. In earlier versions this is the same as the 'name'
|-
| menu_text
| string
| Shown in the dropdown menu for all tramtypes
|-
| 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 <tram type> engine" news message
|-
| powered_tramtype_list
| list of tramtype labels
| Provide a list of tram types that tram vehicles of this type are powered on, e.g. ["RAIL", "ELRL"]. Note that there is no "compatible_tramtype_list" since there is no difference between "powered" and "compatible" for tramtypes
|-
| tramtype_flags
| bitmask(TRAMTYPE_FLAG_XXX, ...)
|
;CATENARY
:Enable catenary
;NO_LEVEL_CROSSING
:Disable level crossings
;NO_HOUSES
:Disallows house construction
;HIDDEN
:Hides the tramtype from players, but remains available to towns...which can't use them
;TOWN_BUILD
:Towns don't build tramtracks...so not sure what the purpose of this is
|-
| construction_cost
| 0 ... 65525
| Per piece of track as multiplier to PR_BUILD_ROAD base cost. Default cost factors are 8 and 16 for RAIL and ELRL, respectively.
|-
| speed_limit
| 0 ... 65525 km/h (speed units)
| A speed limit of 0 means unlimited speed
|-
| map_colour
| 0 ... 255
| Entry in the colour palette.
|-
| requires_tramtype_list
| list of tramtype labels
| List of tram types 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.
|-
| introduces_tramtype_list
| list of tramtype labels
| 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.
|-
| sort_order
| 0 ... 255
| Number which defines the sort order among tram types. If this entry is not defined, it gets assigned sort order n*10+7 for the n-th tramtype.
|-
| maintenance_cost
| 0 ... 255
| Maintenance cost factor for each piece of tram of this tramtype. Default cost factors are 16 and 24 for RAIL and ELRL, respectively.
|-
| alternative_tramtype_list
| list of tramtype labels
| List of tram types which this tram type will act as fallback for, if the corresponding tram type is not defined separately
|}

===Sort order===

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

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

==Tramtype variables==

{| class="t"
! name
! value range
! comment
|-
| terrain_type
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|
|-
| enhanced_tunnels
| 0
| Reserved for future use, always returns 0 in OpenTTD. Should custom tunnel entrances be implemented, 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
|-
| random_bits
|
| 2 pseudo random bits
|}

==Tramtype callbacks==

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

{| class="t"
! callbacks
! number of sprites
! meaning
|-
| gui
| 12
| 6 gui icons, 6 cursors
|-
| track_overlay<ref name=leftout>Either all or none of these sprites should be provided.</ref>
| 19
| 11 track combinations, 4 slopes, and 4 dead ends. These sprites are required
|-
| underlay<ref name=leftout />
| 19
| 11 track combinations, 4 slopes, and 4 dead ends. These sprites are required

|-
| catenary_front
| 29
| 11 track combinations, 4 slopes, 4 dead ends, 4 tunnels, 2 bridge middle, 4 bridge ramps
|-
| catenary_back
| 29
| 11 track combinations, 4 slopes, 4 dead ends, 4 tunnels (unused), 2 bridge middle, 4 bridge ramps
|-
| bridge_surfaces<ref name=leftout />
| 6
| 2 bridge middle, 4 bridge ramps
|-
| depots
| 6
| If not present, the default depot sprites (depending on catenary flag) plus track overlay are drawn.
If present, the depot sprites are expected to include track overlay graphics.

|}

<references />
Note that there is no "default" graphics callback.

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

[[File:Nrt_gui.png]]

==== underlay ====

[[File:Nrt_underlay.png]]

==== overlay ====

[[File:Nrt_overlay.png]]

==== catenary_front ====

[[File:Nrt_catenary_front.png]]

==== catenary_back ====

[[File:Nrt_catenary_back.png]]

==== depots ====

[[File:Nrt_depot.png]]

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

==== bridge_surfaces ====

[[File:Nrt_bridge.png]]


===Example code===

A typical implementation for tramtypes can look like:

<pre style="color:blue">
item(FEAT_TRAMTYPES, dctram, 0x01) {
property {
label: "DCTM";
name: string(STR_DC_TRAM);
menu_text: string(STR_DC_TRAM);
build_window_caption: string(STR_BUILD_CAPTION);
autoreplace_text: string(STR_AUTOREPLACE);
new_engine_text: string(STR_NEW_ENGINE);
powered_tramtype_list: ["DCTM","ELRL"]; // These trams are compatible with other electric trams
tramtype_flags: bitmask(TRAMTYPE_FLAG_CATENARY); // These tramways require catenary
construction_cost: 24; // Electric tramways are pricey
speed_limit: 50 km/h;
}
graphics {
underlay: ground_switch_underlay; // defines the tramtrack underlay
overlay: track_overlay_switch; // defines the tramtrack overlay
tunnels: tunnel_switch; // defines the track drawn on a tunnel tile
depots: depot_switch; // defines the depot sprites
bridge_surfaces: bridge_terrain_switch; // defines the overlay drawn over bridges depending on climate
}
}
</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:Roadtypes

2019-12-28T08:18:36Z

Andrew350: various fixes and clean up

{{NMLNavPropVarCB}}

Roadtypes can only be defined in OpenTTD {{ottd|1.10}} and {{nml|0.5}} or later.

==Roadtype IDs==
Roadtypes and Tramtypes share a pool of 64 IDs. Either feature can use as many IDs as needed (i.e. it is not limited to 32 per type), but both features combined are limited to 64 in total. NewGRF-local IDs may freely be chosen, but must be in the 0..63 range. If other roadtype/tramtype GRFs are loaded, it may be that there are not enough 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 (roadtype_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 roadtypes.

== 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 property <code style="color:green">road_type</code>) is defined. Otherwise the vehicle is disabled.
* When a vehicle is introduced, it always introduces its roadtype (road vehicle property <code style="color:green">road_type</code>).
* A roadtype is introduced, if at least one of the following conditions is met:
** A vehicle is introduced, that references the roadtype (road vehicle property <code style="color:green">road_type</code>).
** Another roadtype is introduced, that references the roadtype via the introduced roadtype list (roadtype property <code style="color:green">introduces_roadtype_list</code>).
** The introduction date (roadtype property <code style="color:green">introduction_date</code>) is passed and all required roadtypes (roadtype property <code style="color:green">requires_roadtype_list </code>) are available.

Via roadtype property <code style="color:green">powered_roadtype_list</code> multiple roadtypes can be defined, which shall be considered equivalent to a roadtype.
This affects the interpretation of road vehicle property <code style="color:green">road_type</code>. If road vehicle property <code style="color:green">road_type</code> references an undefined roadtype, then
roadtype property <code style="color:green">powered_roadtype_list</code> is checked for all defined roadtypes, whether the vehicle can be reassigned to some other roadtype.
Otherwise the vehicle is disabled.

==Roadtype properties==

{| class="t"
! property
! value range
! comment
|-
| label
| 4-byte string
| names of default road types: "ROAD" and "ELRD". See the [[RoadtypeLabels|List of roadtype labels]] in the NewGRF Specs for currently defined custom labels.
|-
| introduction_date
| date(yyyy,mm,dd)
| Valid range for yyyy is 0 ... 5000000.
|-
| name
| string
| Name of this roadtype
|-
| toolbar_caption
| string
| Caption of the build road toolbar
|-
| menu_text
| string
| Shown in the dropdown menu for all roadtypes
|-
| 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 <road type> engine" news message
|-
| powered_roadtype_list
| list of roadtype labels
| Provide a list of road types that road vehicles of this type are powered on, e.g. ["ROAD", "ELRD"]. Note that there is no "compatible_roadtype_list" since there is no difference between "powered" and "compatible" for roadtypes
|-
| roadtype_flags
| bitmask(ROADTYPE_FLAG_XXX, ...)
|
;CATENARY
:Enable catenary
;NO_LEVEL_CROSSING
:Disable level crossings
;NO_HOUSES
:Disallows house construction
;HIDDEN
:Hides the roadtype from players, but remains available to towns
;TOWN_BUILD
:Enables the roadtype to be built by towns, based on ???
|-
| construction_cost
| 0 ... 65525
| Per piece of road as multiplier to PR_BUILD_ROAD base cost. Default cost factors are 8 and 16 for ROAD and ELRD, respectively.
|-
| speed_limit
| 0 ... 65525 km/h (speed units)
| A speed limit of 0 means unlimited speed
|-
| map_colour
| 0 ... 255
| Entry in the colour palette.
|-
| requires_roadtype_list
| list of roadtype labels
| List of road types 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.
|-
| introduces_roadtype_list
| list of roadtype labels
| 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.
|-
| sort_order
| 0 ... 255
| Number which defines the sort order among road types. If this entry is not defined, it gets assigned sort order n*10+7 for the n-th roadtype.
|-
| maintenance_cost
| 0 ... 255
| Maintenance cost factor for each piece of road of this roadtype. Default cost factors are 16 and 24 for ROAD and ELRD, respectively.
|-
| alternative_roadtype_list
| list of roadtype labels
| List of road types which this road type will act as fallback for, if the corresponding road type is not defined separately
|}

===Sort order===

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

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

==Roadtype variables==

{| class="t"
! name
! value range
! comment
|-
| terrain_type
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|
|-
| enhanced_tunnels
| 0
| Reserved for future use, always returns 0 in OpenTTD. Should custom tunnel entrances be implemented, 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
|-
| random_bits
|
| 2 pseudo random bits, based on tile location
|}

==Roadtype callbacks==

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

{| class="t"
! callbacks
! number of sprites
! meaning
|-
| gui
| 12
| 6 gui icons, 6 cursors
|-
| track_overlay<ref name=leftout>Either all or none of these sprites should be provided.</ref>
| 19
| 11 roadbit combinations, 4 slopes, and 4 dead ends. These sprites are optional for roadtypes.
|-
| underlay<ref name=leftout />
| 19
| 11 roadbit combinations, 4 slopes, and 4 dead ends. These sprites are required.

|-
| catenary_front
| 29
| 11 roadbit combinations, 4 slopes, 4 dead ends, 4 tunnels, 2 bridge middle, 4 bridge ramps
|-
| catenary_back
| 29
| 11 roadbit combinations, 4 slopes, 4 dead ends, 4 tunnels (unused), 2 bridge middle, 4 bridge ramps
|-
| bridge_surfaces<ref name=leftout />
| 6
| 2 bridge middle, 4 bridge ramps
|-
| depots
| 6
| If not present, the default depot sprites (depending on catenary flag) plus track overlay are drawn.
If present, the depot sprites are expected to include track overlay graphics.

|-
| roadstops
| 4
| Overlays for drive-in road stops
|}

<references />
Note that there is no "default" graphics callback.

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

[[File:Nrt_gui.png]]

==== underlay ====

[[File:Nrt_underlay.png]]

==== catenary_front ====

[[File:Nrt_catenary_front.png]]

==== catenary_back ====

[[File:Nrt_catenary_back.png]]

==== depots ====

[[File:Nrt_depot.png]]

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

==== bridge_surfaces ====

[[File:Nrt_bridge.png]]

==== roadstops ====

[[File:Nrt_drivein.png]]


===Example code===

A typical implementation for roadtypes can look like:

<pre style="color:blue">
item(FEAT_ROADTYPES, highway, 0x01) {
property {
label: "HWY_";
name: string(STR_HWY);
menu_text: string(STR_HWY);
build_window_caption: string(STR_BUILD_CAPTION);
autoreplace_text: string(STR_AUTOREPLACE);
new_engine_text: string(STR_NEW_ENGINE);
powered_roadtype_list: ["HWY_","ROAD"]; // Highways are compatible with other roads
roadtype_flags: bitmask(ROADTYPE_FLAG_NO_LEVEL_CROSSING, ROADTYPE_FLAG_NO_HOUSES); // Highways should not have level crossings or houses
construction_cost: 32; // Highways are expensive
speed_limit: 100 km/h;
}
graphics {
underlay: ground_switch_underlay; // defines the usual roads
tunnels: tunnel_switch; // defines the roads drawn on a tunnel tile
depots: depot_switch; // defines the depot sprites
bridge_surfaces: bridge_terrain_switch; // defines the overlay drawn over bridges depending on climate
roadstops: roadstops_switch; // defines the look of roadstop pavement
}
}
</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

2019-12-28T07:45:06Z

Andrew350: /* String codes */ added push/pop function

{{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><br /> 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 || <div style="background:#3890E8;width:2em;"> </div>
|-
|SILVER || switch to silver text || <div style="background:#C8C8C8;width:2em;"> </div>
|-
|GOLD || switch to golden text || <div style="background:#FCC000;width:2em;"> </div>
|-
|RED || switch to red text || <div style="background:#FC0000;width:2em;"> </div>
|-
|PURPLE || switch to purple text || <div style="background:#A888E0;width:2em;"> </div>
|-
|LTBROWN || switch to light brown text || <div style="background:#B0B084;width:2em;"> </div>
|-
|ORANGE || switch to orange text || <div style="background:#FCB030;width:2em;"> </div>
|-
|GREEN || switch to green text || <div style="background:#90E05C;width:2em;"> </div>
|-
|YELLOW || switch to yellow text || <div style="background:#FCF880;width:2em;"> </div>
|-
|DKGREEN || switch to dark green text || <div style="background:#B4CC7C;width:2em;"> </div>
|-
|CREAM || switch to cream-coloured text || <div style="background:#D49480;width:2em;"> </div>
|-
|BROWN || switch to brown text || <div style="background:#A46040;width:2em;"> </div>
|-
|WHITE || switch to white text || <div style="background:#FCFCFC;width:2em;"> </div>
|-
|LTBLUE || switch to light blue text || <div style="background:#80C4FC;width:2em;"> </div>
|-
|GRAY || switch to gray text || <div style="background:#626562;width:2em;"> </div>
|-
|DKBLUE || switch to dark blue text || <div style="background:#8484A4;width:2em;"> </div>
|-
|BLACK || switch to black text || <div style="background:#101010;width:2em;"> </div>
|-
|PUSH_COLOUR || {{ottdp|1.10|no}} Push current colour onto colour stack. Use this if you need to switch colour and restore later ||
|-
|POP_COLOUR || {{ottdp|1.10|no}} Pop last colour from colour stack. Use this to restore previous colour ||
|}

== 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
|-
|CARGO_LONG || {{ottdp|1.4|no|ottdrev=r26244}} cargo amount in proper units || 4 (2 + 2)<ref name="cargoamount">First (lower) 2 bytes for cargo type, second (higher) 2 bytes for cargo amount.</ref> || 10 bags of mail
|-
|CARGO_SHORT || {{ottdp|1.4|no|ottdrev=r26244}} cargo amount in proper units in short form || 4 (2 + 2)<ref name="cargoamount"/> || 10 bags
|-
|CARGO_TINY || {{ottdp|1.4|no|ottdrev=r26244}} cargo amount in proper units in tiny form (only unit conversion) || 4 (2 + 2)<ref name="cargoamount"/> || 10
|-
|CARGO_NAME || {{ottdp|1.7|no|ottdrev=r27706}} cargo name || 2 || Coal
|-
|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
|}
<references/>

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

{{:language_IDs}}

In case a language is not in this list, edit the shared [[language_IDs|master language list]] 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:Railtypes

2019-12-28T06:21:17Z

Andrew350: /* Railtype variables */ added random_bits and clarified description of enhanced_tunnels

{{NMLNavPropVarCB}}

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

==Railtype IDs==
Railtype IDs are limited to 64 in total. NewGRF-local IDs may freely be chosen, but must be in the 0..63 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.

== Vehicle and Railtype availability ==

Vehicle and railtype availability and compatibility is influenced by multiple properties.
Generally, the vehicle defines which railtype it is, and the railtypes define the compatibility between each other.
* A vehicle exists, if its railtype (train property <code style="color:green">track_type</code>) is defined. Otherwise the vehicle is disabled.
* When a vehicle is introduced, it always introduces its railtype (train property <code style="color:green">track_type</code>).
* A railtype is introduced, if at least one of the following conditions is met:
** A vehicle is introduced, that references the railtype (train property <code style="color:green">track_type</code>).
** Another railtype is introduced, that references the railtype via the introduced railtype list (railtype propery <code style="color:green">introduces_railtype_list</code>).
** The introduction date (railtype property <code style="color:green">introduction_date</code>) is passed and all required railtypes (railtype property <code style="color:green">requires_railtype_list </code>) are available.

Via railtype property <code style="color:green">compatible_railtype_list</code> multiple railtypes can be defined, which shall be considered equivalent to a railtype.
This affects the interpretation of train property <code style="color:green">track_type</code>. If train property <code style="color:green">track_type</code> references an undefined railtype, then
railtype property <code style="color:green">compatible_railtype_list</code> is checked for all defined railtypes, whether the vehicle can be reassigned to some other railtype.
Otherwise the vehicle is disabled.

==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, ...)
|
; CATENARY
: Enable catenary
; NO_LEVEL_CROSSING
: Disable level crossings
; HIDDEN {{ottd|1.9}}
: Hides railtype from player
; PRECOMBINED {{ottd|1.10}}
: Enable use of precombined overlay sprites
; ALLOW_90DEG {{ottd|1.10}}
: Always allow 90 degree turns
; DISALLOW_90DEG {{ottd|1.10}}
: Always prohibit 90 degree turns (takes precedence over ALLOW_90DEG)
|-
| curve_speed_multiplier
| 0...255
| 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
| 0 ... 255
|
{{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 of 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
| Reserved for future use, always returns 0 in OpenTTD. Should custom tunnel entrances be implemented, 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.)
|-
| random_bits
|
| 2 pseudo-random bits, based on tile location
|}

==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. Used in junctions, and also with path signals, if the "Show reserved tracks" option is enabled in the game settings.
|-
| 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 / 16
| x, y, vertical, horizontal, SW, SE, NE and NW slopes like original fences at sprite 1301. {{ottdp|1.6|no|ottdrev=r27343}} Since OpenTTD r27343 there is also a 16 sprites version, see below.
|-
| 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>getbits(extra_callback_info1, 0, 8)</code>: 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, NW, SE, E, W, S, N. For more information, see [[#signals|below]]
|-
| precombined<ref name=leftout />
| 63
| {{ottd|1.10}} 1 sprite for each combination of track on a tile. The index is determined by treating each track piece as a bit in the order X Y N S W E, subtracting 1, see [[#Precombined overlay sprites|below]]
|}

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

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

[[File:railtype_gui.png]]

==== track_overlay ====

[[File:railtype_overlay.png]]

==== underlay ====

[[File:railtype_underlay.png]]

==== level_crossings ====

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

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

[[File:railtype_levelcrossing.png]]

==== depots ====

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

==== fences ====

[[File:railtype_fences.png]]

{{ottdp|1.6|no|ottdrev=r27343}} Since OpenTTD r27343 there is also a 16 sprites version, this allows to use different sprites resp. offsets for the fences on either track side.

{| |-
! Sprite number !! Tile slope !! Track bit !! Fence position !! Version
|-
| 0 || flat || X || NW || {{ottdp|1.0|no|ottdrev=r19056}}
|-
| 1 || flat || Y || NE || {{ottdp|1.0|no|ottdrev=r19056}}
|-
| 2 || flat || left || E || {{ottdp|1.0|no|ottdrev=r19056}}
|-
| 3 || flat || upper || S || {{ottdp|1.0|no|ottdrev=r19056}}
|-
| 4 || SW || X || NW || {{ottdp|1.0|no|ottdrev=r19056}}
|-
| 5 || SE || Y || NE || {{ottdp|1.0|no|ottdrev=r19056}}
|-
| 6 || NE || X || NW || {{ottdp|1.0|no|ottdrev=r19056}}
|-
| 7 || NW || Y || NE || {{ottdp|1.0|no|ottdrev=r19056}}
|-
| 8 || flat || X || SE || {{ottdp|1.6|no|ottdrev=r27343}}
|-
| 9 || flat || Y || SW || {{ottdp|1.6|no|ottdrev=r27343}}
|-
| 10 || flat || left || W || {{ottdp|1.6|no|ottdrev=r27343}}
|-
| 11 || flat || upper || N || {{ottdp|1.6|no|ottdrev=r27343}}
|-
| 12 || SW || X || SE || {{ottdp|1.6|no|ottdrev=r27343}}
|-
| 13 || SE || Y || SW || {{ottdp|1.6|no|ottdrev=r27343}}
|-
| 14 || NE || X || SE || {{ottdp|1.6|no|ottdrev=r27343}}
|-
| 15 || NW || Y || SW || {{ottdp|1.6|no|ottdrev=r27343}}
|}

==== 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. If resolving fails or results in an empty sprite group, the matching base set sprite will be used instead.

Variable <code style:darkgreen>extra_callback_info2</code> contains the state, variant and type of the signal. Use the builtin function <code style:darkgreen>getbits()</code> in the following fashion to access the information:
<ul><li>
Signal state: <code style:darkgreen>getbits(extra_callback_info2, 0, 8)</code>:
{| |-
! Result !! Meaning
|-
| 00 || Red signal
|-
| 01 || Green signal
|-
| all other values || Reserved
|}
</li><li>
Signal variant: <code style:darkgreen>getbits(extra_callback_info2, 8, 8)</code>:
{| |-
! Result !! Meaning
|-
| 00 || Light (electric) signal
|-
| 01 || Semaphore
|-
| all other values || Reserved
|}
</li><li>
Signal type: <code style:darkgreen>getbits(extra_callback_info2, 16, 8)</code>:
{| |-
! Result !! Meaning
|-
| 00 || Normal block signal
|-
| 01 || Entry pre-signal
|-
| 02 || Exit pre-signal
|-
| 03 || Combo pre-signal
|-
| 04 || Two-way path signal
|-
| 05 || One-way path signal
|-
| all other values || Reserved
|}
</li></ul>
Variable <code style:darkgreen>extra_callback_info1</code> contains the drawing context.
<ul><li>
<code style:darkgreen>getbits(extra_callback_info1, 0, 8)</code>:
{| |-
! Result !! 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
|}
</li></ul>

====Precombined overlay sprites====

[[File:Rails_combined.png]]

===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 only have 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 tunnel 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 catenary 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.

RandomAction2

2019-12-28T06:07:11Z

Andrew350: /* Triggers */ added road/tramtypes

==Introduction==

Unlike [[VariationalAction2]], whose results are always determined by a predictable decision, RandomAction2 can use randomized results to pick one of several [[Action2]] entries.

== Format ==

The data looks as follows:

<Sprite-number> * <Length> 02 <feature> <set-id> <nowiki>[80|83]</nowiki> <random-triggers> <randbit> <nrand> <set-ids>

From TTDPatch 2.6 r1850 and OpenTTD r12452, and '''for vehicles only''':

<Sprite-number> * <Length> 02 <feature> <set-id> 84 <count> <random-triggers> <randbit> <nrand> <set-ids>

{| |-
!'''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)
|-
|80, 83, 84||B||Type of random action, see below.
|-
|<count>||B||(when present) Location of controlling vehicle.
|-
|<random-triggers>||B||When to re-randomize
|-
|<randbit>||B||What random bit to use for this action 2
|-
|<nrand>||B||Number of set-ids to choose from, must be a power of 2
|-
|<set-ids>||W||Action 2 set-ids to choose from.
|}

== Description ==

=== Sprite-number ===

This is just the number you are at.

=== Length ===

Count the number of bytes in this action.

===Feature===

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

{|- |
!Value!![[Features|Feature]]
|-
|00||Trains
|-
|01||Road Vehicles
|-
|02||Ships
|-
|03||Aircraft
|-
|04||Stations
|-
|05||Canals/Rivers
|-
|07||Houses
|-
|09||Industry Tiles
|-
|0A||Industries
|-
|0D||Airports
|-
|0F||Objects
|-
|10||Railtypes
|-
|11||Airport Tiles
|-
|12||Roadtypes
|-
|13||Tramtypes
|}

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

=== 80/83/84 ===

Use 80 to randomize the object (vehicle, station, building, industry, object) based on its own triggers and bits.

Use 83 to randomize the object based on its "related" object (s.b.).

Use 84 to randomize the vehicle based on any vehicle in the consist.

{| |-
!Feature!!Related object
|-
|Vehicles (00-03)||First vehicle of consist
|-
|Stations (04)||N/A
|-
|Houses (07)||N/A
|-
|Industry tiles (09)||Industry containing tile
|-
|Industries (0A)||N/A
|-
|Objects (0F)||N/A
|}

=== count ===

For type 84, this specifies which vehicle's random bits this vehicle will be using and/or modifying.

The low nibble (bits 0-3) specifies how far to count from the starting vehicle. If it is zero, the count will be read from GRF register 100h instead.

The high nibble (bits 6-7, actually) specifies which vehicle is the starting vehicle, and which direction to count:

{| |-
!Value!!Meaning
|-
|0||count back (away from the engine), starting at this vehicle
|-
|4||count forward (toward the engine), starting at this vehicle.
|-
|8||count back, starting at the engine
|-
|C||count back, starting at the first vehicle in this chain of vehicles with the same ID, as for vehicle variable 41
|}

Bits 4-5 are reserved and must be zero, so other values of the high nibble are not allowed.

=== random-triggers ===

This is a bit mask of triggers which cause re-randomizing. Normally, any matching trigger causes the graphics to be randomized again, but if you add 80 to the bitmask, the re-randomizing only happens if '''all''' triggers have occurred.

Trigger bits are feature-specific, see below.

Note, that rerandomisation only occurs in the graphics chain, not for callbacks. So, if you use a random action only inside a callback and want to rerandomise the bits, you have to add a "dummy" rerandomisation RA2 into the graphics chain.

Example:
-1 * -1 02 04 02
80 // random in callback
00 // no triggers
00 // first random bit to use
\b 16 // number of cases
\w 10 \w 11 \w 12 \w 13 // random cases
\w 14 \w 15 \w 16 \w 17
\w 18 \w 19 \w 20 \w 21
\w 22 \w 23 \w 24 \w 25

-1 * -1 02 04 01
85 0C 00 \wx FFFF
01
\w 2 \w 14 \w 14 // callback 14
\w 3 // graphics chain

-1 * -1 02 04 00
80 // dummy random outside callback
04 // train arrival
00 // first bit to rerandomise
\b 16 // number of cases
\w 1 \w1 \w 1 \w1 // all cases the same, only for triggering rerandomisation
\w 1 \w1 \w 1 \w1
\w 1 \w1 \w 1 \w1
\w 1 \w1 \w 1 \w1

-1 * -1 03 04 01 00 00 \w 0 // action 3

=== randbit ===

{{ottdp|no|<2.5|ttdprev=alpha30}} For versions before TTDPatch 2.0.1 alpha 30, leave this at 00. It doesn't quite work the way intended (it was supposed to allow independent random chains, but currently everything is re-randomized at the same time, thereby defeating this mechanism).

{{ottdp| |2.5|ttdprev=alpha 30}} Since TTDPatch 2.0.1 alpha 30, only those bits that actually get triggered will be re-randomized. Prior versions always re-randomized all bits. This will make it possible to have independent sets of bits for independent triggers (or untriggered bits, set only at the time of purchase). Setting randbit determines the first bit to be re-randomized, as well as basing the random graphics on. The total number of bits used is the 2-logarithm of nrand below (e.g., for nrand=16, 4 bits are used).

=== nrand ===

Number of different sets to choose from.  This must be a power of 2, i.e. 2, 4, 8, 16 etc.

=== set-ids ===

Action 2 IDs to randomly choose from

== Triggers ==

{| |-
!rowspan="2"|Feature
!colspan="2"|Random bits
!rowspan="2"|Triggers
|-
!Self!!Related
|-
|Vehicles||8||8 read-only||yes
|-
|Stations||16 + 4 <ref name="stationshared">16 Bits shared for the whole station/airport (airport and station share the same bits). 4 bits per tile.</ref><ref>TTDPatch actually only implements 8 shared random bits (plus 4 per tile). Bits 8-15 are always zero.</ref>
|no||yes
|-
|Canals||8||no||no
|-
|Houses||8||no||yes
|-
|Industry tiles||8||16||yes
|-
|Industries||16||no||no
|-
|Airports||16 <ref name="stationshared"/>||no||no
|-
|Objects||8||no||no
|-
|Railtypes||2||no||no
|-
|Roadtypes||2||no||no
|-
|Tramtypes||2||no||no
|-
|Airport tiles||16 + 4 <ref name="stationshared"/>||no||no
|}
<references/>

=== Vehicles ===

Vehicles have 8 random bits, and the following triggers:

{| |-
!Bit!!Value!!Version!!Trigger
|-
|0||01||{{ottdp|0.6|2.0}}||Vehicle gets new load of cargo (only after it was empty)
|-
|1||02||{{ottdp|0.6|2.0}}||Vehicle enters a depot and is serviced
|-
|2||04||{{ottdp|0.6|2.5}}||The consist has unloaded all cargo
|-
|3||08||{{ottdp|0.6|2.5}}||Any vehicle of the consist receives cargo
|-
|4||10||{{ottdp|0.6|2.5}}||[[Callbacks#32-day callback (32) |Callback 32]] returned 1
|}

The consist trigger bits 2 and 3 allow re-randomizing whenever the consist receives cargo after fully unloading. They should be used with action 2 type 80, not 83, and the random-triggers variable should have 80 added to it, to make the re-randomizing happen only if the consist was empty and '''then''' received new cargo.

Vehicles can read the random bits of other vehicles (using random action type 83 or 84), but they can only trigger
rerandomisation of their own bits. Do not specify any triggers for rerandomisation when accessing random bits of other vehicles (via type 83 or 84), it will not do what you think.

=== Stations ===

Stations have 16+4 random bits. Bits 0 to 15 are a property of the station as a whole, and bits 16 to 19 are different for each tile.  To get tile-based randomness, therefore use randbit=10 and nrand of no more than 16 (since only 4 random bits are available per tile).

{| |-
!Bit!!Value!!Version!!Trigger
|-
|0||01||{{ottdp|1.3|2.5}}||new cargo waiting
|-
|1||02||{{ottdp|1.3|2.5}}||no more cargo
|-
|2||04||{{ottdp|1.3|2.5}}||train arrives (starts unloading/loading)
|-
|3||08||{{ottdp|1.3|2.5}}||train leaves (done unloading & loading)
|-
|4||10||{{ottdp|1.3|2.5}}||train loads or unloads cargo
|-
|5||20||{{ottdp|1.3|2.5}}||train reserves platform (using PBS)
|}

Also note that none of the above triggers will actually trigger unless prop. 12 has at least one bit set.  Triggers 01 will be triggered for any of the cargo types set in prop. 12, but trigger 02 will only be triggered if all of those cargo types have no more cargo waiting. Triggers 04, 08 and 20 are triggered no matter what cargo types the train transports, as long as prop. 12 is not zero.

Triggers 04, 08, 10 and 20 only affect the platform on which they occur, as well as the random bits of the station, but not other platforms.

Because the 'occured triggers' are only stored once per station (not distinguishing tiles or cargo types), adding 80 to
random-triggers does not make a lot of sense.

=== Town building triggers ===

Town buildings have 8 random bits.

{| |-
!Bit!!Value!!Version!!Trigger
|-
|0||01||{{ottdp|0.6|2.5}}||the building tile is processed in the periodic tile processing loop
|-
|1||02||{{ottdp|0.6|2.5}}||the top tile of the building is processed in the periodic tile processing loop
|}

The periodic tile processing loop constantly processes the tiles of the map, processing any given tile in every 256 ticks (approx. 3.5 TTD days). Since no "real" event happens to town buildings, you have only this opportunity to re-randomize the look of your building.

If every 3.5 days is too fast for you, you can multiply the time-out by setting property 16 for the given tile. The time-out is 256 ticks*(prop. 16+1), so 0 means every 3.5 days, 1 means every 7 days, 2 means every 10.5 days and so on.

If trigger 02 is activated, all parts of the building that has this trigger set will get the same random bits, allowing you to randomize a multi-tile building as one unit. On the other hand, if the tiles of a multi-tile building have trigger 1 set, all tiles will be randomized individually. Note that all tiles of a multi-tile building get the same value when building the building.

=== Industry tile triggers ===

Industry tiles have 8+16 random bits. Accessed through random action 2 type 80, you get 8 tile-specific bits, and accessed through random action 2 type 83, you get 16 industry-specific bits. The triggers are the same for both. Triggers 02 and 04 are triggered for all tiles of the industry at once. Every tile can rerandomise both its own random bits and those of the industry. That is every tile can specify some bits of the industry to rerandomize, and the union of all those bits will be rerandomsied at the end.

{| |-
!Bit!!Value!!Version!!Trigger
|-
|0||01||{{ottdp|0.6|2.5}}||the building tile is processed in the periodic tile processing loop<ref>{{ottdp|no| |}} Rerandomisation of the shared bits of the industry does not happen properly in current TTDPatch.</ref>
|-
|1||02||{{ottdp|0.6|2.5}}||triggers simultaneously for all tiles of the industry every 256 ticks. If the industry is a primary one, output cargo is generated at the same time.
|-
|2||04||{{ottdp|0.6|2.5}}||cargo is delivered to the industry. If the industry is a processing one, output cargo is generated at the same time.
|}
<references />

Trigger 1 works similarly to trigger 1 for houses except that you cannot multiply the timeout: it's always 256 ticks.

Industry tiles can rerandomise both their own random bits as well as the random bits of the industry (via random action type 83).
The remembered triggers for rerandomisation with 80 added to the triggers are in both cases the same per tile.

Industries have random bits. However, they can only be rerandomised by their tiles.

=== Canals ===

Canals / Rivers have 8 random bits.

There is currently no way to influence the random byte creation via triggers, internally the bits are feed from VarAction2Canals var 83 that is set when building a canal. Feature ids not supported by VarAction2Canals are undefined and should never be used.

=== Objects ===

Objects have 8 random bits per tile of the object.

There are no triggers for objects however.

Also note that the random bits are unique to each tile in the object, and are not shared across the whole object.

=== Railtypes ===

Rail tiles have 2 pseudo random bits, based on tile location.

There are no triggers.

=== Roadtypes ===

Road tiles have 2 pseudo random bits, based on tile location.

There are no triggers.

=== Tramtypes ===

Tram tiles have 2 pseudo random bits, based on tile location.

There are no triggers.

=== Other features ===

All features not mentioned in the list above have neither random bits nor triggers, including towns (which would be accessed using random action 2 type 83 for stations and industries).

==Example==

Action5

2019-12-28T05:06:24Z

Andrew350: /* 15 / 95 OpenTTD GUI sprites */ added nrt sprites

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

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

|-
|18,98||{{ottdp|1.5|no|ottdrev=r26869}}||Extra all black palette||1
|}

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

===== In NewGRFs =====
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<ref name=numbers>Sprite numbers from trg1(r).pcx.</ref> is as follows:

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

<references />

[[File:Action5Coast16Sprites.png]]

''The 16 sprites for feature 0D''

===== In Base Set's extra grf =====
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 the base grf. 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 184 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
|-
|166 .. 167 || Icons for delete to the left resp. right
|-
|168 || Default window size
|-
|169 .. 173 || Story book: Main toolbar icon, goto place, unfinished goal, finished goal, broken goal
|-
|174 || Smallmap cargoflow button
|-
|175 .. 178 || Icons for group livery selection
|-
|179 .. 183 || NotRoadTypes toolbar and cursor icons
|}

==== 16 / 96 Airport preview sprites ====
[[File:airport_preview_commuter.png|right]]
Preview sprites for the airports in the order
# Small airport
# City airport
# Heliport
# Metropolitan airport
# International airport
# Commuter airport
# Heli depot
# Intercontinental airport
# Heli station

Sprites are without any offsets and should all be the same size. Make sure so by using the forbid cropping.

==== 17 / 97 Tunnel overlay sprites ====
[[File:tunnel_overlays.png|right]]
The sprites provide the ground for the tunnel sprites to be used by railtype NewGRFs which only need to provide the tunnel portals. They must be provided for both terrain types which could be used in any given climate (grass; grass+snow; grass+desert; grass).

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

Action5

2019-12-28T05:01:39Z

Andrew350: /* type */ increase ottd gui sprite count to 184

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

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

|-
|18,98||{{ottdp|1.5|no|ottdrev=r26869}}||Extra all black palette||1
|}

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

===== In NewGRFs =====
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<ref name=numbers>Sprite numbers from trg1(r).pcx.</ref> is as follows:

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

<references />

[[File:Action5Coast16Sprites.png]]

''The 16 sprites for feature 0D''

===== In Base Set's extra grf =====
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 the base grf. 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
|-
|166 .. 167 || Icons for delete to the left resp. right
|-
|168 || Default window size
|-
|169 .. 173 || Story book: Main toolbar icon, goto place, unfinished goal, finished goal, broken goal
|-
|174 || Smallmap cargoflow button
|-
|175 .. 178 || Icons for group livery selection
|}

==== 16 / 96 Airport preview sprites ====
[[File:airport_preview_commuter.png|right]]
Preview sprites for the airports in the order
# Small airport
# City airport
# Heliport
# Metropolitan airport
# International airport
# Commuter airport
# Heli depot
# Intercontinental airport
# Heli station

Sprites are without any offsets and should all be the same size. Make sure so by using the forbid cropping.

==== 17 / 97 Tunnel overlay sprites ====
[[File:tunnel_overlays.png|right]]
The sprites provide the ground for the tunnel sprites to be used by railtype NewGRFs which only need to provide the tunnel portals. They must be provided for both terrain types which could be used in any given climate (grass; grass+snow; grass+desert; grass).

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

Action0/Airport Tiles

2019-12-22T22:48:54Z

Andrew350: /* Animation triggers via callback 152 (11) */ added new animation trigger

== Introduction ==

{{ottdp|1.1|ottdrev=r19204}}
Airport tiles work like industry tiles and similarly to town buildings, except that they are not stand-alone. This means an airport tile can't stand alone, it's always part of an airport.

== Properties ==

{| |-
!Number!!Version!![[GRFActionsDetailed|Size]]!!Description
|-
|08||{{ottdp|1.1|ottdrev=r19204}}||B||Substitute airport tile type
|-
|09||{{ottdp|1.1|ottdrev=r19204}}||B||Airport tile override
|-
|0E||{{ottdp|1.1|ottdrev=r19204}}||B||Callback flags
|-
|0F||{{ottdp|1.1|ottdrev=r19204}}||W||Animation information
|-
|10||{{ottdp|1.1|ottdrev=r19204}}||B||Animation speed.
|-
|11||{{ottdp|1.1|ottdrev=r19204}}||B||Animation triggers
|}

== Descriptions ==

=== Substitute tile type (08) ===

This tile type will be used instead of your new one if your definition isn't available for any reason. Assigning this property copies the properties of the old type just like it does with houses. If this tile's action 3 appears before this property is set, the action 3 will have no effect.

=== Airport tile override (09) ===

Works like the house override property for houses and industry tiles.

=== Callback flags (0E) ===

{| |-
!Bit!!value!!version!!meaning
|-
|0||1||{{ottdp|1.1|ottdrev=r19204}}||use [[Callbacks#Next animation frame (1A/26/141/153/158) |callback 153]] to decide the next animation frame
|-
|1||2||{{ottdp|1.1|ottdrev=r19204}}||use [[Callbacks#Length of animation frame (20/27/142/154/15A) |callback 154]] to decide animation speed
|-
|2||4||{{ottdp}}||(reserved)
|-
|3||8||{{ottdp}}||(reserved)
|-
|4||10||{{ottdp|1.1|ottdrev=r19204}}||use callback xx to check if a slope is suitable (not yet implemented)
|-
|5||20||{{ottdp|1.1|ottdrev=r19204}}||use [[Callbacks#Decide drawing default foundations (30/14E/150) |callback 150]] to decide if default foundations need to be drawn
|-
|6||40||{{ottdp|1.1|ottdrev=r19204}}||use callback xx to allow or deny autosloping below the tile (not yet implemented)
|}

Please note that callback 152 doesn't have a bit here. To use [[Callbacks#Animation control (1B/25/140/152/159) |callback 152]], simply set the wanted bits in property 11 and it will work as intended.

=== Animation information (0F) ===

The low byte specifies the number of animation frames minus one, so 00 means 1 frame, 01 means 2 frames etc. The maximum number of frames is 256, although you can have some problems if your animation exceeds FD (253) frames. The high byte must be 0 for non-looping animations and 01 for looping animations. Every other value is reserved for future use. In addition, if the whole word contains FFFF, animation is turned off for this tile (this is the default value).

=== Animation speed (10) ===

The meaning is the same as for house property 1B, but the lower limit is 0 instead of 2, so the fastest possible animation changes frames every game tick (27ms). The default value is 2.

=== Animation triggers via [[Callback:_Animation_control |callback 152]] (11) ===

This shares some flags with industry tiles and others with stations. Call [[Callback:_Animation_control|callback 152]] when:

{| |-
!Bit!!Value!!Version!!Meaning!!Var 18
|-
|0||1||{{ottdp|1.1|ottdrev=r19204}}||airport was just constructed||
|-
|1||2||{{ottdp|1.1|ottdrev=r19204}}||the tile is processed in the periodic processing loop||
|-
|2||4||{{ottdp|1.1|ottdrev=r19204}}||new cargo arrives at the station (for all airport tiles the same)||<ref name="cargotype">Bits 8..15 of var 18 contain the triggering cargo type. If your GRF has a cargo translation table, the cargo type will be an index in that table, or FFh if the cargo isn't in the table. If you don't have a cargo translation table, the cargo type will simply be the climate-dependent cargo type number.</ref>
|-
|3||8||{{ottdp|1.1|ottdrev=r19204}}||a cargo type gets removed from the station (for all airport tiles the same)||<ref name="cargotype"/>
|-
|4||10||{{ottdp|1.1|ottdrev=r19204}}||every 250 ticks (for all airport tiles the same)||
|-
|5||20||{{ottdp|1.9}}||Triggered when an airplane (not a helicopter!) lands at airport (single tile only)||
|}

<references/>

== Example ==

NML:Airports

2019-12-22T22:11:33Z

Andrew350: more clarification on new anim_trigger

{{NMLNavPropVarCB}}

Airports and airport tiles can only be defined in OpenTTD {{ottd|1.1|r19459}} or later.

==Airport (tile) IDs==
Airport and airport tile IDs are local to the NewGRF, you are free to choose any ID in the 0..255-range. For airport tiles, you should start your item definition with the 'substitute'-property, which allocates a new airport tile. The value of this property should be the ID of a [[AirportTileDefaultProps|default airport tile]], which will be used instead of your item if it is not available for whatever reason (for example, missing NewGRF).

Furthermore, you can set the 'override'-property, which will cause the existing airport tile to be replaced with your item. For airports, there only is an 'override'-property, which acts as a combined substitute and override.

==Airport properties==

{| class="t"
! name
! value range
! comment
|-
| override
|
|
{{ottd|1.1|r19459}} The id of airport to replace / override, see [[AirportTypes]]. '''This property ''must'' be set first, before any other properties or graphics.'''
|-
| layouts
| list of layouts
|
{{ottd|1.1|r20377}}
|-
| name
| string
|
{{ottd|1.1|r19459}} Name of the airport
|-
| years_available
| [start year, last year]
|
{{ottd|1.1|r19459}} List of the availablility years: first and last year it can be built
|-
| ttd_airport-type
| 0 ... 3
|
{{ottd|1.1|r19459}} Substitute TTDPatch airport type
|-
| catchment_area
|
|
{{ottd|1.1|r19459}} Catchment area of the airport in tiles around its perimeter
|-
| noise_level
|
|
{{ottd|1.1|r19459}} Noise generation of this airport
|-
| maintenance_cost
|
|
{{ottd|1.2|r23415}} Maintenance cost factor for this airport
|}

==Airport tile properties==

{| class="t"
! name
! value range
! comment
|-
| override
|
|
{{ottd|1.1|r19204}} The id of airport tile to override, see [[AirportTypes]]. '''This property ''must'' be set first, before any other properties or graphics.'''
|-
| substitute
|
|
{{ottd|1.1|r19204}} The id of airport tile to replace
|-
| callback_flags
| bitmask
|
{{ottd|1.1|r19204}} Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| animation_info
| Array [ANIMATION_XXX, frame-count]
|{{ottd|1.1|r19204}} XXX = [LOOPING <nowiki>|</nowiki> NON_LOOPING], 1..253 frames
|-
| animation_speed
|
|
{{ottd|1.1|r19204}} See [[NML:Animation speed|speed settings]]
|-
| animation_triggers
| bitmask(ANIM_TRIGGER_APT_XXX, ... )
|
{{ottd|1.1|r19204}} Bitmask of triggers that will trigger the <code style="color:darkgreen">anim_control</code> callback, see the [[#Animation triggers|table]] below.
|}

==Airport variables==

A number of variables are shared between airports and stations. These are listed on the [[NML:Stations#Base station variables|stations]] page.

{| class="t"
! name
! value range
! comment
|-
| layout
| 0 .. (number of layouts - 1)
|
{{ottd|1.1|r20364}} Layout number of the airport (index in the layouts array)
|}

==Airport tile variables==

{| class="t"
! name
! value range
! comment
|-
| terrain_type
|
|
|-
| town_radius_group
|
|
|-
| 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
|
|
|}

The following variables require a signed x,y offset as parameters. The offset is relative to the current tile. Offset 0,0 means 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_same_airport
| 1 if the tile is part of the same airport, 0 otherwise
|
|-
| 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_airporttile_id
| 0x00aa, 0xFFbb, 0xFFFE or 0xFFFF
| 0x00aa: The tile is an airport tile that is part of this GRF, the tile id is aa.<br /> 0xFFbb: The tile is an original airport tile with id bb.<br /> 0xFFFE: The tile is an airport tile defined in another GRF.<br /> 0xFFFF: The tile is not an airport tile or it belongs to another GRF.
|}

==Airport callbacks==

{| class="t"
! callback
! return value
! comment
|-
| default
| Sprite set (with 1 sprite)
| Preview graphics to use in the build menu. One sprite per layout may be given, use the <code style="color:darkgreen">layout</code> to distinguish between layouts.
|-
| additional_text
| String
| Additional text to show in the buy menu. String may differ per layout, use the <code style="color:darkgreen">layout</code> variable for this.
|-
| layout_name
| String
| Name of the airport layout in the variable <code style="color:darkgreen">layout</code>
|}

Note that, although the airport isn't built yet, the <code style="color:darkgreen">layout</code> variable is always available and set to the layout the user has selected in the GUI.

==Airport tile callbacks==

{| class="t"
! callback
! return value
! comment
|-
| default
| Sprite layout
| Graphics for an airport tile
|-
| 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. Returning a sound effect in the high byte will cause that sound effect to be played.
* <code style="color:darkgreen">extra_callback_info1</code>: 32 random bits.
|-
| 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. Returning a sound effect in the high byte will cause that sound effect to be played.
* <code style="color:darkgreen">extra_callback_info1</code>: 32 random bits.
* <code style="color:darkgreen">getbits(extra_callback_info2, 0, 8)</code>: Reason for callback trigger, 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.
|-
| foundations
| CB_RESULT[_NO]_FOUNDATIONS
| Return CB_RESULT_FOUNDATIONS to draw standard foundations (default) or CB_RESULT_NO_FOUNDATIONS to not draw them.
|}

===Animation triggers===

{| class="t"
! Animation trigger
! Description
|-
| ANIM_TRIGGER_APT_BUILT
| Airport is built (all tiles at the same time)
|-
| ANIM_TRIGGER_APT_TILELOOP
| Airport tile is processed in the tileloop (at different times for different tiles)
|-
| ANIM_TRIGGER_APT_NEW_CARGO
| New cargo arrives at the airport (all tiles at the same time)
|-
| ANIM_TRIGGER_APT_CARGO_TAKEN
| All cargo of a cargo type is removed from the airport (all tiles at the same time)
|-
| ANIM_TRIGGER_APT_250_TICKS
| Every 250 ticks (all tiles at the same time)
|-
| ANIM_TRIGGER_APT_AIRPLANE_LANDS
| {{ottd|1.9}} Triggered when an airplane (not a helicopter!) lands at airport (single tile only)
|}

NML:Airports

2019-12-22T15:55:16Z

Andrew350: /* Animation triggers */ added ANIM_TRIGGER_APT_AIRPLANE_LANDS

NML:Railtypes

2019-12-22T14:57:46Z

Andrew350: added new flags and callbacks for 1.9 / 1.10

{{NMLNavPropVarCB}}

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

==Railtype IDs==
Railtype IDs are limited to 64 in total. NewGRF-local IDs may freely be chosen, but must be in the 0..63 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.

== Vehicle and Railtype availability ==

Vehicle and railtype availability and compatibility is influenced by multiple properties.
Generally, the vehicle defines which railtype it is, and the railtypes define the compatibility between each other.
* A vehicle exists, if its railtype (train property <code style="color:green">track_type</code>) is defined. Otherwise the vehicle is disabled.
* When a vehicle is introduced, it always introduces its railtype (train property <code style="color:green">track_type</code>).
* A railtype is introduced, if at least one of the following conditions is met:
** A vehicle is introduced, that references the railtype (train property <code style="color:green">track_type</code>).
** Another railtype is introduced, that references the railtype via the introduced railtype list (railtype propery <code style="color:green">introduces_railtype_list</code>).
** The introduction date (railtype property <code style="color:green">introduction_date</code>) is passed and all required railtypes (railtype property <code style="color:green">requires_railtype_list </code>) are available.

Via railtype property <code style="color:green">compatible_railtype_list</code> multiple railtypes can be defined, which shall be considered equivalent to a railtype.
This affects the interpretation of train property <code style="color:green">track_type</code>. If train property <code style="color:green">track_type</code> references an undefined railtype, then
railtype property <code style="color:green">compatible_railtype_list</code> is checked for all defined railtypes, whether the vehicle can be reassigned to some other railtype.
Otherwise the vehicle is disabled.

==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, ...)
|
; CATENARY
: Enable catenary
; NO_LEVEL_CROSSING
: Disable level crossings
; HIDDEN {{ottd|1.9}}
: Hides railtype from player
; PRECOMBINED {{ottd|1.10}}
: Enable use of precombined overlay sprites
; ALLOW_90DEG {{ottd|1.10}}
: Always allow 90 degree turns
; DISALLOW_90DEG {{ottd|1.10}}
: Always prohibit 90 degree turns (takes precedence over ALLOW_90DEG)
|-
| curve_speed_multiplier
| 0...255
| 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
| 0 ... 255
|
{{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 of 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. Used in junctions, and also with path signals, if the "Show reserved tracks" option is enabled in the game settings.
|-
| 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 / 16
| x, y, vertical, horizontal, SW, SE, NE and NW slopes like original fences at sprite 1301. {{ottdp|1.6|no|ottdrev=r27343}} Since OpenTTD r27343 there is also a 16 sprites version, see below.
|-
| 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>getbits(extra_callback_info1, 0, 8)</code>: 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, NW, SE, E, W, S, N. For more information, see [[#signals|below]]
|-
| precombined<ref name=leftout />
| 63
| {{ottd|1.10}} 1 sprite for each combination of track on a tile. The index is determined by treating each track piece as a bit in the order X Y N S W E, subtracting 1, see [[#Precombined overlay sprites|below]]
|}

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

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

[[File:railtype_gui.png]]

==== track_overlay ====

[[File:railtype_overlay.png]]

==== underlay ====

[[File:railtype_underlay.png]]

==== level_crossings ====

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

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

[[File:railtype_levelcrossing.png]]

==== depots ====

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

==== fences ====

[[File:railtype_fences.png]]

{{ottdp|1.6|no|ottdrev=r27343}} Since OpenTTD r27343 there is also a 16 sprites version, this allows to use different sprites resp. offsets for the fences on either track side.

{| |-
! Sprite number !! Tile slope !! Track bit !! Fence position !! Version
|-
| 0 || flat || X || NW || {{ottdp|1.0|no|ottdrev=r19056}}
|-
| 1 || flat || Y || NE || {{ottdp|1.0|no|ottdrev=r19056}}
|-
| 2 || flat || left || E || {{ottdp|1.0|no|ottdrev=r19056}}
|-
| 3 || flat || upper || S || {{ottdp|1.0|no|ottdrev=r19056}}
|-
| 4 || SW || X || NW || {{ottdp|1.0|no|ottdrev=r19056}}
|-
| 5 || SE || Y || NE || {{ottdp|1.0|no|ottdrev=r19056}}
|-
| 6 || NE || X || NW || {{ottdp|1.0|no|ottdrev=r19056}}
|-
| 7 || NW || Y || NE || {{ottdp|1.0|no|ottdrev=r19056}}
|-
| 8 || flat || X || SE || {{ottdp|1.6|no|ottdrev=r27343}}
|-
| 9 || flat || Y || SW || {{ottdp|1.6|no|ottdrev=r27343}}
|-
| 10 || flat || left || W || {{ottdp|1.6|no|ottdrev=r27343}}
|-
| 11 || flat || upper || N || {{ottdp|1.6|no|ottdrev=r27343}}
|-
| 12 || SW || X || SE || {{ottdp|1.6|no|ottdrev=r27343}}
|-
| 13 || SE || Y || SW || {{ottdp|1.6|no|ottdrev=r27343}}
|-
| 14 || NE || X || SE || {{ottdp|1.6|no|ottdrev=r27343}}
|-
| 15 || NW || Y || SW || {{ottdp|1.6|no|ottdrev=r27343}}
|}

==== 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. If resolving fails or results in an empty sprite group, the matching base set sprite will be used instead.

Variable <code style:darkgreen>extra_callback_info2</code> contains the state, variant and type of the signal. Use the builtin function <code style:darkgreen>getbits()</code> in the following fashion to access the information:
<ul><li>
Signal state: <code style:darkgreen>getbits(extra_callback_info2, 0, 8)</code>:
{| |-
! Result !! Meaning
|-
| 00 || Red signal
|-
| 01 || Green signal
|-
| all other values || Reserved
|}
</li><li>
Signal variant: <code style:darkgreen>getbits(extra_callback_info2, 8, 8)</code>:
{| |-
! Result !! Meaning
|-
| 00 || Light (electric) signal
|-
| 01 || Semaphore
|-
| all other values || Reserved
|}
</li><li>
Signal type: <code style:darkgreen>getbits(extra_callback_info2, 16, 8)</code>:
{| |-
! Result !! Meaning
|-
| 00 || Normal block signal
|-
| 01 || Entry pre-signal
|-
| 02 || Exit pre-signal
|-
| 03 || Combo pre-signal
|-
| 04 || Two-way path signal
|-
| 05 || One-way path signal
|-
| all other values || Reserved
|}
</li></ul>
Variable <code style:darkgreen>extra_callback_info1</code> contains the drawing context.
<ul><li>
<code style:darkgreen>getbits(extra_callback_info1, 0, 8)</code>:
{| |-
! Result !! 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
|}
</li></ul>

====Precombined overlay sprites====

[[File:Rails_combined.png]]

===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 only have 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 tunnel 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 catenary 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:Cargos

2019-12-22T13:52:53Z

Andrew350: /* Cargo properties */ updated number of cargos available

{{NMLNavPropVarCB}}

==Cargo IDs==
For cargos, the item ID corresponds to the cargo type slot of the cargo. TTD default cargos occupy slots 0-11, so if you want to define a new cargo be sure to set this ID to 12 or higher. It is recommended to set the 'number'-property to the same value as the item ID.

==Cargo properties==

{| class="t"
! name
! value range
! comment
|-
| number
| 0..63
| Number of the cargo for bitmasks. Prior to {{ottd|1.9}} this was clamped to 0..31. This mostly affects old NewGRFs that don't have a cargo translation table.
|-
| type_name
| string
| String to use as cargo type name. Example: "Passengers". The list of [[NML:Default_TTD_strings|default TTD strings]] contains the strings used by the default cargos (TTD_STR_CARGO_PLURAL_XXX), which may be re-used.
|-
| unit_name
| string
| String to use for the name of one unit from the cargo type. Currently used for subsidies only (First Passenger service to..). Example string: "Passenger". The list of [[NML:Default_TTD_strings|default TTD strings]] contains the strings used by the default cargos (TTD_STR_CARGO_SINGULAR_XXX), which may be re-used.
|-
| units_of_cargo
| string
| String used to show the "short cargo" form for cargo units, e.g. "10 tonnes" or "20.000 litres". Example: "{COMMA} item{P "" s}". The list of [[NML:Default_TTD_strings|default TTD strings]] contains the strings used by the default cargos (TTD_STR_PASSENGERS and further), which may be re-used.
|-
| items_of_cargo
| string
| String used to show the "long cargo" form for cargo units, e.g. "10 tonnes of coal" or "20.000 litres of water". Example: "{COMMA} item{P "" s} of livestock". The list of [[NML:Default_TTD_strings|default TTD strings]] contains the strings used by the default cargos (TTD_STR_QUANTITY_XXX), which may be re-used.
|-
| type_abbreviation
| string
| String used for the two-letter cargo type abbreviation. Must start with a {TINYFONT} string-code. Example: "{TINYFONT}XX". Make sure to avoid multiple cargos having the same abbreviation. The list of [[NML:Default_TTD_strings|default TTD strings]] contains the strings used by the default cargos (TTD_STR_ABBREV_XXX), which may be re-used.
|-
| sprite
| sprite
| TTD sprite number for the icon of the cargo. Alternatively, set to NEW_CARGO_SPRITE and use a graphics block to define a custom sprite.
|-
| weight
| float 0..255
| Weight of one unit of the cargo (in tons)
|-
| penalty_lowerbound
| 0..255
| Delivery time until penalty is applied
|-
| single_penalty_length
| 0..255
| Length of the interval where a single penalty is applied
|-
| price_factor
| float
| Payment for delivering 10 units of cargo across a distance of 20 squares (in British Pounds).
|-
| station_list_colour
| 0..255
|
Colour for the station list window (index from the [[NML:Graphic files|default (DOS) palette]])
|-
| cargo_payment_list_colour
| 0..255
|
Colour for the cargo payment list window (index from the [[NML:Graphic files|default (DOS) palette]])
|-
| is_freight
| 0 or 1
| Freight status (for the freighttrains switch); 0=not freight, 1=is freight
|-
| cargo_classes
|
bitmask([[#Cargo classes|cargo classes]])
| Cargo classes
|-
| cargo_label
| 4 letters
| [[CargoTypes|Cargo label]], as used in the [[NML:Cargotable|cargo table]]
|-
| town_growth_effect
| TOWNGROWTH_XXX
|
Effect for town growth, see [[#Cargo effects on town growth|Cargo effects on town growth]]
|-
| town_growth_multiplier
| float 0..255
| Multiplier for town growth. To be used in conjuction with town_growth_effect, when that is not TOWNGROWTH_NONE. For example, a value of 4 makes your cargo have the same effect on town growth as 4 units of food/goods/etc.
|-
| callback_flags
| bitmask(flags)
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| capacity_multiplier
| float 0 .. 255
| {{ottd|1.2|r22860}} This defines the capacity of vehicles carrying this cargo type, if the vehicle sets no specific capacity to this specific cargo type. Set this property to the amount of cargo a vehicle shall carry, which can carry 1 ton of coal or 1000 thousand litres of water (whatever comparison is more suitable for your cargotype). Depending on whether your cargo type is light or heavy you should set this property either comparing the weight or the volume. Default values are 4 for passengers, 2 for mail, goods and sweets and 1 for all other cargos.
|}

Cargo payment is computed from <code style="color:darkgreen">price_factor</code>, amount of cargo transported, distance, and a time delivery factor. Unit of the delivery time is 185 ticks, roughly 2.5 days. The factor is constant (with value 255) if delivery time is less than <code style="color:darkgreen">penalty_lowerbound</code>. It goes down with rate 1 between <code style="color:darkgreen">penalty_lowerbound + single_penalty_length</code>, and goes down with rate 2 if the delivery time is even longer. Time delivery factor is never less than 31.

===Cargo classes===

Available cargo classes are listed in the following table. Cargos may be in more than one class. Cargo classes are always used as a bitmask, use the built-in function <code>bitmask()</code>. For example, <code style="color:darkgreen">bitmask(CC_EXPRESS, CC_REFRIGERATED)</code> is used for food.

{| class="t"
! name
! type of cargo
|-
| CC_PASSENGERS
| passengers, also tourists (ECS)
|-
| CC_MAIL
| mail
|-
| CC_EXPRESS
| express goods, also tourists (ECS)
|-
| CC_ARMOURED
| valuables, diamonds, gold and alike
|-
| CC_BULK
| coal, ore, grain,...
|-
| CC_PIECE_GOODS
| containers, crates, livestock
|-
| CC_LIQUID
| oil, milk, water, ...
|-
| CC_REFRIGERATED
| food, milk, ...
|-
| CC_HAZARDOUS
| chemicals?, uranium, ...
|-
| CC_COVERED
| grain, cement, fruit, ...
|-
| CC_OVERSIZED
| vehicles, ...
|-
| CC_POWDERIZED
| cement, ...
|-
| CC_NON_POURABLE<br>CC_NEO_BULK
| sugar cane, wool or straw bales, ...
|-
| CC_SPECIAL
| Special cargo, used for refit tricks. (e.g. regearing in NARS)
|-
| NO_CARGO_CLASS
| Special value that you can used to instead of 0.
|-
| ALL_NORMAL_CARGO_CLASSES
| Bitmask of all cargo classes except CC_SPECIAL. This is the same as <code style="color:darkgreen">bitmask(CC_PASSENGERS, CC_MAIL, ..., CC_OVERSIZED)</code>. Note: This is already a bitmask, don't use the <code style="color:darkgreen">bitmask(..)</code> function with this.
|-
| ALL_CARGO_CLASSES
| Bitmask of all cargo classes. Same as <code style="color:darkgreen">ALL_NORMAL_CARGO_CLASSES | bitmask(CC_SPECIAL)</code> Note: This is already a bitmask, don't use the <code style="color:darkgreen">bitmask(..)</code> function with this.
|}

===Cargo effects on town growth===

{| class="t"
! value
! effect
|-
| TOWNGROWTH_PASSENGERS
| Affect towns as passengers do
|-
| TOWNGROWTH_MAIL
| Affect towns as mail does
|-
| TOWNGROWTH_GOODS
| Affect towns as goods/candy does
|-
| TOWNGROWTH_WATER
| Affect towns as water does (second required cargo for towngrowth in the desert)
|-
| TOWNGROWTH_FOOD
| Affect towns as food/fizzy drinks do (first required cargo for towngrowth in desert/above snowline)
|-
| TOWNGROWTH_NONE
| Don't affect town growth (default)
|}

==Cargo variables==

Cargos have no variables (yet).

==Cargo callbacks==

{| class="t"
! callback
! return value
! comment
|-
| default
| Sprite set (with 1 sprite)
| Graphics for the cargo icon (only if property <code style="color:darkgreen">sprite</code> is set to NEW_CARGO_SPRITE)
|-
| station_rating
| -16384 .. 16383
| See detailed explanation below
|-
| profit
| -12748 .. 12748
| Called whenever cargo is delivered.
* <code style="color:darkgreen">getbits(extra_callback_info2, 0, 16):</code> The manhattan distance the cargo was transported.
* <code style="color:darkgreen">getbits(extra_callback_info2, 16, 8):</code> The amount of cargo delivered.
* <code style="color:darkgreen">getbits(extra_callback_info2, 24, 8):</code> The time spent en-route (1 unit = 2.5 days).
The returned value is multiplied by the amount and the <code style="color:darkgreen">price_factor</code> and then divided by 256 to determine the income the player receives. Returning negative values is possible, it makes players pay for the delivery.
|}

===Station rating callback===

The station rating callback is quite complicated and deserves some detailed explanation. The default station rating calculation works as follows:

Internally, station rating is byte with values 0 .. 255, representing respectively 0% and 100%. Every 2.5 days, the transportation 'performance' is calculated using some factors outlined below. The station rating is then set to this performance value, with the caveat that the rating change cannot exceed 2 points. Therefore, rating changes are always slow, this callback cannot change this. The initial rating is 175 points (69%). The following factors are parts of the performance, their effects are summed.

====Time since the cargo was last picked up====

{| class="t"
! Time units (days)
! Score (%, rounded)
|-
| >21 (>52.5 days)
| 0 (0%)
|-
| 13 .. 21 (32.5 days .. 52.5 days)
| 25 (10%)
|-
| 7 .. 12 (17.5 days .. 32.5 days)
| 50 (20%)
|-
| 4 .. 6 (10 days .. 17.5 days)
| 95 (37%)
|-
| 0..3 (0 days..10 days)
| 130 (51%)
|}

The time unit used equals 185 engine ticks, or 2.5 TTD days. For ships, the time units are divided by 4 before calculating this component, so ships have four times more time before the ratings start dropping.

====Amount of cargo waiting====

{| class="t"
! Amount of cargo
! Score (%, rounded)
|-
| >1500
| -90 (-35%)
|-
| 1001..1500
| -35 (-14%)
|-
| 601..1000
| 0 (0%)
|-
| 301..600
| 10 (4%)
|-
| 101..300
| 30 (12%)
|-
| 0..100
| 40 (16%)
|}

====Max. speed of the last vehicle picking up the cargo====

This calculation is somewhat complicated. The maximum speed of the vehicle is expressed in "speed units". For trains and road vehicles, the speed unit is 1 km/h; for ships, it's 0.5 km/h; for aircraft, it's 8 mph. If the max. speed is above 255 speed units, 255 is used instead. If the vehicle is slower than 85 units, no points are awarded; otherwise, you get (speed_units-85)/4 points. Therefore, the maximum you can get is 42 points, or 16%.

====Age of the last carrier picking up the cargo====

{| class="t"
! Age of vehicle (years)
! Score (%, rounded)
|-
| 2
| 10 (4%)
|-
| 1
| 20 (8%)
|-
| 0
| 33 (13%)
|}

In TTDPatch this changes when the 'newagerating' switch is enabled

====Bonus for AI companies (TTDPatch only)====

{| class="t"
! AI intelligence setting
! Score (%, rounded)
|-
| Low
| 0 (0%)
|-
| Medium
| 31 (12%)
|-
| High
| 63 (25%)
|}

====Bonus for statue in nearest town====

If your company has erected a statue in the nearest town, you get 26 points (10%) bonus to all cargo ratings.

====Callback parameters====

<ul><li>
<code style="color:darkgreen">getbits(extra_callback_info1, 0, 8)</code>:
{| |-
!value!!meaning
|-
|0x10||the last vehicle entering the station was a train
|-
|0x11||the last vehicle entering the station was a road vehicle
|-
|0x12||the last vehicle entering the station was a ship
|-
|0x13||the last vehicle entering the station was an aircraft
|-
|0||no vehicle entered the station yet, or (TTDPatch) the last one entering was sold
|}
Please note that there's only one "last vehicle type" field per station, so the vehicle this refers to may not have picked up any of your cargo.
</li><li>
<code style="color:darkgreen">getbits(extra_callback_info2, 0, 8)</code>: The time since the cargo was last picked up, in the time units described above (1 unit = 2.5 days independent of vehicle type)
</li><li>
<code style="color:darkgreen">getbits(extra_callback_info2, 8, 16)</code>: The amount of cargo waiting.
</li><li>
<code style="color:darkgreen">getbits(extra_callback_info2, 24, 8)</code>: The speed of the last vehicle picking the cargo up, in the speed units described above (if no vehicle entered the station yet, the value is 0xFF).
</li></ul>

====Effect of callback====

The return value of the callback replaces the first three components (time since pickup, amount of cargo, max speed) of the calculation. The bonus for statues, TTDPatch AIs and new vehicles is always in effect, you cannot (yet) change this.

NML:Builtin functions

2019-12-22T13:25:59Z

Andrew350: updated number of permanent storage registers

{{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). Since {{ottd|1.9}} up to 256 registers are available. 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
|-
| getbits(''value'', ''first'', ''amount'')
| {{nml|0.4.1}} Extract some bits from a value. Result is (value >> first) & (1 << amount - 1)
|-
| 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.
|-
| create_effect(''effect_sprite'', ''l_x_offset'', ''t_y_offset'', ''z_offset'')
| Helper function for the vehicle callback 'create_effect'.
* ''effect_sprite'': Sprite for the effect. One of EFFECT_SPRITE_[NONE|STEAM|DIESEL|ELECTRIC|AIRCRAFT_BREAKDOWN_SMOKE].
* ''l_x_offset'': Longitudinal or X position of the effect, depending on callback result CB_RESULT_CREATE_EFFECT_NO_ROTATION.
* ''t_y_offset'': Transversal or Y position of the effect, depending on callback result CB_RESULT_CREATE_EFFECT_NO_ROTATION.
* ''z_offset'': Z position of the effect.
|-
| 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 in WAV format, PCM encoding:
* mono
* 8-bit or {{ottdp|1.0|no}} 16-bit
* 11025 Hz, 22050 Hz or 44100 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 [[NML:List_of_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 [[NML:List_of_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.
|}

GlobalVariables

2019-12-22T13:12:34Z

Andrew350: /* OpenTTD Version (21 / A1) */ fixed typo

== Overview ==
{|
!colspan=3|'''Variable'''
!rowspan=2|[[GRFActionsDetailed|'''Size''']]
!rowspan=2|'''Versions'''
!rowspan=2|'''Description'''
|-
|[[VariationalAction2 | VA2]]||A[[Action6|6]]/[[Action7|7]]/[[Action9|9]]/[[ActionD|D]]<br>(read)||[[ActionD|ActD]]<br>(write)
|-
|00||80|| ||W||{{ottdp|0.6|2.0}}||current date (counted as days from 1920)<ref name="startdate">{{ottdp|0.7}} In multiplayer games OpenTTD doesn't report the current date and year to actions 6,7,9 and D, but the date and year the game was loaded. The reason lies in the fact that it was seen that use of this variable leads to desyncs in network games.</ref>
|-
|01||81|| ||B||{{ottdp|0.6|2.0}}|| Current year (count from 1920, max. 2175 even with eternalgame)<ref name="startdate"/>
|-
|02||82|| ||B/D||{{ottdp|0.6|2.0}}|| current month (0-11) in bits 0-7; the higher bytes contain unusable junk.<ref name="startdate"/><br/>{{ottdp|0.7|ottdrev=r13594}} Since OpenTTD r13594 'day of month' (0-30) is stored in bits 8-12, bit 15 is set in leapyears and 'day of year'(0-364 resp. 365) is stored in bits 16-24. All other bits are reserved and should be masked.
|-
|03||83|| ||B||{{ottdp|0.6|2.0}}|| Current climate: 00 = temp, 01 = arctic, 02 = trop, 03 = toyland
|-
| ||84|| ||D||{{ottdp|0.6|2.0}}|| [[GrfLoadingStages|GRF loading stage]], see [[#GRF_Loading_stage_.28-_.2F_84.29|below]]
|-
| ||85|| ||B||{{ottdp|0.6|2.0}}|| [[TTDPatchFlags|TTDPatch flags]]: only for bit tests
|-
|06||86|| ||B||{{ottdp|0.6|2.0}}|| Road traffic side: bit 4 clear=left, set=right; other bits are reserved and must be masked.
|-
| ||(87)||(87)||B||{{ottdp|no|no}}|| No longer used since TTDPatch 2.0. (was width of "€" character)
|-
| ||88|| ||4*B||{{ottdp|0.6|2.0}}|| Checks specified GRFID (see [[Action7#condition-type|condition-types]])<ref>The value of variable 88 can only be tested with the GRFID tests.</ref>
|-
|09||89|| ||W||{{ottdp|0.6|2.0}}|| date fraction, incremented by 0x375 every engine tick
|-
|0A||8A|| ||W||{{ottdp|0.6|2.0}}|| animation counter, incremented every tick
|-
|0B||8B|| ||D||{{ottdp|no|2.0}}|| [[Version_numbers#TTDPatch_version|TTDPatch version]], see [[#TTDPatch_Version_.280B_.2F_8B.29|below]] <ref>OpenTTD reports some arbitrary TTDPatch 2.6 version number to make old GRFs work, which do not know about OpenTTD. Do not rely on this for new NewGRFs.</ref><ref name="versionchecks">It is generally not useful to check version variables using Action 7. If you want to skip certain actions which are incompatible to some versions, you want to skip them during all loading stages. So, use Action 9.</ref>
|-
|0C|| || ||W||{{ottdp|0.6|2.5}}|| current [[Callbacks|callback]] ID (feature-specific), set to 00 when not in a callback
|-
|0D||8D|| ||B||{{ottdp|0.6|2.5}}|| TTD version, 0=DOS, 1=Windows
|-
|0E||8E||8E||B||{{ottdp|0.6|2.5}}|| Y-Offset for train sprites
|-
|0F||8F||8F||3*B||{{ottdp|0.6|2.5}}|| Rail track type cost factors
|-
|10|| || ||D||{{ottdp|0.6|2.5}}|| Extra callback info 1, see [[#Extra_callback_info_.2810_.2F_-.29_and_.2818_.2F_-.29|below]].
|-
|11|| || ||B||{{ottdp|no|2.5}}|| current rail tool type (for station callbacks)
|-
|12||92|| ||B||{{ottdp|0.6|2.5}}|| Game mode, 0 in title screen, 1 in game and 2 in editor
|-
|13||93||93||W||{{ottdp|no|2.5|ttdprev=2.0.1 alpha 39}}|| Tile refresh offset to left <ref name="tilefresh">See [[ActionD#Tile+refresh+offsets|Action D]] for more details on tile refresh offsets and their use.</ref>
|-
|14||94||94||W||{{ottdp|no|2.5|ttdprev=2.0.1 alpha 39}}|| Tile refresh offset to right <ref name="tilefresh"/>
|-
|15||95||95||W||{{ottdp|no|2.5|ttdprev=2.0.1 alpha 39}}|| Tile refresh offset upwards <ref name="tilefresh"/>
|-
|16||96||96||W||{{ottdp|no|2.5|ttdprev=2.0.1 alpha 39}}|| Tile refresh offset downwards <ref name="tilefresh"/>
|-
| ||97||97||B||{{ottdp|no|2.5}}|| Fixed snow line height <ref>This variable is a deprecated way to set the snow line height via NewGRFs using [[ActionD]]. It is superseded by the [[Action0/Global Settings#Snow_line_height_table_.2810.29 | Action 0 snow line height table]]. To read the current snow line with [[VariationalAction2 | VarAct2]] in a running game, use variable 20 instead.</ref><ref name="heightlevel">{{grfTill|7}} For GRF version 7 and below these variable are multiples of 8; {{grfFrom|8}} for GRF version 8 and above they directly state the heightlevel as multiple of 1.</ref>
|-
|18|| || ||D||{{ottdp|0.6|2.5}}|| Extra callback info 2, see [[#Extra_callback_info_.2810_.2F_-.29_and_.2818_.2F_-.29|below]].
|-
| ||99||99||D||{{ottdp|no|2.5}}|| Global ID offset
|-
|1A||9A|| ||D||{{ottdp|0.6|2.5}}|| Has always all bits set; you can use this to make unconditional jumps
|-
|1B|| || ||B||{{ottdp|no|2.5}}|| display options; bit 0=town names, 1=station names, 2=signs, 3=animation, 4=transparency, 5=full detail
|-
|1C|| || ||D||{{ottdp|0.6|2.5}}|| result from most recent VarAction2
|-
|1D||9D|| ||D||{{ottdp|0.6|2.5}}|| TTD Platform, 0=TTDPatch, 1=OpenTTD <ref name="versionchecks"/>
|-
|1E||9E||9E||D||{{ottdp|0.6|2.5}}|| Misc. GRF Features
|-
| || ||9F||D||{{ottdp|no|2.5}}|| writable only: Locale-dependent settings
|-
|20|| || ||B||{{ottdp|0.6|2.5}}|| Current snow line height, FFh if snow isn't present at all <ref name="heightlevel"/>
|-
|21||A1|| ||D||{{ottdp|0.6|no}}|| [[Version_numbers#OpenTTD_version|OpenTTD version]], see [[#OpenTTD_Version_.2821_.2F_A1.29|below]]. <ref name="versionchecks"/>
|-
|22||A2|| ||D||{{ottdp|0.7|2.6|ottdrev=r12499|ttdprev=r1857}}|| Difficulty level: 00= easy, 01=medium, 02=hard, 03=custom
|-
|23||A3|| ||D||{{ottdp|0.7|2.6|ottdrev=r13376|ttdpref=r2048}}|| Current date long format
|-
|24||A4|| ||D|||{{ottdp|0.7|2.6|ottdrev=r13376|ttdprev=r2048}}|| Current year zero based
|-
|25|| || ||D||{{ottdp|0.7|ottdrev=r15739}}|| GRFID of the grf that contains the corresponding Action3. Useful when accessing the "related" object. Currently only supported for vehicles.
|}

All other variable numbers are reserved and must not be used.

<references/>

== Special variables ==

=== GRF Loading stage (- / 84) ===

Variable 84 is a BYTE variable up to TTDPatch 2.5r1220. Its lower byte (bits 0..7) are 0 for the post-load and GRF initialization stages and 01 for all other stages. The remaining bits are a bitmask, and including the lower byte have the following meaning:
{|
!Bit!!Version!!Meaning
|-
|0||{{ottdp|0.6|2.0}}||Set after the "Initialization" stage completes
|-
|1..7||{{ottdp|0.6|2.0}}||Always clear
|-
|8||{{ottdp|0.6|2.5|ttdprev=r1220}}||Set during the "Reserve" stage only
|-
|9||{{ottdp|0.6|2.5|ttdprev=r1220}}||Set during the "Activate" stage only
|-
|10||{{ottdp|0.6|2.5|ttdprev=r1220}}||Set during the "Test" stage only
|-
|11..15|| || Reserved. Do not test for them.
|}

=== TTDPatch Version (0B / 8B) ===
Variable 8B has the following format: MMmrbbbb (though encoded in little endian as bb bb mr MM)
{|
!Element!!Meaning!!Value
|-
|MM||major||First number of the [[Version_numbers#TTDPatch_version|TTDPatch version]]
|-
|m||minor||Second number of the TTDPatch version
|-
|r||revision||Third number of the TTDPatch version<ref name="rev">For TTDPatch 2.0, r=7 and for TTDPatch 2.0.1 series, r=10 due to an oversight which used r=1..4 for TTDPatch 2.0 beta 1..4.</ref>
|-
|bbbb||build||Alpha/beta version number times ten (up to an including TTDPatch 2.5 beta 5), SVN revision (from TTDPatch 2.5 beta 5 r418 on)
|}

Examples
{|
!Version!!Variable 8B!!Elements
|-
|1.9.1 alpha 50||019101F4|| MM=01, m=9, r=1, bbbb=50*10=01F4
|-
|2.0 beta 4||02040028||MM=02, m=0, r=4<ref name="rev"/>, bbbb=4*10=0028
|-
|2.0 final||02070046||MM=02, m=0, r=7<ref name="rev"/>, bbbb=70=0046
|-
|2.0 rev 1||02070050||MM=02, m=0, r=7<ref name="rev"/>, bbbb=80=0050
|-
|2.0.1 alpha 3||020A001E||MM=02, m=0, r=10<ref name="rev"/>, bbbb=3*10=001E
|-
|2.5 beta 2||02500014||MM=02, m=5, r=0, bbbb=2*10=0014
|-
|2.5 rev631||02500631||MM=02, m=5, r=0, bbbb=631=0631
|}

<references/>

To detect versions from TTDPatch 2.5 rev419 and up correctly, check that var. 8B is 02500419 or higher, or replace 0419 with the actual required revision (using the revision number as hex digits). Because SVN revisions are shared with other patch branches, it is important to check the actual patch version as well as the SVN revision.

=== Y-Offset for train sprites (0E / 8E) ===

Since train sprites must normally have the same offsets on the map and in the depot view, they will appear either too low on the map or too high in the depot view. This variable moves all vehicles in the depot view down by this many pixels.

{{ottdp|1.0|no|ottdrev=r16867}} Since OpenTTD r16867 this variable works per grf file, that is: It only affects trains defined in the same grf.

=== Rail track type cost factors (0F / 8F) ===

This variable is a collection of three bytes that are used as multipliers for track costs when the "trackcostdiff" switch is on. The value of 08 is the baseline value that is used by standard TTD.

The defaults are the following:

{|
!Values!!Track types!!Electrified railways setting

|-
|08, 10, 18||Regular, Monorail, Maglev||off

|-
|08, 0D, 10||Regular, Electric, Monorail/Maglev||on
|}

=== Extra callback info (10 / -) and (18 / -) ===
These variables have callback specific meanings. They are described along the individual [[callbacks]].

Additionally they are used outside of callbacks for these special purposes:
{| |-
! [[Features|Feature]] !! Usage
|-
| Vehicles || Used to distinguish drawing of vehicles in the GUI or on the map. See [[Action2/Vehicles#Introduction|Action2]].
|-
| Stations || Used to compose station tiles with sprites from different Action-1-2-3 chains, or to draw custom foundations. See [[Action0/Stations#General_Flags_.2813.29|General station flags]] and [[AdvancedSpriteLayout]].
|-
| Railtypes || Used to distinguish between the type of tunnel portal or signal requested. See [[Action3/Railtypes#Tunnel_portal_overlay_.280A.29|Railtype tunnel portal overlay]] or [[Action3/Railtypes#Signal_sprites_.280B.29|Railtype signal sprites]] for details, respectively.
|}

=== Tile refresh offsets (13,14,15,16 / 93,94,95,96) ===

These four variables belong to an experimental TTDPatch feature. However, their definition is based on an incomplete understanding of the drawing algorithm in TTD, so they actually do not achieve what they were meant to do. Consider this historic content.

{{ottdp|no|2.5|ttdprev=2.0.1 alpha 39}}

''These four offsets define the size and position of the rectangle refreshed when TTD decides to refresh a tile. The basis of the calculations is the pixel coordinate of the north corner of the tile.''

''After calculating it, TTD subtracts offset_left from it to get the x coordinate of the left edge, adds offset_right to get the x coordinate of the right edge, subtracts offset_up to get the y coordinate of the top edge and adds offset_down to get the y coordinate of the bottom edge. This results in refreshing (offset_left+offset_right)*(offset_up+offset_down) pixels. The default values of these variables are 31, 36, 122 and 32, respectively.''

''Reading these values is not too useful, but you can modify them using action D as well, so your sprites that would exceed the original limits can still be redrawn and animated properly. Please note that TTD uses these values for every tile, so specifying too high values may slow the game down. Please also note that these variables are specified as dwords for technical reasons, but only the bottom word will be used.''

''Since these values are global to the entire game, you shouldn't just overwrite them with an action D. Instead, you should first check if they're big enough for you by using action 7, and skip your action D if they are. This way, the variables will be set to the maximal value needed, not just the value needed for the last grf in the list.''

=== Snow line height (- / 97) ===

This is only active if the tempsnowline switch is on. It defaults to FF (no snow) and 38 (GRF version < 8) resp. 07 (GRF version >= 8) in the temperate and arctic climates, respectively.

{{grfTill|7}} For GRF version 7 and below it must be set to a multiple of 8, which is one level of height difference.

{{grfFrom|8}} For GRF version 8 and above the heightlevel is set directly as multiple of 1.

=== Global ID offset (- / 99) ===

Setting this variable will add the given value to all the relevant IDs in subsequent action 0, action 3 (''except'' livery overrides), action 4 (''except'' generic texts) and action A entries. This is a more convenient way of applying the result of a GRF resource request. Setting this variable applies only to the current .grf file only.

In detail, it affects the following elements:

{|
!Action!!Element modified

|-
|0||<tt><Id></tt> (i.e., not property numbers)

|-
|3||<tt><Ids...></tt> (i.e., not cargo types or cargo IDs, also not for livery overrides)

|-
|4||<tt><Offset></tt> (not for generic texts, though)

|-
|A||<tt><First-sprite></tt>
|}

=== Display options (1B / -) ===
The definition of variable 1B is slightly feature-dependent. For features that can be drawn transparently (stations, bridges, houses, industry tiles and objects) bit 4 is set if the current feature will be drawn normally, and clear if the current feature will be drawn transparently. For these purposes, airports are stations. For all other features, bit 4 is undefined.

=== Misc. GRF Features (1E / 9E) ===

This variable is a global bit mask of various patch features a grf file can enable. Please only set the bits using operation 08 (bitwise OR), or, if absolutely necessary, remove certain bits with operation 07 (bitwise AND). This ensures that you don't mess up the settings of other grf files.

{|
!Bit!!Value!!Version!!Feature

|-
|0||1||{{ottdp|no|2.5}}||Allow trees and fields in the desert
|-
|1||2||{{ottdp|0.6|2.5}}||Show pavement and lights in desert towns
|-
|2||4||{{ottdp|no|2.5}}||Fields have a height, using a 3D bounding box
|-
|3||8||{{ottdp|0.6|2.5}}||Display train vehicles with full width of 32 pixels in depot window (instead of 29 pixels)<ref>Since {{ottdp|1.0|no|ottdrev=r16867}} this flag works per grf file, that is: It only affects trains defined in the same GRF.</ref>
|-
|4||10||{{ottdp|1.2|2.6|ottdrev=r23114|ttdprev=r821}}||Enable ambient sound effect callback 144
|-
|5||20||{{ottdp|no|2.5/2.6|ttdprev=r1439, will be in yet unreleased 2.5 beta 10}}||Enable catenaries over the third track type (only with electrifiedrailway on)
|-
|6||40||{{ottdp|1.5|no|ottdrev=r27200}}||Enable usage of the second rocky tile set. (sprites 4042 to 4061)
|-
|31||80000000||{{ottdp|no|2.5}}||Only to be set by ttdpbase(w).grf for identification
|}

Remarks:
<references />

Example code for setting bit 3:

24 * 9 0D 9E 08 9E FF 08 00 00 00

(Here, the first 08 indicates the bitwise OR operation, and 08 00 00 00 is the value to OR var.9E with.)

=== Locale-dependent settings (1F / 9F) ===

This variable is a doubleword in the format rrccmmll, where the meaning of the bytes is:

{|
!Byte!!Meaning

|-
|rr||Reserved for future use, just put zero here for now

|-
|cc||Default currency to be used when the game is first started. It can be larger than 5 to select one of the currencies added via morecurrencies. If this value is larger than 5 while morecurrencies is disabled, US dollars will be used instead.

|-
|mm||Default measurement system to be used when the game is first started. 00h means the imperial system (miles), 01h means the metric system (kilometers), other values are forbidden.

|-
|ll||Language ID. By setting this byte, you can override the default language ID and allow other GRFs to supply correctly localized texts. (The other GRF can check for this value in action 4s)
|}

Reading this variable isn't reliable, so you must only write to it. Please also note that the cc and mm parts are considered only while loading the title screen for the first time, changing them later is ignored.

'''NOTE''': This variable is reset after the initialization stage. Only changes during the activation stage are considered. This way, GRFs disabled in newgrf.cfg won't change the language and/or default settings. If you want to modify the cc or mm part, make sure the corresponding action D isn't skipped by an earlier action 7 or 9. In particular, if your GRF isn't available for the tropic climate, make sure you set variable 9F before the climate check, since the default title screen is tropic, and your climate check will fail on it.

=== OpenTTD Version (21 / A1) ===
Variable A1 has the following format: Mmrbbbbb (though encoded in little endian as bb bb rb Mm). This variable has only a usefull meaning when variable 9D is 1 (OpenTTD). This variable can be used since OpenTTD r11330.
{|
!Element!!Meaning!!Value
|-
|M||major||First number of the [[Version_numbers#OpenTTD_version|OpenTTD version]]
|-
|m||minor||Second number of the OpenTTD version
|-
|r||revision||Third number of the OpenTTD version
|-
|bbbbb||build||Stable releases have 80000h set.
{{ottd|≤1.8}} When OpenTTD was versioned using SVN the lower bits contained the SVN revision. Since OpenTTD 1.9 these bits are unused.
|}

The presence of 80000h (bit 19 set) means that a release always has a higher version number than any builds leading to that release.

Examples
{|
!Version!!Variable A1!!Elements
|-
|0.6.0 r11330||06002C42||M=0, m=6, r=0, bbbbb=11330=2C42
|-
|0.6.0 (release)||06080000||M=0, m=6, r=0, bbbbb=0=80000 (due to release)
|}

NML:Railtypes

2019-12-22T12:40:48Z

Andrew350: updated for 64 railtypes and fixed a few typos

{{NMLNavPropVarCB}}

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

==Railtype IDs==
Railtype IDs are limited to 64 in total. NewGRF-local IDs may freely be chosen, but must be in the 0..63 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.

== Vehicle and Railtype availability ==

Vehicle and railtype availability and compatibility is influenced by multiple properties.
Generally, the vehicle defines which railtype it is, and the railtypes define the compatibility between each other.
* A vehicle exists, if its railtype (train property <code style="color:green">track_type</code>) is defined. Otherwise the vehicle is disabled.
* When a vehicle is introduced, it always introduces its railtype (train property <code style="color:green">track_type</code>).
* A railtype is introduced, if at least one of the following conditions is met:
** A vehicle is introduced, that references the railtype (train property <code style="color:green">track_type</code>).
** Another railtype is introduced, that references the railtype via the introduced railtype list (railtype propery <code style="color:green">introduces_railtype_list</code>).
** The introduction date (railtype property <code style="color:green">introduction_date</code>) is passed and all required railtypes (railtype property <code style="color:green">requires_railtype_list </code>) are available.

Via railtype property <code style="color:green">compatible_railtype_list</code> multiple railtypes can be defined, which shall be considered equivalent to a railtype.
This affects the interpretation of train property <code style="color:green">track_type</code>. If train property <code style="color:green">track_type</code> references an undefined railtype, then
railtype property <code style="color:green">compatible_railtype_list</code> is checked for all defined railtypes, whether the vehicle can be reassigned to some other railtype.
Otherwise the vehicle is disabled.

==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...255
| 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
| 0 ... 255
|
{{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 of 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. Used in junctions, and also with path signals, if the "Show reserved tracks" option is enabled in the game settings.
|-
| 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 / 16
| x, y, vertical, horizontal, SW, SE, NE and NW slopes like original fences at sprite 1301. {{ottdp|1.6|no|ottdrev=r27343}} Since OpenTTD r27343 there is also a 16 sprites version, see below.
|-
| 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>getbits(extra_callback_info1, 0, 8)</code>: 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, NW, SE, E, W, S, N. For more information, see [[#signals|below]]
|}

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

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

[[File:railtype_gui.png]]

==== track_overlay ====

[[File:railtype_overlay.png]]

==== underlay ====

[[File:railtype_underlay.png]]

==== level_crossings ====

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

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

[[File:railtype_levelcrossing.png]]

==== depots ====

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

==== fences ====

[[File:railtype_fences.png]]

{{ottdp|1.6|no|ottdrev=r27343}} Since OpenTTD r27343 there is also a 16 sprites version, this allows to use different sprites resp. offsets for the fences on either track side.

{| |-
! Sprite number !! Tile slope !! Track bit !! Fence position !! Version
|-
| 0 || flat || X || NW || {{ottdp|1.0|no|ottdrev=r19056}}
|-
| 1 || flat || Y || NE || {{ottdp|1.0|no|ottdrev=r19056}}
|-
| 2 || flat || left || E || {{ottdp|1.0|no|ottdrev=r19056}}
|-
| 3 || flat || upper || S || {{ottdp|1.0|no|ottdrev=r19056}}
|-
| 4 || SW || X || NW || {{ottdp|1.0|no|ottdrev=r19056}}
|-
| 5 || SE || Y || NE || {{ottdp|1.0|no|ottdrev=r19056}}
|-
| 6 || NE || X || NW || {{ottdp|1.0|no|ottdrev=r19056}}
|-
| 7 || NW || Y || NE || {{ottdp|1.0|no|ottdrev=r19056}}
|-
| 8 || flat || X || SE || {{ottdp|1.6|no|ottdrev=r27343}}
|-
| 9 || flat || Y || SW || {{ottdp|1.6|no|ottdrev=r27343}}
|-
| 10 || flat || left || W || {{ottdp|1.6|no|ottdrev=r27343}}
|-
| 11 || flat || upper || N || {{ottdp|1.6|no|ottdrev=r27343}}
|-
| 12 || SW || X || SE || {{ottdp|1.6|no|ottdrev=r27343}}
|-
| 13 || SE || Y || SW || {{ottdp|1.6|no|ottdrev=r27343}}
|-
| 14 || NE || X || SE || {{ottdp|1.6|no|ottdrev=r27343}}
|-
| 15 || NW || Y || SW || {{ottdp|1.6|no|ottdrev=r27343}}
|}

==== 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. If resolving fails or results in an empty sprite group, the matching base set sprite will be used instead.

Variable <code style:darkgreen>extra_callback_info2</code> contains the state, variant and type of the signal. Use the builtin function <code style:darkgreen>getbits()</code> in the following fashion to access the information:
<ul><li>
Signal state: <code style:darkgreen>getbits(extra_callback_info2, 0, 8)</code>:
{| |-
! Result !! Meaning
|-
| 00 || Red signal
|-
| 01 || Green signal
|-
| all other values || Reserved
|}
</li><li>
Signal variant: <code style:darkgreen>getbits(extra_callback_info2, 8, 8)</code>:
{| |-
! Result !! Meaning
|-
| 00 || Light (electric) signal
|-
| 01 || Semaphore
|-
| all other values || Reserved
|}
</li><li>
Signal type: <code style:darkgreen>getbits(extra_callback_info2, 16, 8)</code>:
{| |-
! Result !! Meaning
|-
| 00 || Normal block signal
|-
| 01 || Entry pre-signal
|-
| 02 || Exit pre-signal
|-
| 03 || Combo pre-signal
|-
| 04 || Two-way path signal
|-
| 05 || One-way path signal
|-
| all other values || Reserved
|}
</li></ul>
Variable <code style:darkgreen>extra_callback_info1</code> contains the drawing context.
<ul><li>
<code style:darkgreen>getbits(extra_callback_info1, 0, 8)</code>:
{| |-
! Result !! 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
|}
</li></ul>

===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 only have 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 tunnel 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 catenary 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:Tramtypes

2019-12-22T12:25:03Z

Andrew350: added two tramtype_flags

{{NMLNavPropVarCB}}

Tramtypes can only be defined in OpenTTD {{ottd|1.10}} or later.

==Tramtype IDs==
Tramtypes and Roadtypes share a pool of 64 IDs. Either feature can use as many IDs as needed (i.e. it is not limited to 32 per type), but both features combined are limited to 64 in total. NewGRF-local IDs may freely be chosen, but must be in the 0..63 range. If other tramtype/tramtype GRFs are loaded, it may be that there are not enough 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 (tramtype_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 tramtypes.

== 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.
* Remember that the road vehicle flag 'ROADVEH_FLAG_TRAM' must be set in order for a road vehicle to be considered a tram.
* A vehicle exists, if its tramtype (tram vehicle property <code style="color:green">track_type</code>) is defined. Otherwise the vehicle is disabled.
* When a vehicle is introduced, it always introduces its tramtype (tram vehicle property <code style="color:green">track_type</code>).
* A tramtype is introduced, if at least one of the following conditions is met:
** A vehicle is introduced, that references the tramtype (tram vehicle property <code style="color:green">track_type</code>).
** Another tramtype is introduced, that references the tramtype via the introduced tramtype list (tramtype property <code style="color:green">introduces_tramtype_list</code>).
** The introduction date (tramtype property <code style="color:green">introduction_date</code>) is passed and all required tramtypes (tramtype property <code style="color:green">requires_tramtype_list </code>) are available.

Via tramtype property <code style="color:green">powered_tramtype_list</code> multiple tramtypes can be defined, which shall be considered equivalent to a tramtype.
This affects the interpretation of tram vehicle property <code style="color:green">track_type</code>. If tram vehicle property <code style="color:green">track_type</code> references an undefined tramtype, then
tramtype property <code style="color:green">powered_tramtype_list</code> is checked for all defined tramtypes, whether the vehicle can be reassigned to some other tramtype.
Otherwise the vehicle is disabled.

==Tramtype properties==

{| class="t"
! property
! value range
! comment
|-
| label
| 4-byte string
| names of default tram types: "RAIL" and "ELRL". See the [[TramtypeLabels|List of tramtype labels]] in the NewGRF Specs for currently defined custom labels.
|-
| introduction_date
| date(yyyy,mm,dd)
| Valid range for yyyy is 0 ... 5000000.
|-
| name
| string
| Name of this tramtype
|-
| toolbar_caption
| string
| Caption of the build tram toolbar. In earlier versions this is the same as the 'name'
|-
| menu_text
| string
| Shown in the dropdown menu for all tramtypes
|-
| 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 <tram type> engine" news message
|-
| powered_tramtype_list
| list of tramtype labels
| Provide a list of tram types that tram vehicles of this type are powered on, e.g. ["RAIL", "ELRL"]. Note that there is no difference between "powered" and "compatible" for tramtypes
|-
| tramtype_flags
| bitmask(TRAMTYPE_FLAG_XXX, ...)
|
;CATENARY
:Enable catenary
;NO_LEVEL_CROSSING
:Disable level crossings
;NO_HOUSES
:Disallows house construction
;HIDDEN
:Hides the tramtype from players, but remains available to towns
;TOWN_BUILD
:Towns don't build tramtracks...so what does this do???
|-
| construction_cost
| 0 ... 65525
| Per piece of track as multiplier to PR_BUILD_ROAD base cost. Default cost factors are 8 and 16 for RAIL and ELRL, respectively.
|-
| speed_limit
| 0 ... 65525 km/h (speed units)
| A speed limit of 0 means unlimited speed
|-
| map_colour
| 0 ... 255
| Entry in the colour palette.
|-
| requires_tramtype_list
| list of tramtype labels
| List of tram types 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.
|-
| introduces_tramtype_list
| list of tramtype labels
| 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.
|-
| sort_order
| 0 ... 255
| Number which defines the sort order among tram types. If this entry is not defined, it gets assigned sort order n*10+7 for the n-th tramtype.
|-
| maintenance_cost
| 0 ... 255
| Maintenance cost factor for each piece of tram of this tramtype. Default cost factors are 16 and 24 for RAIL and ELRL, respectively.
|-
| alternative_tramtype_list
| list of tramtype labels
| List of tram types which this tram type will act as fallback for, if the corresponding tram type is not defined separately
|}

===Sort order===

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

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

==Tramtype variables==

{| class="t"
! name
! value range
! comment
|-
| terrain_type
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|
|-
| 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
|-
| random_bits
|
| 2 pseudo random bits
|}

==Tramtype callbacks==

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

{| class="t"
! callbacks
! number of sprites
! meaning
|-
| gui
| 12
| 6 gui icons, 6 cursors
|-
| track_overlay<ref name=leftout>Either all or none of these sprites should be provided.</ref>
| 19
| 11 track combinations, 4 slopes, and 4 dead ends. These sprites are required
|-
| underlay<ref name=leftout />
| 19
| 11 track combinations, 4 slopes, and 4 dead ends. These sprites are required
|-
| tunnels<ref name=leftout />
| 4
| 1 sprite for each direction. Sprite is overlay for tram in existing tunnel graphics. The original ground sprite is drawn, then the overlay, then possibly a tram vehicle and the original tunnel head is drawn over the top. This keeps compatibility with different landscape types. Sprite order: SW, NW, NE, SE.
|-
| catenary_front
| 29
| 11 track combinations, 4 slopes, 4 dead ends, 4 tunnels, 2 bridge middle, 4 bridge ramps
|-
| catenary_back
| 29
| 11 track combinations, 4 slopes, 4 dead ends, 4 tunnels (unused), 2 bridge middle, 4 bridge ramps
|-
| bridge_surfaces<ref name=leftout />
| 6
| 2 bridge middle, 4 bridge ramps
|-
| depots
| 6
| If not present, the default depot sprites (depending on catenary flag) plus track overlay are drawn.
If present, the depot sprites are expected to include track overlay graphics.

|}

<references />
Note that there is no "default graphics" callback.

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

[[File:Nrt_gui.png]]

==== underlay ====

[[File:Nrt_underlay.png]]

==== overlay ====

[[File:Nrt_overlay.png]]

==== catenary_front ====

[[File:Nrt_catenary_front.png]]

==== catenary_back ====

[[File:Nrt_catenary_back.png]]

==== depots ====

[[File:Nrt_depot.png]]

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

==== bridge_surfaces ====

[[File:Nrt_bridge.png]]


===Example code===

A typical implementation for tramtypes can look like:

<pre style="color:blue">
item(FEAT_TRAMTYPES, dctram, 0x01) {
property {
label: "DCTM";
name: string(STR_DC_TRAM);
menu_text: string(STR_DC_TRAM);
build_window_caption: string(STR_BUILD_CAPTION);
autoreplace_text: string(STR_AUTOREPLACE);
new_engine_text: string(STR_NEW_ENGINE);
powered_tramtype_list: ["DCTM","ELRL"]; // These trams are compatible with other electric trams
tramtype_flags: bitmask(TRAMTYPE_FLAG_CATENARY); // These tramways require catenary
construction_cost: 24; // Electric tramways are pricey
speed_limit: 50 km/h;
}
graphics {
underlay: ground_switch_underlay; // defines the tramtrack underlay
overlay: track_overlay_switch; // defines the tramtrack overlay
tunnels: tunnel_switch; // defines the track drawn on a tunnel tile
depots: depot_switch; // defines the depot sprites
bridge_surfaces: bridge_terrain_switch; // defines the overlay drawn over bridges depending on climate
}
}
</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:Roadtypes

2019-12-22T12:19:54Z

Andrew350: added two roadtype_flags

{{NMLNavPropVarCB}}

Roadtypes can only be defined in OpenTTD {{ottd|1.10}} or later.

==Roadtype IDs==
Roadtypes and Tramtypes share a pool of 64 IDs. Either feature can use as many IDs as needed (i.e. it is not limited to 32 per type), but both features combined are limited to 64 in total. NewGRF-local IDs may freely be chosen, but must be in the 0..63 range. If other roadtype/tramtype GRFs are loaded, it may be that there are not enough 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 (roadtype_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 roadtypes.

== 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 property <code style="color:green">track_type</code>) is defined. Otherwise the vehicle is disabled.
* When a vehicle is introduced, it always introduces its roadtype (road vehicle property <code style="color:green">track_type</code>).
* A roadtype is introduced, if at least one of the following conditions is met:
** A vehicle is introduced, that references the roadtype (road vehicle property <code style="color:green">track_type</code>).
** Another roadtype is introduced, that references the roadtype via the introduced roadtype list (roadtype property <code style="color:green">introduces_roadtype_list</code>).
** The introduction date (roadtype property <code style="color:green">introduction_date</code>) is passed and all required roadtypes (roadtype property <code style="color:green">requires_roadtype_list </code>) are available.

Via roadtype property <code style="color:green">compatible_roadtype_list</code> multiple roadtypes can be defined, which shall be considered equivalent to a roadtype.
This affects the interpretation of road vehicle property <code style="color:green">track_type</code>. If road vehicle property <code style="color:green">track_type</code> references an undefined roadtype, then
roadtype property <code style="color:green">compatible_roadtype_list</code> is checked for all defined roadtypes, whether the vehicle can be reassigned to some other roadtype.
Otherwise the vehicle is disabled.

==Roadtype properties==

{| class="t"
! property
! value range
! comment
|-
| label
| 4-byte string
| names of default road types: "ROAD" and "ELRD". See the [[RoadtypeLabels|List of roadtype labels]] in the NewGRF Specs for currently defined custom labels.
|-
| introduction_date
| date(yyyy,mm,dd)
| Valid range for yyyy is 0 ... 5000000.
|-
| name
| string
| Name of this roadtype
|-
| toolbar_caption
| string
| Caption of the build road toolbar
|-
| menu_text
| string
| Shown in the dropdown menu for all roadtypes
|-
| 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 <road type> engine" news message
|-
| powered_roadtype_list
| list of roadtype labels
| Provide a list of road types that road vehicles of this type are powered on, e.g. ["ROAD", "ELRD"]. Note that there is no difference between "powered" and "compatible" for roadtypes
|-
| roadtype_flags
| bitmask(ROADTYPE_FLAG_XXX, ...)
|
;CATENARY
:Enable catenary
;NO_LEVEL_CROSSING
:Disable level crossings
;NO_HOUSES
:Disallows house construction
;HIDDEN
:Hides the roadtype from players, but remains available to towns
;TOWN_BUILD
:Enables the roadtype to be built by towns, based on ???
|-
| construction_cost
| 0 ... 65525
| Per piece of road as multiplier to PR_BUILD_ROAD base cost. Default cost factors are 8 and 16 for ROAD and ELRD, respectively.
|-
| speed_limit
| 0 ... 65525 km/h (speed units)
| A speed limit of 0 means unlimited speed
|-
| map_colour
| 0 ... 255
| Entry in the colour palette.
|-
| requires_roadtype_list
| list of roadtype labels
| List of road types 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.
|-
| introduces_roadtype_list
| list of roadtype labels
| 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.
|-
| sort_order
| 0 ... 255
| Number which defines the sort order among road types. If this entry is not defined, it gets assigned sort order n*10+7 for the n-th roadtype.
|-
| maintenance_cost
| 0 ... 255
| Maintenance cost factor for each piece of road of this roadtype. Default cost factors are 16 and 24 for ROAD and ELRD, respectively.
|-
| alternative_roadtype_list
| list of roadtype labels
| List of road types which this road type will act as fallback for, if the corresponding road type is not defined separately
|}

===Sort order===

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

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

==Roadtype variables==

{| class="t"
! name
! value range
! comment
|-
| terrain_type
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|
|-
| 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
|-
| random_bits
|
| 2 pseudo random bits
|}

==Roadtype callbacks==

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

{| class="t"
! callbacks
! number of sprites
! meaning
|-
| gui
| 12
| 6 gui icons, 6 cursors
|-
| track_overlay<ref name=leftout>Either all or none of these sprites should be provided.</ref>
| 19
| 11 roadbit combinations, 4 slopes, and 4 dead ends. These sprites are optional for roadtypes.
|-
| underlay<ref name=leftout />
| 19
| 11 roadbit combinations, 4 slopes, and 4 dead ends. These sprites are required.
|-
| tunnels<ref name=leftout />
| 4
| 1 sprite for each direction. Sprite is overlay for road in existing tunnel graphics. The original ground sprite is drawn, then the overlay, then possibly a road vehicle and the original tunnel head is drawn over the top. This keeps compatibility with different landscape types. Sprite order: SW, NW, NE, SE.
|-
| catenary_front
| 29
| 11 roadbit combinations, 4 slopes, 4 dead ends, 4 tunnels, 2 bridge middle, 4 bridge ramps
|-
| catenary_back
| 29
| 11 roadbit combinations, 4 slopes, 4 dead ends, 4 tunnels (unused), 2 bridge middle, 4 bridge ramps
|-
| bridge_surfaces<ref name=leftout />
| 6
| 2 bridge middle, 4 bridge ramps
|-
| depots
| 6
| If not present, the default depot sprites (depending on catenary flag) plus track overlay are drawn.
If present, the depot sprites are expected to include track overlay graphics.

|-
| roadstops
| 4
| Overlays for drive-in road stops
|}

<references />
Note that there is no "default graphics" callback.

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

[[File:Nrt_gui.png]]

==== underlay ====

[[File:Nrt_underlay.png]]

==== catenary_front ====

[[File:Nrt_catenary_front.png]]

==== catenary_back ====

[[File:Nrt_catenary_back.png]]

==== depots ====

[[File:Nrt_depot.png]]

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

==== bridge_surfaces ====

[[File:Nrt_bridge.png]]

==== roadstops ====

[[File:Nrt_drivein.png]]


===Example code===

A typical implementation for roadtypes can look like:

<pre style="color:blue">
item(FEAT_ROADTYPES, highway, 0x01) {
property {
label: "HWY_";
name: string(STR_HWY);
menu_text: string(STR_HWY);
build_window_caption: string(STR_BUILD_CAPTION);
autoreplace_text: string(STR_AUTOREPLACE);
new_engine_text: string(STR_NEW_ENGINE);
powered_roadtype_list: ["HWY_","ROAD"]; // Highways are compatible with other roads
roadtype_flags: bitmask(ROADTYPE_FLAG_NO_LEVEL_CROSSING, ROADTYPE_FLAG_NO_HOUSES); // Highways should not have level crossings or houses
construction_cost: 32; // Highways are expensive
speed_limit: 100 km/h;
}
graphics {
underlay: ground_switch_underlay; // defines the usual roads
tunnels: tunnel_switch; // defines the roads drawn on a tunnel tile
depots: depot_switch; // defines the depot sprites
bridge_surfaces: bridge_terrain_switch; // defines the overlay drawn over bridges depending on climate
roadstops: roadstops_switch; // defines the look of roadstop pavement
}
}
</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:Roadtypes

2019-12-22T11:30:16Z

Andrew350: initial roadtype spec (incomplete)

{{NMLNavPropVarCB}}

Roadtypes can only be defined in OpenTTD {{ottd|1.10}} or later.

==Roadtype IDs==
Roadtypes and Tramtypes share a pool of 64 IDs. Either feature can use as many IDs as needed (i.e. it is not limited to 32 per type), but both features combined are limited to 64 in total. NewGRF-local IDs may freely be chosen, but must be in the 0..63 range. If other roadtype/tramtype GRFs are loaded, it may be that there are not enough 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 (roadtype_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 roadtypes.

== 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 property <code style="color:green">track_type</code>) is defined. Otherwise the vehicle is disabled.
* When a vehicle is introduced, it always introduces its roadtype (road vehicle property <code style="color:green">track_type</code>).
* A roadtype is introduced, if at least one of the following conditions is met:
** A vehicle is introduced, that references the roadtype (road vehicle property <code style="color:green">track_type</code>).
** Another roadtype is introduced, that references the roadtype via the introduced roadtype list (roadtype property <code style="color:green">introduces_roadtype_list</code>).
** The introduction date (roadtype property <code style="color:green">introduction_date</code>) is passed and all required roadtypes (roadtype property <code style="color:green">requires_roadtype_list </code>) are available.

Via roadtype property <code style="color:green">compatible_roadtype_list</code> multiple roadtypes can be defined, which shall be considered equivalent to a roadtype.
This affects the interpretation of road vehicle property <code style="color:green">track_type</code>. If road vehicle property <code style="color:green">track_type</code> references an undefined roadtype, then
roadtype property <code style="color:green">compatible_roadtype_list</code> is checked for all defined roadtypes, whether the vehicle can be reassigned to some other roadtype.
Otherwise the vehicle is disabled.

==Roadtype properties==

{| class="t"
! property
! value range
! comment
|-
| label
| 4-byte string
| names of default road types: "ROAD" and "ELRD". See the [[RoadtypeLabels|List of roadtype labels]] in the NewGRF Specs for currently defined custom labels.
|-
| introduction_date
| date(yyyy,mm,dd)
| Valid range for yyyy is 0 ... 5000000.
|-
| name
| string
| Name of this roadtype
|-
| toolbar_caption
| string
| Caption of the build road toolbar
|-
| menu_text
| string
| Shown in the dropdown menu for all roadtypes
|-
| 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 <road type> engine" news message
|-
| powered_roadtype_list
| list of roadtype labels
| Provide a list of road types that road vehicles of this type are powered on, e.g. ["ROAD", "ELRD"]. Note that there is no difference between "powered" and "compatible" for roadtypes
|-
| roadtype_flags
| bitmask(ROADTYPE_FLAG_XXX, ...)
|
;CATENARY
:Enable catenary
;NO_LEVEL_CROSSING
:Disable level crossings
;NO_HOUSES
:Disallows house construction
|-
| construction_cost
| 0 ... 65525
| Per piece of road as multiplier to PR_BUILD_ROAD base cost. Default cost factors are 8 and 16 for ROAD and ELRD, respectively.
|-
| speed_limit
| 0 ... 65525 km/h (speed units)
| A speed limit of 0 means unlimited speed
|-
| map_colour
| 0 ... 255
| Entry in the colour palette.
|-
| requires_roadtype_list
| list of roadtype labels
| List of road types 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.
|-
| introduces_roadtype_list
| list of roadtype labels
| 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.
|-
| sort_order
| 0 ... 255
| Number which defines the sort order among road types. If this entry is not defined, it gets assigned sort order n*10+7 for the n-th roadtype.
|-
| maintenance_cost
| 0 ... 255
| Maintenance cost factor for each piece of road of this roadtype. Default cost factors are 16 and 24 for ROAD and ELRD, respectively.
|-
| alternative_roadtype_list
| list of roadtype labels
| List of road types which this road type will act as fallback for, if the corresponding road type is not defined separately
|}

===Sort order===

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

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

==Roadtype variables==

{| class="t"
! name
! value range
! comment
|-
| terrain_type
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|
|-
| 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
|-
| random_bits
|
| 2 pseudo random bits
|}

==Roadtype callbacks==

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

{| class="t"
! callbacks
! number of sprites
! meaning
|-
| gui
| 12
| 6 gui icons, 6 cursors
|-
| track_overlay<ref name=leftout>Either all or none of these sprites should be provided.</ref>
| 19
| 11 roadbit combinations, 4 slopes, and 4 dead ends. These sprites are optional for roadtypes.
|-
| underlay<ref name=leftout />
| 19
| 11 roadbit combinations, 4 slopes, and 4 dead ends. These sprites are required.
|-
| tunnels<ref name=leftout />
| 4
| 1 sprite for each direction. Sprite is overlay for road in existing tunnel graphics. The original ground sprite is drawn, then the overlay, then possibly a road vehicle and the original tunnel head is drawn over the top. This keeps compatibility with different landscape types. Sprite order: SW, NW, NE, SE.
|-
| catenary_front
| 29
| 11 roadbit combinations, 4 slopes, 4 dead ends, 4 tunnels, 2 bridge middle, 4 bridge ramps
|-
| catenary_back
| 29
| 11 roadbit combinations, 4 slopes, 4 dead ends, 4 tunnels (unused), 2 bridge middle, 4 bridge ramps
|-
| bridge_surfaces<ref name=leftout />
| 6
| 2 bridge middle, 4 bridge ramps
|-
| depots
| 6
| If not present, the default depot sprites (depending on catenary flag) plus track overlay are drawn.
If present, the depot sprites are expected to include track overlay graphics.

|-
| roadstops
| 4
| Overlays for drive-in road stops
|}

<references />
Note that there is no "default graphics" callback.

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

[[File:Nrt_gui.png]]

==== underlay ====

[[File:Nrt_underlay.png]]

==== catenary_front ====

[[File:Nrt_catenary_front.png]]

==== catenary_back ====

[[File:Nrt_catenary_back.png]]

==== depots ====

[[File:Nrt_depot.png]]

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

==== bridge_surfaces ====

[[File:Nrt_bridge.png]]

==== roadstops ====

[[File:Nrt_drivein.png]]


===Example code===

A typical implementation for roadtypes can look like:

<pre style="color:blue">
item(FEAT_ROADTYPES, highway, 0x01) {
property {
label: "HWY_";
name: string(STR_HWY);
menu_text: string(STR_HWY);
build_window_caption: string(STR_BUILD_CAPTION);
autoreplace_text: string(STR_AUTOREPLACE);
new_engine_text: string(STR_NEW_ENGINE);
powered_roadtype_list: ["HWY_","ROAD"]; // Highways are compatible with other roads
roadtype_flags: bitmask(ROADTYPE_FLAG_NO_LEVEL_CROSSING, ROADTYPE_FLAG_NO_HOUSES); // Highways should not have level crossings or houses
construction_cost: 32; // Highways are expensive
speed_limit: 100 km/h;
}
graphics {
underlay: ground_switch_underlay; // defines the usual roads
tunnels: tunnel_switch; // defines the roads drawn on a tunnel tile
depots: depot_switch; // defines the depot sprites
bridge_surfaces: bridge_terrain_switch; // defines the overlay drawn over bridges depending on climate
roadstops: roadstops_switch; // defines the look of roadstop pavement
}
}
</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:Tramtypes

2019-12-22T11:29:20Z

Andrew350: initial tramtype spec (incomplete)

{{NMLNavPropVarCB}}

Tramtypes can only be defined in OpenTTD {{ottd|1.10}} or later.

==Tramtype IDs==
Tramtypes and Roadtypes share a pool of 64 IDs. Either feature can use as many IDs as needed (i.e. it is not limited to 32 per type), but both features combined are limited to 64 in total. NewGRF-local IDs may freely be chosen, but must be in the 0..63 range. If other tramtype/tramtype GRFs are loaded, it may be that there are not enough 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 (tramtype_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 tramtypes.

== 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.
* Remember that the road vehicle flag 'ROADVEH_FLAG_TRAM' must be set in order for a road vehicle to be considered a tram.
* A vehicle exists, if its tramtype (tram vehicle property <code style="color:green">track_type</code>) is defined. Otherwise the vehicle is disabled.
* When a vehicle is introduced, it always introduces its tramtype (tram vehicle property <code style="color:green">track_type</code>).
* A tramtype is introduced, if at least one of the following conditions is met:
** A vehicle is introduced, that references the tramtype (tram vehicle property <code style="color:green">track_type</code>).
** Another tramtype is introduced, that references the tramtype via the introduced tramtype list (tramtype property <code style="color:green">introduces_tramtype_list</code>).
** The introduction date (tramtype property <code style="color:green">introduction_date</code>) is passed and all required tramtypes (tramtype property <code style="color:green">requires_tramtype_list </code>) are available.

Via tramtype property <code style="color:green">powered_tramtype_list</code> multiple tramtypes can be defined, which shall be considered equivalent to a tramtype.
This affects the interpretation of tram vehicle property <code style="color:green">track_type</code>. If tram vehicle property <code style="color:green">track_type</code> references an undefined tramtype, then
tramtype property <code style="color:green">powered_tramtype_list</code> is checked for all defined tramtypes, whether the vehicle can be reassigned to some other tramtype.
Otherwise the vehicle is disabled.

==Tramtype properties==

{| class="t"
! property
! value range
! comment
|-
| label
| 4-byte string
| names of default tram types: "RAIL" and "ELRL". See the [[TramtypeLabels|List of tramtype labels]] in the NewGRF Specs for currently defined custom labels.
|-
| introduction_date
| date(yyyy,mm,dd)
| Valid range for yyyy is 0 ... 5000000.
|-
| name
| string
| Name of this tramtype
|-
| toolbar_caption
| string
| Caption of the build tram toolbar. In earlier versions this is the same as the 'name'
|-
| menu_text
| string
| Shown in the dropdown menu for all tramtypes
|-
| 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 <tram type> engine" news message
|-
| powered_tramtype_list
| list of tramtype labels
| Provide a list of tram types that tram vehicles of this type are powered on, e.g. ["RAIL", "ELRL"]. Note that there is no difference between "powered" and "compatible" for tramtypes
|-
| tramtype_flags
| bitmask(TRAMTYPE_FLAG_XXX, ...)
|
;CATENARY
:Enable catenary
;NO_LEVEL_CROSSING
:Disable level crossings
;NO_HOUSES
:Disallows house construction
|-
| construction_cost
| 0 ... 65525
| Per piece of track as multiplier to PR_BUILD_ROAD base cost. Default cost factors are 8 and 16 for RAIL and ELRL, respectively.
|-
| speed_limit
| 0 ... 65525 km/h (speed units)
| A speed limit of 0 means unlimited speed
|-
| map_colour
| 0 ... 255
| Entry in the colour palette.
|-
| requires_tramtype_list
| list of tramtype labels
| List of tram types 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.
|-
| introduces_tramtype_list
| list of tramtype labels
| 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.
|-
| sort_order
| 0 ... 255
| Number which defines the sort order among tram types. If this entry is not defined, it gets assigned sort order n*10+7 for the n-th tramtype.
|-
| maintenance_cost
| 0 ... 255
| Maintenance cost factor for each piece of tram of this tramtype. Default cost factors are 16 and 24 for RAIL and ELRL, respectively.
|-
| alternative_tramtype_list
| list of tramtype labels
| List of tram types which this tram type will act as fallback for, if the corresponding tram type is not defined separately
|}

===Sort order===

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

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

==Tramtype variables==

{| class="t"
! name
! value range
! comment
|-
| terrain_type
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|
|-
| 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
|-
| random_bits
|
| 2 pseudo random bits
|}

==Tramtype callbacks==

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

{| class="t"
! callbacks
! number of sprites
! meaning
|-
| gui
| 12
| 6 gui icons, 6 cursors
|-
| track_overlay<ref name=leftout>Either all or none of these sprites should be provided.</ref>
| 19
| 11 track combinations, 4 slopes, and 4 dead ends. These sprites are required
|-
| underlay<ref name=leftout />
| 19
| 11 track combinations, 4 slopes, and 4 dead ends. These sprites are required
|-
| tunnels<ref name=leftout />
| 4
| 1 sprite for each direction. Sprite is overlay for tram in existing tunnel graphics. The original ground sprite is drawn, then the overlay, then possibly a tram vehicle and the original tunnel head is drawn over the top. This keeps compatibility with different landscape types. Sprite order: SW, NW, NE, SE.
|-
| catenary_front
| 29
| 11 track combinations, 4 slopes, 4 dead ends, 4 tunnels, 2 bridge middle, 4 bridge ramps
|-
| catenary_back
| 29
| 11 track combinations, 4 slopes, 4 dead ends, 4 tunnels (unused), 2 bridge middle, 4 bridge ramps
|-
| bridge_surfaces<ref name=leftout />
| 6
| 2 bridge middle, 4 bridge ramps
|-
| depots
| 6
| If not present, the default depot sprites (depending on catenary flag) plus track overlay are drawn.
If present, the depot sprites are expected to include track overlay graphics.

|}

<references />
Note that there is no "default graphics" callback.

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

[[File:Nrt_gui.png]]

==== underlay ====

[[File:Nrt_underlay.png]]

==== overlay ====

[[File:Nrt_overlay.png]]

==== catenary_front ====

[[File:Nrt_catenary_front.png]]

==== catenary_back ====

[[File:Nrt_catenary_back.png]]

==== depots ====

[[File:Nrt_depot.png]]

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

==== bridge_surfaces ====

[[File:Nrt_bridge.png]]


===Example code===

A typical implementation for tramtypes can look like:

<pre style="color:blue">
item(FEAT_TRAMTYPES, dctram, 0x01) {
property {
label: "DCTM";
name: string(STR_DC_TRAM);
menu_text: string(STR_DC_TRAM);
build_window_caption: string(STR_BUILD_CAPTION);
autoreplace_text: string(STR_AUTOREPLACE);
new_engine_text: string(STR_NEW_ENGINE);
powered_tramtype_list: ["DCTM","ELRL"]; // These trams are compatible with other electric trams
tramtype_flags: bitmask(TRAMTYPE_FLAG_CATENARY); // These tramways require catenary
construction_cost: 24; // Electric tramways are pricey
speed_limit: 50 km/h;
}
graphics {
underlay: ground_switch_underlay; // defines the tramtrack underlay
overlay: track_overlay_switch; // defines the tramtrack overlay
tunnels: tunnel_switch; // defines the track drawn on a tunnel tile
depots: depot_switch; // defines the depot sprites
bridge_surfaces: bridge_terrain_switch; // defines the overlay drawn over bridges depending on climate
}
}
</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.

User:Andrew350/NML:Tramtypes

2019-12-22T11:22:14Z

Andrew350: initial conversion to tramtypes (from roadtypes)

{{NMLNavPropVarCB}}

Tramtypes can only be defined in OpenTTD {{ottd|1.10}} or later.

==Tramtype IDs==
Tramtypes and Roadtypes share a pool of 64 IDs. Either feature can use as many IDs as needed (i.e. it is not limited to 32 per type), but both features combined are limited to 64 in total. NewGRF-local IDs may freely be chosen, but must be in the 0..63 range. If other tramtype/tramtype GRFs are loaded, it may be that there are not enough 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 (tramtype_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 tramtypes.

== 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.
* Remember that the road vehicle flag 'ROADVEH_FLAG_TRAM' must be set in order for a road vehicle to be considered a tram.
* A vehicle exists, if its tramtype (tram vehicle property <code style="color:green">track_type</code>) is defined. Otherwise the vehicle is disabled.
* When a vehicle is introduced, it always introduces its tramtype (tram vehicle property <code style="color:green">track_type</code>).
* A tramtype is introduced, if at least one of the following conditions is met:
** A vehicle is introduced, that references the tramtype (tram vehicle property <code style="color:green">track_type</code>).
** Another tramtype is introduced, that references the tramtype via the introduced tramtype list (tramtype property <code style="color:green">introduces_tramtype_list</code>).
** The introduction date (tramtype property <code style="color:green">introduction_date</code>) is passed and all required tramtypes (tramtype property <code style="color:green">requires_tramtype_list </code>) are available.

Via tramtype property <code style="color:green">powered_tramtype_list</code> multiple tramtypes can be defined, which shall be considered equivalent to a tramtype.
This affects the interpretation of tram vehicle property <code style="color:green">track_type</code>. If tram vehicle property <code style="color:green">track_type</code> references an undefined tramtype, then
tramtype property <code style="color:green">powered_tramtype_list</code> is checked for all defined tramtypes, whether the vehicle can be reassigned to some other tramtype.
Otherwise the vehicle is disabled.

==Tramtype properties==

{| class="t"
! property
! value range
! comment
|-
| label
| 4-byte string
| names of default tram types: "RAIL" and "ELRL". See the [[TramtypeLabels|List of tramtype labels]] in the NewGRF Specs for currently defined custom labels.
|-
| introduction_date
| date(yyyy,mm,dd)
| Valid range for yyyy is 0 ... 5000000.
|-
| name
| string
| Name of this tramtype
|-
| toolbar_caption
| string
| Caption of the build tram toolbar. In earlier versions this is the same as the 'name'
|-
| menu_text
| string
| Shown in the dropdown menu for all tramtypes
|-
| 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 <tram type> engine" news message
|-
| powered_tramtype_list
| list of tramtype labels
| Provide a list of tram types that tram vehicles of this type are powered on, e.g. ["RAIL", "ELRL"]. Note that there is no difference between "powered" and "compatible" for tramtypes
|-
| tramtype_flags
| bitmask(TRAMTYPE_FLAG_XXX, ...)
|
;CATENARY
:Enable catenary
;NO_LEVEL_CROSSING
:Disable level crossings
;NO_HOUSES
:Disallows house construction
|-
| construction_cost
| 0 ... 65525
| Per piece of track as multiplier to PR_BUILD_ROAD base cost. Default cost factors are 8 and 16 for RAIL and ELRL, respectively.
|-
| speed_limit
| 0 ... 65525 km/h (speed units)
| A speed limit of 0 means unlimited speed
|-
| map_colour
| 0 ... 255
| Entry in the colour palette.
|-
| requires_tramtype_list
| list of tramtype labels
| List of tram types 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.
|-
| introduces_tramtype_list
| list of tramtype labels
| 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.
|-
| sort_order
| 0 ... 255
| Number which defines the sort order among tram types. If this entry is not defined, it gets assigned sort order n*10+7 for the n-th tramtype.
|-
| maintenance_cost
| 0 ... 255
| Maintenance cost factor for each piece of tram of this tramtype. Default cost factors are 16 and 24 for RAIL and ELRL, respectively.
|-
| alternative_tramtype_list
| list of tramtype labels
| List of tram types which this tram type will act as fallback for, if the corresponding tram type is not defined separately
|}

===Sort order===

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

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

==Tramtype variables==

{| class="t"
! name
! value range
! comment
|-
| terrain_type
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|
|-
| 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
|-
| random_bits
|
| 2 pseudo random bits
|}

==Tramtype callbacks==

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

{| class="t"
! callbacks
! number of sprites
! meaning
|-
| gui
| 12
| 6 gui icons, 6 cursors
|-
| track_overlay<ref name=leftout>Either all or none of these sprites should be provided.</ref>
| 19
| 11 track combinations, 4 slopes, and 4 dead ends. These sprites are required
|-
| underlay<ref name=leftout />
| 19
| 11 track combinations, 4 slopes, and 4 dead ends. These sprites are required
|-
| tunnels<ref name=leftout />
| 4
| 1 sprite for each direction. Sprite is overlay for tram in existing tunnel graphics. The original ground sprite is drawn, then the overlay, then possibly a tram vehicle and the original tunnel head is drawn over the top. This keeps compatibility with different landscape types. Sprite order: SW, NW, NE, SE.
|-
| catenary_front
| 29
| 11 track combinations, 4 slopes, 4 dead ends, 4 tunnels, 2 bridge middle, 4 bridge ramps
|-
| catenary_back
| 29
| 11 track combinations, 4 slopes, 4 dead ends, 4 tunnels (unused), 2 bridge middle, 4 bridge ramps
|-
| bridge_surfaces<ref name=leftout />
| 6
| 2 bridge middle, 4 bridge ramps
|-
| depots
| 6
| If not present, the default depot sprites (depending on catenary flag) plus track overlay are drawn.
If present, the depot sprites are expected to include track overlay graphics.

|}

<references />
Note that there is no "default graphics" callback.

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

[[File:Nrt_gui.png]]

==== underlay ====

[[File:Nrt_underlay.png]]

==== overlay ====

[[File:Nrt_overlay.png]]

==== catenary_front ====

[[File:Nrt_catenary_front.png]]

==== catenary_back ====

[[File:Nrt_catenary_back.png]]

==== depots ====

[[File:Nrt_depot.png]]

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

==== bridge_surfaces ====

[[File:Nrt_bridge.png]]


===Example code===

A typical implementation for tramtypes can look like:

<pre style="color:blue">
item(FEAT_TRAMTYPES, dctram, 0x01) {
property {
label: "DCTM";
name: string(STR_DC_TRAM);
menu_text: string(STR_DC_TRAM);
build_window_caption: string(STR_BUILD_CAPTION);
autoreplace_text: string(STR_AUTOREPLACE);
new_engine_text: string(STR_NEW_ENGINE);
powered_tramtype_list: ["DCTM","ELRL"]; // These trams are compatible with other electric trams
tramtype_flags: bitmask(TRAMTYPE_FLAG_CATENARY); // These tramways require catenary
construction_cost: 24; // Electric tramways are pricey
speed_limit: 50 km/h;
}
graphics {
underlay: ground_switch_underlay; // defines the tramtrack underlay
overlay: track_overlay_switch; // defines the tramtrack overlay
tunnels: tunnel_switch; // defines the track drawn on a tunnel tile
depots: depot_switch; // defines the depot sprites
bridge_surfaces: bridge_terrain_switch; // defines the overlay drawn over bridges depending on climate
}
}
</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.

User:Andrew350/NML:Roadtypes

2019-12-22T11:03:09Z

Andrew350: remove some unnecessary things

{{NMLNavPropVarCB}}

Roadtypes can only be defined in OpenTTD {{ottd|1.10}} or later.

==Roadtype IDs==
Roadtypes and Tramtypes share a pool of 64 IDs. Either feature can use as many IDs as needed (i.e. it is not limited to 32 per type), but both features combined are limited to 64 in total. NewGRF-local IDs may freely be chosen, but must be in the 0..63 range. If other roadtype/tramtype GRFs are loaded, it may be that there are not enough 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 (roadtype_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 roadtypes.

== 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 property <code style="color:green">track_type</code>) is defined. Otherwise the vehicle is disabled.
* When a vehicle is introduced, it always introduces its roadtype (road vehicle property <code style="color:green">track_type</code>).
* A roadtype is introduced, if at least one of the following conditions is met:
** A vehicle is introduced, that references the roadtype (road vehicle property <code style="color:green">track_type</code>).
** Another roadtype is introduced, that references the roadtype via the introduced roadtype list (roadtype property <code style="color:green">introduces_roadtype_list</code>).
** The introduction date (roadtype property <code style="color:green">introduction_date</code>) is passed and all required roadtypes (roadtype property <code style="color:green">requires_roadtype_list </code>) are available.

Via roadtype property <code style="color:green">compatible_roadtype_list</code> multiple roadtypes can be defined, which shall be considered equivalent to a roadtype.
This affects the interpretation of road vehicle property <code style="color:green">track_type</code>. If road vehicle property <code style="color:green">track_type</code> references an undefined roadtype, then
roadtype property <code style="color:green">compatible_roadtype_list</code> is checked for all defined roadtypes, whether the vehicle can be reassigned to some other roadtype.
Otherwise the vehicle is disabled.

==Roadtype properties==

{| class="t"
! property
! value range
! comment
|-
| label
| 4-byte string
| names of default road types: "ROAD" and "ELRD". See the [[RoadtypeLabels|List of roadtype labels]] in the NewGRF Specs for currently defined custom labels.
|-
| introduction_date
| date(yyyy,mm,dd)
| Valid range for yyyy is 0 ... 5000000.
|-
| name
| string
| Name of this roadtype
|-
| toolbar_caption
| string
| Caption of the build road toolbar
|-
| menu_text
| string
| Shown in the dropdown menu for all roadtypes
|-
| 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 <road type> engine" news message
|-
| powered_roadtype_list
| list of roadtype labels
| Provide a list of road types that road vehicles of this type are powered on, e.g. ["ROAD", "ELRD"]. Note that there is no difference between "powered" and "compatible" for roadtypes
|-
| roadtype_flags
| bitmask(ROADTYPE_FLAG_XXX, ...)
|
;CATENARY
:Enable catenary
;NO_LEVEL_CROSSING
:Disable level crossings
;NO_HOUSES
:Disallows house construction
|-
| construction_cost
| 0 ... 65525
| Per piece of road as multiplier to PR_BUILD_ROAD base cost. Default cost factors are 8 and 16 for ROAD and ELRD, respectively.
|-
| speed_limit
| 0 ... 65525 km/h (speed units)
| A speed limit of 0 means unlimited speed
|-
| map_colour
| 0 ... 255
| Entry in the colour palette.
|-
| requires_roadtype_list
| list of roadtype labels
| List of road types 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.
|-
| introduces_roadtype_list
| list of roadtype labels
| 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.
|-
| sort_order
| 0 ... 255
| Number which defines the sort order among road types. If this entry is not defined, it gets assigned sort order n*10+7 for the n-th roadtype.
|-
| maintenance_cost
| 0 ... 255
| Maintenance cost factor for each piece of road of this roadtype. Default cost factors are 16 and 24 for ROAD and ELRD, respectively.
|-
| alternative_roadtype_list
| list of roadtype labels
| List of road types which this road type will act as fallback for, if the corresponding road type is not defined separately
|}

===Sort order===

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

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

==Roadtype variables==

{| class="t"
! name
! value range
! comment
|-
| terrain_type
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|
|-
| 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
|-
| random_bits
|
| 2 pseudo random bits
|}

==Roadtype callbacks==

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

{| class="t"
! callbacks
! number of sprites
! meaning
|-
| gui
| 12
| 6 gui icons, 6 cursors
|-
| track_overlay<ref name=leftout>Either all or none of these sprites should be provided.</ref>
| 19
| 11 roadbit combinations, 4 slopes, and 4 dead ends. These sprites are optional for roadtypes.
|-
| underlay<ref name=leftout />
| 19
| 11 roadbit combinations, 4 slopes, and 4 dead ends. These sprites are required.
|-
| tunnels<ref name=leftout />
| 4
| 1 sprite for each direction. Sprite is overlay for road in existing tunnel graphics. The original ground sprite is drawn, then the overlay, then possibly a road vehicle and the original tunnel head is drawn over the top. This keeps compatibility with different landscape types. Sprite order: SW, NW, NE, SE.
|-
| catenary_front
| 29
| 11 roadbit combinations, 4 slopes, 4 dead ends, 4 tunnels, 2 bridge middle, 4 bridge ramps
|-
| catenary_back
| 29
| 11 roadbit combinations, 4 slopes, 4 dead ends, 4 tunnels (unused), 2 bridge middle, 4 bridge ramps
|-
| bridge_surfaces<ref name=leftout />
| 6
| 2 bridge middle, 4 bridge ramps
|-
| depots
| 6
| If not present, the default depot sprites (depending on catenary flag) plus track overlay are drawn.
If present, the depot sprites are expected to include track overlay graphics.

|-
| roadstops
| 4
| Overlays for drive-in road stops
|}

<references />
Note that there is no "default graphics" callback.

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

[[File:Nrt_gui.png]]

==== underlay ====

[[File:Nrt_underlay.png]]

==== catenary_front ====

[[File:Nrt_catenary_front.png]]

==== catenary_back ====

[[File:Nrt_catenary_back.png]]

==== depots ====

[[File:Nrt_depot.png]]

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

==== bridge_surfaces ====

[[File:Nrt_bridge.png]]

==== roadstops ====

[[File:Nrt_drivein.png]]


===Example code===

A typical implementation for roadtypes can look like:

<pre style="color:blue">
item(FEAT_ROADTYPES, highway, 0x01) {
property {
label: "HWY_";
name: string(STR_HWY);
menu_text: string(STR_HWY);
build_window_caption: string(STR_BUILD_CAPTION);
autoreplace_text: string(STR_AUTOREPLACE);
new_engine_text: string(STR_NEW_ENGINE);
powered_roadtype_list: ["HWY_","ROAD"]; // Highways are compatible with other roads
roadtype_flags: bitmask(ROADTYPE_FLAG_NO_LEVEL_CROSSING, ROADTYPE_FLAG_NO_HOUSES); // Highways should not have level crossings or houses
construction_cost: 32; // Highways are expensive
speed_limit: 100 km/h;
}
graphics {
underlay: ground_switch_underlay; // defines the usual roads
tunnels: tunnel_switch; // defines the roads drawn on a tunnel tile
depots: depot_switch; // defines the depot sprites
bridge_surfaces: bridge_terrain_switch; // defines the overlay drawn over bridges depending on climate
roadstops: roadstops_switch; // defines the look of roadstop pavement
}
}
</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.

File:Nrt underlay.png

2019-12-22T09:41:48Z

Andrew350:

File:Nrt overlay.png

2019-12-22T09:41:37Z

Andrew350:

File:Nrt gui.png

2019-12-22T09:41:26Z

Andrew350:

File:Nrt drivein.png

2019-12-22T09:41:16Z

Andrew350:

File:Nrt depot.png

2019-12-22T09:41:02Z

Andrew350:

File:Nrt catenary front.png

2019-12-22T09:40:52Z

Andrew350:

File:Nrt catenary back.png

2019-12-22T09:40:41Z

Andrew350:

File:Nrt bridge.png

2019-12-22T09:39:15Z

Andrew350:

User:Andrew350/NML:Roadtypes

2019-12-22T09:35:12Z

Andrew350: fine-tuned the specs for roadtypes, cross referenced from frosch's draft specs

{{NMLNavPropVarCB}}

Roadtypes can only be defined in OpenTTD {{ottd|1.10}} or later.

==Roadtype IDs==
Roadtypes and Tramtypes share a pool of 64 IDs. Either feature can use as many IDs as needed (i.e. it is not limited to 32 per type), but both features combined are limited to 64 in total. NewGRF-local IDs may freely be chosen, but must be in the 0..63 range. If other roadtype/tramtype GRFs are loaded, it may be that there are not enough 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 (roadtype_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 roadtypes.

== 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 property <code style="color:green">track_type</code>) is defined. Otherwise the vehicle is disabled.
* When a vehicle is introduced, it always introduces its roadtype (road vehicle property <code style="color:green">track_type</code>).
* A roadtype is introduced, if at least one of the following conditions is met:
** A vehicle is introduced, that references the roadtype (road vehicle property <code style="color:green">track_type</code>).
** Another roadtype is introduced, that references the roadtype via the introduced roadtype list (roadtype property <code style="color:green">introduces_roadtype_list</code>).
** The introduction date (roadtype property <code style="color:green">introduction_date</code>) is passed and all required roadtypes (roadtype property <code style="color:green">requires_roadtype_list </code>) are available.

Via roadtype property <code style="color:green">compatible_roadtype_list</code> multiple roadtypes can be defined, which shall be considered equivalent to a roadtype.
This affects the interpretation of road vehicle property <code style="color:green">track_type</code>. If road vehicle property <code style="color:green">track_type</code> references an undefined roadtype, then
roadtype property <code style="color:green">compatible_roadtype_list</code> is checked for all defined roadtypes, whether the vehicle can be reassigned to some other roadtype.
Otherwise the vehicle is disabled.

==Roadtype properties==

{| class="t"
! property
! value range
! comment
|-
| label
| 4-byte string
| names of default road types: "ROAD" and "ELRD". See the [[RoadtypeLabels|List of roadtype labels]] in the NewGRF Specs for currently defined custom labels.
|-
| introduction_date
| date(yyyy,mm,dd)
| Valid range for yyyy is 0 ... 5000000.
|-
| name
| string
| Name of this roadtype
|-
| toolbar_caption
| string
| Caption of the build road toolbar. In earlier versions this is the same as the 'name'
|-
| menu_text
| string
| Shown in the dropdown menu for all roadtypes
|-
| 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 <road type> engine" news message
|-
| powered_roadtype_list
| list of roadtype labels
| Provide a list of road types that road vehicles of this type are powered on, e.g. ["ROAD", "ELRD"]. Note that there is no difference between "powered" and "compatible" for roadtypes
|-
| roadtype_flags
| bitmask(ROADTYPE_FLAG_XXX, ...)
|
;CATENARY
:Enable catenary
;NO_LEVEL_CROSSING
:Disable level crossings
;NO_HOUSES
:Disallows house construction
|-
| construction_cost
| 0 ... 65525
| Per piece of road as multiplier to PR_BUILD_ROAD base cost. Default cost factors are 8 and 16 for ROAD and ELRD, respectively.
|-
| speed_limit
| 0 ... 65525 km/h (speed units)
| A speed limit of 0 means unlimited speed
|-
| map_colour
| 0 ... 255
| Entry in the colour palette.
|-
| requires_roadtype_list
| list of roadtype labels
| List of road types 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.
|-
| introduces_roadtype_list
| list of roadtype labels
| 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.
|-
| sort_order
| 0 ... 255
| Number which defines the sort order among road types. If this entry is not defined, it gets assigned sort order n*10+7 for the n-th roadtype.
|-
| maintenance_cost
| 0 ... 255
| Maintenance cost factor for each piece of road of this roadtype. Default cost factors are 16 and 24 for ROAD and ELRD, respectively.
|-
| alternative_roadtype_list
| list of roadtype labels
| List of road types which this road type will act as fallback for, if the corresponding road type is not defined separately
|}

===Sort order===

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

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

==Roadtype variables==

{| class="t"
! name
! value range
! comment
|-
| terrain_type
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|
|-
| 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.)
|-
| random_bits
|
| 2 pseudo random bits
|}

==Roadtype callbacks==

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

{| class="t"
! callbacks
! number of sprites
! meaning
|-
| gui
| 12
| 6 gui icons, 6 cursors
|-
| track_overlay<ref name=leftout>Either all or none of these sprites should be provided.</ref>
| 19
| 11 roadbit combinations, 4 slopes, and 4 dead ends. These sprites are optional for roadtypes.
|-
| underlay<ref name=leftout />
| 19
| 11 roadbit combinations, 4 slopes, and 4 dead ends. These sprites are required.
|-
| tunnels<ref name=leftout />
| 4
| 1 sprite for each direction. Sprite is overlay for road in existing tunnel graphics. The original ground sprite is drawn, then the overlay, then possibly a road vehicle and the original tunnel head is drawn over the top. This keeps compatibility with different landscape types. Sprite order: SW, NW, NE, SE.
|-
| catenary_front
| 29
| 11 roadbit combinations, 4 slopes, 4 dead ends, 4 tunnels, 2 bridge middle, 4 bridge ramps
|-
| catenary_back
| 29
| 11 roadbit combinations, 4 slopes, 4 dead ends, 4 tunnels (unused), 2 bridge middle, 4 bridge ramps
|-
| bridge_surfaces<ref name=leftout />
| 6
| 2 bridge middle, 4 bridge ramps
|-
| depots
| 6
| If not present, the default depot sprites (depending on catenary flag) plus track overlay are drawn.
If present, the depot sprites are expected to include track overlay graphics.

|-
| roadstops
| 4
| Overlays for drive-in road stops
|}

<references />
Note that there is no "default graphics" callback.

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

[[File:Nrt_gui.png]]

==== underlay ====

[[File:Nrt_underlay.png]]

==== catenary_front ====

[[File:Nrt_catenary_front.png]]

==== catenary_back ====

[[File:Nrt_catenary_back.png]]

==== depots ====

[[File:Nrt_depot.png]]

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

==== bridge_surfaces ====

[[File:Nrt_bridge.png]]

==== roadstops ====

[[File:Nrt_drivein.png]]


===Example code===

A typical implementation for roadtypes can look like:

<pre style="color:blue">
item(FEAT_ROADTYPES, highway, 0x01) {
property {
label: "HWY_";
name: string(STR_HWY);
menu_text: string(STR_HWY);
build_window_caption: string(STR_BUILD_CAPTION);
autoreplace_text: string(STR_AUTOREPLACE);
new_engine_text: string(STR_NEW_ENGINE);
powered_roadtype_list: ["HWY_","ROAD"]; // Highways are compatible with other roads
roadtype_flags: bitmask(ROADTYPE_FLAG_NO_LEVEL_CROSSING, ROADTYPE_FLAG_NO_HOUSES); // Highways should not have level crossings or houses
construction_cost: 32; // Highways are expensive
speed_limit: 100 km/h;
}
graphics {
underlay: ground_switch_underlay; // defines the usual roads
tunnels: tunnel_switch; // defines the roads drawn on a tunnel tile
depots: depot_switch; // defines the depot sprites
bridge_surfaces: bridge_terrain_switch; // defines the overlay drawn over bridges depending on climate
roadstops: roadstops_switch; // defines the look of roadstop pavement
}
}
</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.