GRFSpecs - User contributions [en-gb]

Action0/Vehicles/Trains

2014-12-07T16:04:53Z

The Dude: Add nicely organized table for always active callbacks

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

=Introduction=
Defining properties of train vehicles.

= Properties =

{| |-
!Number!![[GRFActionsDetailed|Size]]!!Version!!Description!!Available for articulated parts
|-
|05||B||{{ottdp|0.6|2.0}}||Track type (see below)||should be same as front
|-
|08||B||{{ottdp|0.6|2.0}}||AI special flag: set to 1 if engine is 'optimized' for passenger service (AI won't use it for other cargo), 0 otherwise||no
|-
|09||W||{{ottdp|0.6|2.0}}||Speed in mph*1.6 (see below)||no
|-
|0B||W||{{ottdp|0.6|2.0}}||Power (0 for wagons)||should be zero
|-
|0D||B||{{ottdp|0.6|2.0}}||Running cost factor (0 for wagons)||should be zero
|-
|0E||D||{{ottdp|0.6|2.0}}||Running cost base, see below||should be zero
|-
|12||B||{{ottdp|0.6|2.0}}||Sprite ID (FD for new graphics)||yes
|-
|13||B||{{ottdp|0.6|2.0}}||Dual-headed flag; 1 if dual-headed engine, 0 otherwise||should be zero also for front
|-
|14||B||{{ottdp|0.6|2.0}}||Cargo capacity||yes
|-
|15||B||{{ottdp|0.6|2.0}}||Cargo type, see [[CargoTypes]]<br/>
{{grfTill|7}} For GRF version 7 and below: Type B 'cargo slot'<br/>
{{grfFrom|8}} For GRF version 8 and above: Type A '(translated) cargo bit'
||yes
|-
|16||B||{{ottdp|0.6|2.0}}||Weight in tons||should be zero
|-
|17||B||{{ottdp|0.6|2.0}}||Cost factor||should be zero
|-
|18||B||{{ottdp|<0.7|2.0}}<ref>This property is not used by OpenTTDs NoAI API.</ref>||Engine rank for the AI (AI selects the highest-rank engine of those it can buy)||no
|-
|19||B||{{ottdp|0.6|2.0}} {{grfFrom|1}}||Engine traction type (see below)||no
|-
|1A||B/B*<ref>{{ottdp|0.7|no|ottdrev=r13831}} Since OpenTTD r13831 this is an extended byte.</ref>||{{ottdp|0.6|2.0}} {{grfFrom|1}}||Not a property, but an action: sort the purchase list.||no
|-
|1B||W||{{ottdp|0.6|2.5}} {{grfFrom|6}}||Power added by each wagon connected to this engine, see below||should be zero
|-
|1C||B||{{ottdp|0.6|2.5}} {{grfFrom|6}}||Refit cost, using 50% of the [[BaseCosts|purchase price cost base]]||yes
|-
|1D||D||{{ottdp|0.6|2.5}} {{grfFrom|6}}||Bit mask of cargo types available for refitting, see column 2 (bit value) in [[CargoTypes]]||yes
|-
|1E||B||{{ottdp|0.6|2.5}} {{grfFrom|6}}||Callback flags bit mask, see below||yes
|-
|1F||B||{{ottdp|0.6|2.5|ttdprev=alpha 19}}||Coefficient of tractive effort||should be zero
|-
|20||B||{{ottdp|1.1|2.5|ttdprev=alpha 27}}||Coefficient of air drag||should be zero
|-
|21||B||{{ottdp|0.6|2.0}} {{grfFrom|2}}||Make vehicle shorter by this amount, see below||yes
|-
|22||B||{{ottdp|0.6|2.5}} {{grfFrom|6}}||Set visual effect type (steam/smoke/sparks) as well as position, see below||yes
|-
|23||B||{{ottdp|0.6|2.5}} {{grfFrom|6}}||Set how much weight is added by making wagons powered (i.e. weight of engine), see below||should be zero
|-
|24||B||{{ottdp|0.6|2.5|ttdprev=alpha 44}}||High byte of vehicle weight, weight will be prop.24*256+prop.16||should be zero
|-
|25||B||{{ottdp|0.6|2.5|ttdprev=alpha 44}}||User-defined bit mask to set when checking veh. var. 42||yes
|-
|26||B||{{ottdp|0.6|2.5|ttdprev=alpha 44}}||Retire vehicle early, this many years before the end of phase 2 (see [[Action0General]])||no
|-
|27||B||{{ottdp|0.6|2.5|ttdprev=alpha 58}}||Miscellaneous flags||partly
|-
|28||W||{{ottdp|0.6|2.5|ttdprev=alpha 58}}||Refittable cargo classes||yes
|-
|29||W||{{ottdp|0.6|2.5|ttdprev=alpha 58}}||Non-refittable cargo classes||yes
|-
|2A||D||{{ottdp|0.6|2.5|ottdrev=r7191|ttdprev=r1210}}||Long format introduction date||no
|-
|2B||W||{{ottdp|1.2|no|ottdrev=r22713}}||Custom cargo ageing period||yes
|-
|2C||B n*B||{{ottdp|1.2|no|ottdrev=r23291}}||List of always refittable cargo types||yes
|-
|2D||B n*B||{{ottdp|1.2|no|ottdrev=r23291}}||List of never refittable cargo types||yes
|}
<references/>

= Description =

== Track type (05) ==
Set track type of vehicle: 0 = rail, 1 = monorail, 2 = maglev. For setting the appropriate traction type, see [[Action0Trains#Engine traction type 19|prop19]].

{{ottdp|1.0|no}} In OpenTTD, if a [[Action0Railtypes|rail type]] translation table is loaded, this property is an index into the table instead.

== Speed (09) ==

Train speed is in units of mph*1.6, i.e. approximately km/h.

For wagons, this value is only used if the "wagonspeedlimit" switch is on, and it limits the speed of the train to that of the lowest wagon speed.  This limit is ignored for wagons with a livery override for the current train, so that train sets always get their max speed from the engine's max speed.

For wagons, a value of 0 means "default" (which depends on cargo type and date of introduction), and FFFF means no limit.

== Power (0B) ==

The power of the engine, in HP.

A value of 0 means that the vehicle will be a wagon, otherwise it will be an engine.

== Running cost base (0E) and factor (0D) ==

TTD calculates all costs by multiplying a 32-bit [[BaseCosts|base amount]] with an 8-bit factor.  The base amount is changed according to inflation, whereas the factor remains constant.

For the running costs of train vehicles, the following base amounts are available depending on the vehicle type (the value here is a pointer into TTD's memory where the actual amount is stored):

{| |-
!Type!!Value!!in little-endian notation
|-
|Steam engines||4C30||30 4C 00 00
|-
|Diesel engines||4C36||36 4C 00 00
|-
|Electric engines||4C3C||3C 4C 00 00
|-
|Wagons||0||00 00 00 00
|}

Theoretically, you could use pointers to other base amounts available in TTD, but these are the numbers TTD uses for train vehicles.

The following are some real values for maintenance costs depending on the setting of the above two factors.  This value is correct for medium difficulty, but increases and decreases for hard and easy difficulties respectively.  These are the costs of a new game starting in 1921, because they obviously increase with inflation over time (unless noinflation is turned on).

'''Running cost base 4C30 (steam)'''

{| |-
!Running cost factor!!Maintenance cost
|-
|01||$ 42
|-
|10||$ 700
|-
|20||$ 1.400
|-
|80||$ 5.600
|-
|A0||$ 7.000
|-
|FF||$ 11.112
|}

'''Running cost base 4C36 (diesel)'''

{| |-
!Running cost factor!!Maintenance cost
|-
|01||$ 40
|-
|10||$ 650
|-
|20||$ 1.300
|-
|80||$ 5.200
|-
|A0||$ 6.500
|-
|FF||$ 10.318
|}

'''Running cost base 4C3C (electric)'''

{| |-
!Running cost factor!!Maintenance cost
|-
|01||$ 36
|-
|10||$ 600
|-
|20||$ 1.200
|-
|80||$ 4.800
|-
|A0||$ 6.000
|-
|FF||$ 9.524
|}

== Cost factor (17) ==

The cost factor is a bit-coded value which determines how expensive an engine is. There is no distinction between steam, diesel or electric engines, they all use the same cost factor. The table below gives you some values to use for finding the right price for your engines.

{| |-
!Cost factor!!Price
|-
|01||$ 3.124
|-
|10||$ 50.000
|-
|20||$ 100.000
|-
|80||$ 400.000
|-
|A0||$ 500.000
|-
|FF||$ 796.874
|}

== Engine traction type (19) ==

This sets the traction type of a train engine, i.e. whether it is powered by steam, diesel, electric, monorail or maglev technology.  It also sets the corresponding sound effect of the engine, and if property 22 is not set, the visual effect as well.

The following ranges are available (and it does not matter which value you pick):

{| |-
!Values!!Traction type
|-
|00..07||Steam
|-
|08..27||Diesel
|-
|28..31||Electric
|-
|32..37||Monorail
|-
|38..41||Maglev
|}
Default value is 00, i.e. steam. For setting the appropriate track type, see [[Action0Trains#Track type 05|prop05]].

{{ottdp|1.1|no}} In OpenTTD, if a [[Action0Railtypes|rail type]] translation table is loaded, setting this property does NOT alter the track type.

== Sort vehicle list (1A) ==

This is not a property as such, but an action.  It forces TTDPatch to shuffle the vehicle this "property" is being set for in front of the vehicle with the given value of the property.  The order of this list is only used in the train purchase window.

For example, setting prop. 1A for vehicle 09 to a value of 07 would lead to the following internal list: ... 05 06 09 07 08 0A 0B ...

This property can not simply be overwritten, because the list is already shuffled when trying to do so.

{{ottdp|no|2.0}} It is possible to reset the list to its original order with a special action 0 that has num-info set to 0, and only sets property 1A for trains:
<pre>00 00 01 00 00 1A</pre>

Resetting the list should however only be done by sets that contain replacements for all train vehicles.

{{ottdp|0.7|no|ottdrev=r13831}} This property is an extended byte in OpenTTD since r13831!

== Powered train wagons (1B and 23, see also 22) ==

Normally, train wagons are unpowered in TTD, and if you set property 0B to a non-zero value, they become engines instead.  Therefore, to model real-life trains where wagons have power, a different mechanism is needed.
To make train wagons powered, you set property 1B of the '''engine''' instead of the wagon. This determines how much power each wagon adds to the train when attached to this engine. This only applies to wagons with a [[Action3|graphics override]] for this engine as well.  This means that for example passenger wagons (with an override) will add power, but coal wagons (with no override) will not.

In addition to adding power, these wagons are also heavier by the amount set in property 23.

== Refit cost (1C) ==

Refit cost, using 50% of the [[BaseCosts|purchase price cost base]]. This property can be overridden by callback 15E.

{{ottdp|1.2|no|ottdrev=r23087}} If the refit cost factor is set to zero and bit 4 of the miscellaneous flags (27) is set, auto-refitting is allowed.

== Callbacks (1E) ==
For trains, the following [[callbacks]] have to be enabled by setting the corresponding bit in property 1E (certain other, not as frequently used callbacks are available without setting a bit here):

{| |-
!Bit!!Value!!Variable 0C value!!Callback
|-
|0||1||10||Powered wagons and visual effect
|-
|1||2||11||Wagon length
|-
|2||4||12||Load amount
|-
|3||8||15||Set refitted capacity
|-
|4||10||16||Build articulated engines
|-
|5||20||19||show a suffix after the cargo type name
|-
|6||40||2D||Select color mapping for vehicle
|-
|7||80||33||Sound effect callbacks
|}

Bit is the bit you have to set, you do this by adding all the values for all the bits. Variable 0C value is what variable 0C will be set to, for checking it in the VarAction2 for callbacks.

These callbacks do not need a bit to activate them, they are always active and will be used if defined in the action 3/action 2 chain.
{| |-
!Variable 0C value!!Callback
|-
|1D||Can wagon be attached
|-
|23||Additional text in purchase screen
|-
|31||Start/stop check
|-
|32||32-day callback
|-
|36||Change Vehicle Properties
|-
|15E||Refit cost
|}

== Coefficient of tractive effort (1F) ==

This cofficient sets what fraction of the vehicle weight is equal to the maximum tractive effort.  This includes the effect of having some unpowered axles, as well as the coefficient of friction that is available.

Theoretically, this value should be calculated by taking the ratio of adhesive weight W<sub>adh</sub> (i.e. the vehicle weight that rests on powered axles) times the coefficient of friction µ between the wheels and the rails to the total vehicle weight W, times 255, and convert to hex:

prop. 1F = HEX ((W<sub>adh</sub> * µ / W) * 255)

With prop. 1F having a value of FF, the tractive effort is equal to the vehicle weight, for 80, it is half, and so on. If not set, a default of 4C is used, for a fraction of 0.30, corresponding to Wadh=W and a coefficient of friction of 0.30, which is the value used by the patch before TTDPatch 2.0.1 alpha 19.

Sometimes you know the real-life tractive effort instead of adhesive weight and coefficient of friction. To help calculating prop. 1F in that case, here's a small example using the NS 1600 (Electric) with a mass of 84 tons and real-life tractive effort (TE<sub>real</sub>) of 259 kN. To quickly find the value for property 1F you fill in the following formula:

prop. 1F = HEX ((TE<sub>real</sub> / (Mass * g) * 255)

That may look confusing but you already know all variables:

prop. 1F = HEX ((259 / (84 * 9.8) * 255)

prop. 1F = HEX (0.3146 *255) = HEX(80.229)

HEX calculations only work with figures in the natural domain: each figure has to be a positive and round figure. Therefore the value you convert to HEX isn't 80.229 but 80:

HEX 80 = 50

Property 1F for the NS 1600 (Electric) would then be: 1F 50.

== Coefficient of air drag (20) ==

This property sets the air drag coefficient c2 used for the realistic acceleration model, from 01 (no airdrag) to FF (most air drag) in arbitrary units. 00 means to use the default value that depends on the top speed (to simulate the fact that high-speed engines are more streamlined).

The default values are the following:

{| |-
!top speed (mph/1.6)!! <16!! 16!! 24!! 32!! 48!! 64!! 96!! 128!! 192!! 256!! ...
|-
|c2|| 192|| 128|| 96|| 64|| 48|| 32|| 24|| 16|| 12|| 8
|}

For higher speeds, the series is continued in the same manner.

Air drag in Newtons will then be c2*v*v with v in m/s, although it is probably futile to attempt to make c2 a realistic number due to the lack of TTD's consistent scaling. If a train doesn't reach its historical top speed, you might try setting the value of prop. 20 one or two steps lower than the default above, otherwise it's probably a good idea to leave it at the default.

== Shorter train vehicles (21) ==

This property reduces the length of train vehicles, in units of 1/8th (12.5%). The value 00 means the vehicle has the full length, 01 means shorter by 1/8th (12.5%), up to 05=shorter by 5/8ths (62.5%). Larger numbers will not work properly
<ref>{{ottdp|1.0|no|ottdrev=r15793}} This restriction has been removed in OpenTTD r15793. Every vehicle can have a length between 1/8 and 8/8 independent of its position in the chain.</ref>,
except at the end of the train
<ref>{{ottdp|<1.0|}} This means that it is only safe to use values larger than 05 in the length callback making sure that they are only returned for the very last vehicle in the train. Otherwise the train will occasionally fall apart, with the wagons after the shortest one stopping to move.</ref>. The vehicle length is set whenever it leaves a depot. This property does not work for the first vehicle in a train (i.e. the engine).

<references/>

== Visual effects and wagon power (22) ==

By default, the visual effect of train engines is determined by the traction type (property 19). With this option you can change the type of effect as well as the position of it relative to the vehicle. (Note: for TTDPatch and OpenTTD up to r21229 only the positioning of steam actually works. For {{ottdp|1.1|no|ottdrev=r21230}} positioning diesel smoke and electric sparks works as well) The position of the effect provides a range from 0 to F that is added to the type of the effect.

Position 0 corresponds to a point half a vehicle length ahead of the vehicle, 4 is the front of the vehicle, 8 the middle, C the end and F is a half length behind the vehicle. Intermediate values are in-between.

Additionally, this property can be used to disable powered wagons of this type, although that is usually done with [[Callbacks#Visual_effect_and_wagon_power_.2810.29| callback 10]] instead (which has the same meaning as prop. 22, but is more flexible).

{| |-
!Range !!Effect type
|-
|00..0F||Use the default effect type, but reposition it. For engines this is defined via property 19, wagons have no default effect.
|-
|10..1F||Steam puffs
|-
|20..2F||Diesel fumes
|-
|30..3F||Electric sparks
|-
|40||Disable visual effect
|-
|41..7F||{{ottdp|1.5|no|ottdrev=r26747}} Create effects with [[Callbacks#Advanced_effect_creation_.28160.29|Callback 160]] using one of these spawning models:
* 41 Steam: Gradually less effects when approaching max speed
* 42 Diesel: Effect proportional to acceleration, no effect when idling at top speed
* 43 Electric: Random effect, gradually less likely when approaching max spped
* 44-7F Reserved
|-
|80+00..80+7F||Same as 00..7F above, but disable wagon power
|}

For example, 28 would make the wagon powered and emit diesel fumes, but 80+28 = A8 would only emit the diesel fumes without adding power.

== Miscellaneous flags (27) ==

This is a bit mask, with the following bits:

{| |-
!Bit!! Value!! Version !!Meaning
|-
|0|| 1||{{ottdp|0.6|2.5}}|| Vehicle tilts in curves, and thus gets speed bonus <ref>The tilting speed bonus only applies if all vehicles in the train have this bit set. In TTDPatch it requires the "curves" switch to be on. For realistic curves, it gives the train two free curving pieces with no speed decrease, and for other settings, it increases the curves setting by one (0->1, 1->2, 2->2). In OpenTTD, the curve speed limit increases by 20% if 'realistic' acceleration is enabled, else there is no effect.
</ref>
|-
|1|| 2||{{ottdp|0.6|2.5}}|| Uses two company colors
|-
|2|| 4||{{ottdp|0.6|2.5}}|| Vehicle is a multiple unit (DMU/EMU), for colour selection
|-
|3|| 8||{{ottdp|1.1|no|ottdrev=r21966}}|| Vehicle can be flipped around in the depot <ref>When you enable flipping of a vehicle in a depot you must make sure that the graphics are correctly aligned when flipped as well. Especially in the case of shortened vehicles. For multiheaded or articulated vehicles the flipping bit has no effect; these vehicles are never to be flipped around in the depot.
<br>
Prior to {{ottd|1.1|r21966}} all non-multiheaded/non-articulated vehicles would be able to flip around in the depot. As such this disables a "feature" in OpenTTD, but often it makes no sense to flip vehicles around (symetric vehicles) or the graphics are wrong (most shortened vehicles), and thus only enabling this when the NewGRF developer says it is possible is better.
</ref>
|-
|4|| 10||{{ottdp|1.2|no|ottdrev=r23087}}|| Auto-refitting is enabled for refits where callback 15E allows it or prop 1C specifies zero cost
|-
|5|| 20||{{ottdp|1.2|no|ottdrev=r23861}}|| Use cargo multiplier for default cargo (and load amount). See page about [[VehicleRefitting#Misc._vehicle_flag_5_.27use_of_capacity_multiplier_for_default_cargo.27_set|vehicle refitting]].
|-
|6|| 40||{{ottdp|1.3|no|ottdrev=r24124}}|| Disable breakdown smoke effect.
|}

<references />

== Cargo classes (28, 29) ==

To make vehicle sets more compatible with future new cargo definitions, these two properties allow vehicles to define what type of cargo they should be refittable to. A wagon will be refittable to all cargo types that match any of the classes set in prop. 28 except for the ones that match any of the classes set in prop. 29. In addition, afterwards those cargo types listed in prop. 1D will be toggled. In terms of logic, it is

Refit list = (cargos from prop. 28 AND NOT cargos from prop. 29) XOR cargos from prop. 1D

This means, if a cargo type is in the list because it matches prop. 28 but not prop 29, having the respective bit set in prop. 1D will disable it again. Conversely, if the cargo type is not in the list, the bit in prop. 1D will add it. This way, if props. 28/29 are unset, prop. 1D will retain the original meaning, but it is still able to selectively add or remove certain cargo types even if props. 28/29 are used.

As a consequence, you have both full control over the cargo types that you know of (using prop. 1D), and those you don't know of yet (using props. 28/29). Leave the bits for cargos that you don't know of unset in prop. 1D, and set/clear the bits for known cargos to add/remove them from the list as appropriate.

{{ottd|1.2|r23291}} It is recommended to use properties 2C and 2D instead of property 1D, as property 1D behaves badly if the cargo classes of a cargo are ever changed.

The class list is a bit mask. See the action0 cargos page for bits and classes defined so far.

Take a look at [[Action0Cargos#Cargo classes 16|Action0 for cargos]] for the classes defined so far.

Note that cargo types may belong to several classes. This is the reason for making two properties, an additive and a subtractive one, because this way a vehicle can be specified to be refittable to, for example, all express cargo that does not require refrigeration (i.e., from the default cargos, no food).
For the cargo types added in this way, the vehicle will probably have no specific graphics (in [[Action3|action 3]]) to show the cargo load.  In this case, the default will be used, which should therefore be sufficiently generic-looking if possible. However, using [[VarAction2Vehicles#Vehicle cargo info 47|vehicle variable 47]] you can at least select the graphics most appropriate for the cargo type's class.
About the interaction with other properties take a look at the summary page about [[VehicleRefitting|vehicle refitting]].

Disclaimer: there is no guarantee that classes won't vary over time or between sets. The classes of a cargo may change between different versions of a specific industry/cargo newgrf, or different classes may be set for the same cargo label by different industry/cargo newgrfs. Feel free to use classes in your set for conveniently refitting to cargos, but if you - the vehicle author - care about specific cargos being transported in specific vehicles, use label based refits (changing labels without a very good reason is considered to be bad practice).

== Long format introduction date (2A) ==

Set the vehicle introduction date, in days since the year 0. This takes account of leap years; dividable by 4, but not 100 unless 400. A start date of 1920-01-01 is obtained with a value of 701265 (51 B3 0A 00). This property must be set after property 00 to take effect.

{{ottdp|no|}} In TTDPatch, dates after 2044 will be limited to 2044.

== Custom cargo ageing period (2B) ==

This property allows to modify the period in ticks after which cargo carried by the vehicle is aged. By default, cargo is aged every 185 ticks. A value of 0 disables ageing of cargo. This property can be modified via [[Callbacks#Change_vehicle_properties_.2836.29|callback 36]].

== List of always refittable cargo types (2C, 2D) ==

These two properties allows to unconditionally include or exclude cargo types for refittability independent of any of the other refit properties or the cargo classes. If you specify a cargo type that is not available, the cargo type will be silently ignored.

The format for both properties is:

<pre>2C/2D <nvar> (<Index into cargo type table>){n}</pre>

That is you give the number of cargos in a single byte followed by a list of that length of indexes into the cargo translation table ([[CargoTypes|Type A]]).

= Example =

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

(A basic version)

<pre>10 * 14  00 00 03 01 02 09 C0 00 0B D8 0E 12 FD</pre>

{| |-
!'''Bytes'''!!'''Meaning'''
|-
|10||<Sprite-number>
|-
|14||<Length>: of the action in bytes; start counting at 0 (<action>)
|-
|00||<action>: sets this pseudo-sprite to function as action 0
|-
|00||<Feature>: In this case Train
|-
|03||<Num-props>: 3 Properties to change
|-
|01||<Num-info>: 1 vehicle ID to make changes to
|-
|02||<ids...>: vehcile ID (02 - Ploddyphut Choo-Choo)
|-
|||'''Properties'''
|-
|09||<Speed>
|-
|C0 00||<Value>: Value for Speed (192 Km/h)
|-
|0B||<Power>
|-
|D8 0E||<value>: value for Power (3800 HP)
|-
|12||<Sprite ID>
|-
|FD||<value>: FD for new graphics
|}
Since nfo version 7, so-called [[GRFActionsDetailed#Byte order|"escape sequences"]] have been introduced in an attempt to offer a more human-readable form.

Below is the same example as above, with escape sequences being used:

<pre>-1 * 0 00 00 \b3 01 \b*2 // \b<number of props to change> \b*<vehicle ID>

       09 \w192 // value for speed (192 Km/h)

       0B \w3800 // value for power (3800 hp)

       12 FD // use new graphics</pre>

NML:Language files

2014-12-07T15:46:34Z

The Dude: Removed the hex code, as it was misleading to some people. Added coloured image for colours from openttd pallete

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

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

Action4

2014-12-07T15:42:15Z

The Dude: Added the colour itself as image

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

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

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

== Syntax ==

The data looks as follows:

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

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

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

== Descriptions ==

=== Sprite-number ===

This is just the number you are at.

=== Length ===

Count the number of bytes in this action.

=== Feature ===

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

{|- |
!Value!![[Features|Feature]]
|-
|00||Trains
|-
|01||Road Vehicles
|-
|02||Ships
|-
|03||Aircraft
|-
|04||Stations
|-
|07||Houses
|-
|0A||Industries
|-
|0B||Cargos
|-
|0D||Airports
|-
|0F||Objects
|-
|10||Railtypes
|-
|48||Original strings; see [[TextIDs]] for a list of TTD's text IDs.
|}

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

{{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 newobjects and several callbacks. Some callbacks as well as newobjects support IDs up to D3FF.
|-
|D4xx||'''Never use in Action4''', only for displaying textids in range D000-D3FF (grf specific), see [[TextIDs]]
|-
|D8xx||'''Never use in Action4''', only usable in Action0 features, see [[TextIDs]]
|-
|DCxx||Set miscellaneous persistent GRF texts. Unlike the D0xx GRF texts, these IDs can be used to set properties. The text ID must be set before any [[Action0/Houses|action 0]] references it.
|}

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

=== text ===

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

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

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

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

Action4

2014-12-07T14:57:27Z

The Dude: Added missing colour (8F) and the colour names correspond to the ones from nml wiki

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

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

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

== Syntax ==

The data looks as follows:

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

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

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

== Descriptions ==

=== Sprite-number ===

This is just the number you are at.

=== Length ===

Count the number of bytes in this action.

=== Feature ===

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

{|- |
!Value!![[Features|Feature]]
|-
|00||Trains
|-
|01||Road Vehicles
|-
|02||Ships
|-
|03||Aircraft
|-
|04||Stations
|-
|07||Houses
|-
|0A||Industries
|-
|0B||Cargos
|-
|0D||Airports
|-
|0F||Objects
|-
|10||Railtypes
|-
|48||Original strings; see [[TextIDs]] for a list of TTD's text IDs.
|}

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

{{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 newobjects and several callbacks. Some callbacks as well as newobjects support IDs up to D3FF.
|-
|D4xx||'''Never use in Action4''', only for displaying textids in range D000-D3FF (grf specific), see [[TextIDs]]
|-
|D8xx||'''Never use in Action4''', only usable in Action0 features, see [[TextIDs]]
|-
|DCxx||Set miscellaneous persistent GRF texts. Unlike the D0xx GRF texts, these IDs can be used to set properties. The text ID must be set before any [[Action0/Houses|action 0]] references it.
|}

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

=== text ===

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

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

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

The following colour codes are available for use:

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

==Example==

NML:Main

2014-12-05T20:57:32Z

The Dude:

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

;[[NML:Preface |Preface]]
;[[NML:changes 0.3|Changes between NML 0.2 and head / 0.3]]
;[[NML:changes 0.4|Changes between NML 0.3 and head / 0.4]]
;[[NML:Getting started|Getting started]]
;[[NML:Graphic files|Graphics files]]

;[[NML:Block syntax|Language structure and block syntax]]
*[[NML:GRF|GRF]] and its parameters
*[[NML:Item|Item]] (Properties, graphics, livery overrides)

*;Defining sprites:
**[[NML:Realsprites|Realsprites]]
**[[NML:Template|Template]]
**[[NML:Base Graphics|Base Graphics]]
**[[NML:Spriteset|Spriteset]]
**;Replacing sprites:
***[[NML:Replace TTD sprites|Replace TTD sprites]]
***[[NML:Replace new sprites|Replace new sprites]]
***[[NML:Add font glyphs|Add font glyphs]]
***[[NML:Alternative sprites|Alternative sprites]] (32bpp, zoom levels)
**;Aranging and grouping sprites:
***[[NML:Spritegroup|Spritegroup]] (Vehicles)
***[[NML:Spritelayout|Spritelayout]] (Houses, industries, stations, airports, objects)
***[[NML:Recolour sprites|Recolour sprites]]

*;Flow control
**[[NML:Tilelayout|Tilelayout]]
**[[NML:Switch|Switch]]
**[[NML:Produce|Produce]]
**[[NML:Random switch|Random switch]]

*;Global scope
**[[NML:Cargotable|Cargotable]]
**[[NML:Railtypetable|Railtypetable]]
**[[NML:Snow line|Snow line]]
**[[NML:Setting base costs|Setting base costs]]
**[[NML:Parameter assignment|Parameter assignment]]
**[[NML:If|If/else]]
**[[NML:While|While]]

*;Interaction with other grfs
**[[NML:Error|Error]]
**[[NML:Disable items|Disable items]]
**[[NML:Deactivate other NewGRFs|Deactivate other NewGRFs]]
**[[NML:Testing for other NewGRFs|Testing for other NewGRFs]]
**[[NML:Overriding vehicles in other NewGRFs|Overriding vehicles in other NewGRFs]]

*;Misc
**[[NML:Town names|Town names]]
**[[NML:Town names parts|Town names parts]]

;[[NML:Units|Units]]
;[[NML:Expressions|Expressions]]
*[[NML:Elementary values|Elementary values]]
*[[NML:Builtin functions|Builtin functions]]
;[[NML:Language files|Language files]]
;[[NML:Properties and variables and callbacks|Lists of properties, variables and callbacks]]

{|
!Type
!Properties
!Variables
!Callbacks
!Feature
|-
|[[NML:General|General]] || || [[NML:General#General variables|variables]] || || FEAT_GLOBALVARS
|-
|[[NML:Vehicles|Vehicles]] || [[NML:Vehicles#Properties common to all vehicle types|common properties]] || [[NML:Vehicles#Vehicle variables|variables]] || [[NML:Vehicles#Vehicle callbacks|callbacks]] ||
|-
| || [[NML:Vehicles#Train properties|train properties]] || || || FEAT_TRAINS
|-
| || [[NML:Vehicles#Road vehicle properties|road vehicle properties]] || || || FEAT_ROADVEHS
|-
| || [[NML:Vehicles#Ship properties|ship properties]] || || || FEAT_SHIPS
|-
| || [[NML:Vehicles#Aircraft properties|aircraft properties]] || || || FEAT_AIRCRAFT
|-
|[[NML:Stations|Stations]] || [[NML:Stations#Station properties|properties]] || [[NML:Stations#Station variables|variables]] || [[NML:Stations#Station callbacks|callbacks]] || FEAT_STATIONS
|-
|[[NML:Canals|Canals]] || [[NML:Canals#Canal properties|properties]] || [[NML:Canals#Canal variables|variables]] || [[NML:Canals#Canal callbacks|callbacks]] || FEAT_CANALS
|-
|[[NML:Bridges|Bridges]] || [[NML:Bridges#Bridge properties|properties]] || [[NML:Bridges#Bridge variables|variables]] || [[NML:Bridges#Bridge callbacks|callbacks]] || FEAT_BRIDGES
|-
|[[NML:Towns|Towns]] || || || ||
|-
|[[NML:Houses|Houses]] || [[NML:Houses#House properties|properties]] || [[NML:Houses#House variables|variables]] || [[NML:Houses#House callbacks|callbacks]] || FEAT_HOUSES
|-
|[[NML:Industries|Industries]]|| || [[NML:Industries#Common variables|common variables]] || ||
|-
| || [[NML:Industries#Industry properties|industry properties]] || [[NML:Industries#Industry variables|industry variables]] || [[NML:Industries#Industry callbacks|industry callbacks]] || FEAT_INDUSTRIES
|-
| || [[NML:IndustryTiles#Industry tile properties|tile properties]] || [[NML:IndustryTiles#Industry tile variables|tile variables]] || [[NML:IndustryTiles#Industry tile callbacks|tile callbacks]] || FEAT_INDUSTRYTILES
|-
|[[NML:Cargos|Cargos]] || [[NML:Cargos#Cargo properties|properties]] || [[NML:Cargos#Cargo variables|variables]] || [[NML:Cargos#Cargo callbacks|callbacks]] || FEAT_CARGOS
|-
|[[NML:Airports|Airports]] || [[NML:Airports#Airport properties|properties]] || [[NML:Airports#Airport variables|variables]] || [[NML:Airports#Airport callbacks|callbacks]] || FEAT_AIRPORTS
|-
| || [[NML:Airports#Airport tile properties|tile properties]] || [[NML:Airports#Airport tile variables|tile variables]] || [[NML:Airports#Airport tile callbacks|tile callbacks]] || FEAT_AIRPORTTILES
|-
|[[NML:Objects|Objects]] || [[NML:Objects#Object properties|properties]] || [[NML:Objects#Object variables|variables]] || [[NML:Objects#Object callbacks|callbacks]] || FEAT_OBJECTS
|-
|[[NML:Railtypes|Railtypes]] || [[NML:Railtypes#Railtype properties|properties]] || [[NML:Railtypes#Railtype variables|variables]] || [[NML:Railtypes#Railtype callbacks|callbacks]] || FEAT_RAILTYPES
|-
|Signals|| || || || FEAT_SIGNALS
|}

;[[NML:Warnings|Compiler Warnings]]
;[[NML:Additional references|Additional references]]
*[[NML:Animation speed|Animation speed]]
*[[NML:Default industries|Default industries]]
*[[NML:Default industry tiles|Default industry tiles]]
*[[NML:Base cost table|Base cost table]]
*[[NML:List of sound effects|List of sound effects]]
*[[NML:List of default vehicle IDs|List of default vehicle IDs]]
*[[NML:List of default house properties|List of default house properties]]
*[[NML:List of town zones|List of town zones]]
*[[NML:List of tile classes|List of tile classes]]
*[[NML:List of default colour translation palettes|List of default colour translation palettes]]
*[[NML:List of direction constants|List of direction constants]]
*[[NML:List of tile slopes|List of tile slopes]]
*[[NML:List of tiles|List of tiles]]
*[[NML:Default TTD strings|Default TTD strings]]
*[[NML:Deprecated syntax|Deprecated syntax]]
;[[NML:NewGRF compatibility|NewGRF compatibility]]
;[[NML:Old style callbacks|Old-style callbacks]]

[[NML:Manual of style|Manual of style]]

NML:Language files

2014-12-05T19:39:45Z

The Dude: /* String codes */

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

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

Language files MUST have the extension <code style="color:darkgreen">.lng</code><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
!Hex
|-
| ||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 || || 88
|-
|SILVER || switch to silver text || || 89
|-
|GOLD || switch to golden text || || 8A
|-
|RED || switch to red text || || 8B
|-
|PURPLE || switch to purple text || || 8C
|-
|LTBROWN || switch to light brown text || || 8D
|-
|ORANGE || switch to orange text || || 8E
|-
|GREEN || switch to green text || || 8F
|-
|YELLOW || switch to yellow text || || 90
|-
|DKGREEN || switch to dark green text || || 91
|-
|CREAM || switch to cream-coloured text || || 92
|-
|BROWN || switch to brown text || || 93
|-
|WHITE || switch to white text || || 94
|-
|LTBLUE || switch to light blue text || || 95
|-
|GRAY || switch to gray text || || 96
|-
|DKBLUE || switch to dark blue text || || 97
|-
|BLACK || switch to black text || || 98
|}

== 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
|-
|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:List of sound effects

2014-11-22T12:18:00Z

The Dude:

{{NMLNavAdditionalreferences}}
{|
|+ Table of OpenTTD default sound effects
!ID (dec)
!ID (hex)
!Name
|-
| 0 || 0 || SOUND_SPLAT
|-
| 1 || 1 || SOUND_FACTORY_WHISTLE
|-
| 2 || 2 || SOUND_TRAIN
|-
| 3 || 3 || SOUND_TRAIN_THROUGH_TUNNEL
|-
| 4 || 4 || SOUND_SHIP_HORN
|-
| 5 || 5 || SOUND_FERRY_HORN
|-
| 6 || 6 || SOUND_PLANE_TAKE_OFF
|-
| 7 || 7 || SOUND_JET
|-
| 8 || 8 || SOUND_TRAIN_HORN
|-
| 9 || 9 || SOUND_MINING_MACHINERY
|-
| 10 || A || SOUND_ELECTRIC_SPARK
|-
| 11 || B || SOUND_STEAM
|-
| 12 || C || SOUND_LEVEL_CROSSING
|-
| 13 || D || SOUND_VEHICLE_BREAKDOWN
|-
| 14 || E || SOUND_TRAIN_BREAKDOWN
|-
| 15 || F || SOUND_CRASH
|-
| 16 || 10 || SOUND_EXPLOSION
|-
| 17 || 11 || SOUND_BIG_CRASH
|-
| 18 || 12 || SOUND_CASHTILL
|-
| 19 || 13 || SOUND_BEEP
|-
| 20 || 14 || SOUND_MORSE
|-
| 21 || 15 || SOUND_SKID_PLANE
|-
| 22 || 16 || SOUND_HELICOPTER
|-
| 23 || 17 || SOUND_BUS_START_PULL_AWAY
|-
| 24 || 18 || SOUND_BUS_START_PULL_AWAY_WITH_HORN
|-
| 25 || 19 || SOUND_TRUCK_START
|-
| 26 || 1A || SOUND_TRUCK_START_2
|-
| 27 || 1B || SOUND_APPLAUSE
|-
| 28 || 1C || SOUND_OOOOH
|-
| 29 || 1D || SOUND_SPLAT
|-
| 30 || 1E || SOUND_SPLAT_2
|-
| 31 || 1F || SOUND_JACKHAMMER
|-
| 32 || 20 || SOUND_CAR_HORN
|-
| 33 || 21 || SOUND_CAR_HORN_2
|-
| 34 || 22 || SOUND_SHEEP
|-
| 35 || 23 || SOUND_COW
|-
| 36 || 24 || SOUND_HORSE
|-
| 37 || 25 || SOUND_BLACKSMITH_ANVIL
|-
| 38 || 26 || SOUND_SAWMILL
|-
| 39 || 27 || SOUND_GOOD_YEAR
|-
| 40 || 28 || SOUND_BAD_YEAR
|-
| 41 || 29 || SOUND_RIP
|-
| 42 || 2A || SOUND_EXTRACT_AND_POP
|-
| 43 || 2B || SOUND_COMEDY_HIT
|-
| 44 || 2C || SOUND_MACHINERY
|-
| 45 || 2D || SOUND_RIP_2
|-
| 46 || 2E || SOUND_EXTRACT_AND_POP
|-
| 47 || 2F || SOUND_POP
|-
| 48 || 30 || SOUND_CARTOON_SOUND
|-
| 49 || 31 || SOUND_EXTRACT
|-
| 50 || 32 || SOUND_POP_2
|-
| 51 || 33 || SOUND_PLASTIC_MINE
|-
| 52 || 34 || SOUND_WIND
|-
| 53 || 35 || SOUND_COMEDY_BREAKDOWN
|-
| 54 || 36 || SOUND_CARTOON_CRASH
|-
| 55 || 37 || SOUND_BALLOON_SQUEAK
|-
| 56 || 38 || SOUND_CHAINSAW
|-
| 57 || 39 || SOUND_HEAVY_WIND
|-
| 58 || 3A || SOUND_COMEDY_BREAKDOWN_2
|-
| 59 || 3B || SOUND_JET_OVERHEAD
|-
| 60 || 3C || SOUND_COMEDY_CAR
|-
| 61 || 3D || SOUND_ANOTHER_JET_OVERHEAD
|-
| 62 || 3E || SOUND_COMEDY_CAR_2
|-
| 63 || 3F || SOUND_COMEDY_CAR_3
|-
| 64 || 40 || SOUND_COMEDY_CAR_START_AND_PULL_AWAY
|-
| 65 || 41 || SOUND_MAGLEV
|-
| 66 || 42 || SOUND_LOON_BIRD
|-
| 67 || 43 || SOUND_LION
|-
| 68 || 44 || SOUND_MONKEYS
|-
| 69 || 45 || SOUND_PLANE_CRASHING
|-
| 70 || 46 || SOUND_PLANE_ENGINE_SPUTTERING
|-
| 71 || 47 || SOUND_MAGLEV_2
|-
| 72 || 48 || SOUND_DISTANT_BIRD
|}