GRFSpecs - User contributions [en-gb]

NML:General

2020-02-17T14:26:00Z

Planetmaker: /* General variables */ OpenTTD revision doesn't change anymore after it moved to github

{{NMLNavPropVarCB}}

==General variables==

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

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

<pre style="color:blue">
traininfo_y_offset = -2;
</pre></ref>
| 0 or 1
| If 1, desert roads have pavement and street lights.
|-
| <code style="color:green">second_rocky_tileset</code>
| Yes <ref name=readwrite />
| 0 or 1
| {{ottdp|1.5|no|ottdrev=r27200}} If 1, rocky tiles are drawn using sprites from two ranges: 4023 - 4041 (always used) and 4042 - 4060 (used if enabled)
|-
| <code style="color:green">train_width_32_px</code>
| Yes <ref name=readwrite />
| 0 or 1
| If 1, train vehicles are 32 instead of 29 pixels wide in the depot view.
|-
| <code style="color:green">traininfo_y_offset</code>
| Yes <ref name=readwrite />
| -128 .. 127
| Used to correctly position the depot view of trains.
|-
| <code style="color:green">snowline_height</code>
| No
| {{nml|0.2}} 16 .. 120 in steps of 8, or 0xFF if no snow.
{{nml|0.3}} 0..max_tile_height, or 0xFF if no snow.
| {{nml|0.2}} One tile height is equivalent to 8 units.
{{nml|0.3}} It's the height in tiles.
|-
| <code style="color:green">traffic_side</code>
| Yes <ref name=gamechange />
| <code style="color:green">TRAFFIC_SIDE_LEFT</code> or <code style="color:green">TRAFFIC_SIDE_RIGHT</code>
|
|-
| <code style="color:green">freight_trains</code>
| Yes
| 1 .. 255
| Weight multiplier for freight trains
|-
| <code style="color:green">plane_speed</code>
| Yes
| 1 .. 4
| Speed multiplier for planes. Value of 1 is equal to the original speed (1/4), while 4 means that planes move at full speed (4/4)
|-
| <code style="color:green">ttdpatch_flags</code>
| Yes
|
|
|-
| <code style="color:green">current_callback</code>
| No
|
| Set to the ID of the current callback, useful for old-style callbacks.
|-
| <code style="color:green">extra_callback_info1</code>
| No
| Varies
| Extra callback information, meaning differs per callback.
|-
| <code style="color:green">extra_callback_info2</code>
| No
| Varies
| Extra callback information, meaning differs per callback.
|-
| <code style="color:green">last_computed_result</code>
| No
|
| Result of the last (previously evaluated) switch block.
|-
| <code style="color:green">base_sprite_2cc</code>
| Yes
| 0 .. 65535
| Base sprite for 2cc (dual company colour) colour-maps
|-
| <code style="color:green">base_sprite_foundations</code>
| Yes
| 0 .. 65535
| {{ottdp|1.4|no|ottdrev=r25230}} Base sprite for foundations. This sprite block does only contain the extra foundations from [[NML:Replace_new_sprites| replacenew]] type <code style="color:green">FOUNDATIONS_SLOPES_HALFTILES</code> or <code style="color:green">FOUNDATIONS_SLOPES</code>. It does not contain the default foundations of sprites 990 to 1003 (via replace)
|-
| <code style="color:green">base_sprite_shores</code>
| Yes
| 0 .. 65535
| {{ottdp|1.4|no|ottdrev=r25230}} Base sprite for shores. All coast sprites in the order of the [[Action5#0D_Coast_tile_sprites|16 sprites version]] of [[NML:Replace_new_sprites| replacenew]] type <code style="color:green">COAST_TILES</code>. Note that, it does not matter in which way the sprites were originally defined (whether via replacenew with 10 or 16 sprites, or via replace). The sprite block returned by this variable has always all sprites in the same order.
|-
| <code style="color:green">map_type</code>
| Yes
| <code style="color:green">MAP_TYPE_XXX</code> with <code style="color:green">XXX</code> = [<code style="color:green">RECTANGULAR</code> <nowiki>|</nowiki> <code style="color:green">X_BIGGER</code> <nowiki>|</nowiki> <code style="color:green">Y_BIGGER</code>]
|
|-
| <code style="color:green">map_min_edge</code>
| Yes
| 64 .. 4096
| Length of the smallest map edge (in tiles)
|-
| <code style="color:green">map_max_edge</code>
| Yes
| 64 .. 4096
| Length of the biggest map edge (in tiles)
|-
| <code style="color:green">map_x_edge</code>
| Yes
| 64 .. 4096
| Length of the x (top-left) map edge (in tiles)
|-
| <code style="color:green">map_y_edge</code>
| Yes
| 64 .. 4096
| Length of the y (top-right) map edge (in tiles)
|-
| <code style="color:green">map_size</code>
| Yes
| 64*64 .. 4096*4096
| Total number of tiles on the map
|-
| <code style="color:green">long_bridges</code>
| Yes
| 0 or 1
|
|-
| <code style="color:green">gradual_loading</code>
| Yes
| 0 or 1
|
|-
| <code style="color:green">bridge_speed_limits</code>
| Yes
| {{ttdp|}} 0 or 1 {{ottd|}} Always 1
|
|-
| <code style="color:green">wagon_speed_limits</code>
| Yes
| 0 or 1
| {{nml|0.4}}
|-
| <code style="color:green">signals_on_traffic_side</code>
| Yes
| 0 or 1
|
|-
| <code style="color:green">electrified_railways</code>
| Yes
| 0 or 1
|
|-
| <code style="color:green">unified_maglev</code>
| Yes
| {{ttdp|}} 0 .. 3 {{ottd|}} Always 3
|
|-
| <code style="color:green">temperate_snowline</code>
| Yes
| {{ttdp|}} 0 or 1 {{ottd|}} Always 0
|
|-
| <code style="color:green">dynamic_engines</code>
| Yes
| 0 or 1
|
|-
| <code style="color:green">variable_runningcosts</code>
| Yes
| {{ttdp|}} 0 or 1 {{ottd|}} Always 1
|
|-
| <code style="color:green">newtrains</code>
| Yes
| {{ttdp|}} 0 or 1 {{ottd|}} Always 1
|
|-
| <code style="color:green">newrvs</code>
| Yes
| {{ttdp|}} 0 or 1 {{ottd|}} Always 1
|
|-
| <code style="color:green">newships</code>
| Yes
| {{ttdp|}} 0 or 1 {{ottd|}} Always 1
|
|-
| <code style="color:green">newplanes</code>
| Yes
| {{ttdp|}} 0 or 1 {{ottd|}} Always 1
|
|-
| <code style="color:green">newhouses</code>
| Yes
| {{ttdp|}} 0 or 1 {{ottd|}} Always 1
|
|-
| <code style="color:green">newindustries</code>
| Yes
| {{ttdp|}} 0 or 1 {{ottd|}} Always 1
|
|-
| <code style="color:green">newcargos</code>
| Yes
| {{ttdp|}} 0 or 1 {{ottd|}} Always 1
|
|}

<references />

Features

2019-04-02T10:29:05Z

Planetmaker: towns' feature is 0x12

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

VariationalAction2/Industries

2018-12-22T10:22:17Z

Planetmaker: fix order of sections

==Introduction==

== Variables ==

{| |-
!Variable !![[GRFActionsDetailed|Size]] !!Version !! Description
|-
|40..42||||{{ottdp| | }}||Waiting cargo. See also variable 6F.
|-
|43||||{{ottdp| |2.6|ttdprev=r1298}}||Manhattan distance of closest dry/land tile
|-
|44||||{{ottdp| |2.6|ttdprev=r1594}}||Layout number (1-based)
|-
|45||||{{ottdp| |2.6|ttdprev=r1711}}||Player info
|-
|46||||{{ottdp|0.7|2.6|ttdprev=r2047|ottdrev=r13443}}||Date when industry was built in days since year 0
|-
|60||||{{ottdp| |2.5|ttdprev=alpha 73}}||Get industry tile ID at offset
|-
|61||||{{ottdp| |2.5|ttdprev=alpha 73}}||Get random tile bits at offset
|-
|62||||{{ottdp| |2.5|ttdprev=alpha 74}}||Land info of nearby tiles
|-
|63||||{{ottdp| | }}||Animation stage of nearby tiles
|-
|64||||{{ottdp| | }}||Distance of nearest industry with given type
|-
|65||||{{ottdp| | }}||Get [[TownZones|town zone]] and Manhattan distance of closest town
|-
|66||||{{ottdp| | }}||Get square of Euclidean distance of closest town
|-
|67||||{{ottdp| | }}||Count of industry, distance of closest instance
|-
|68||||{{ottdp| | }}||Like the above, but with layout filter
|-
|69||||{{ottdp|1.9|no|ottdrev=e66cec8f}}||Amount of produced output cargo waiting to be distributed.
|-
|6A||||{{ottdp|1.9|no|ottdrev=e66cec8f}}||Amount of cargo produced this month (so far).
|-
|6B||||{{ottdp|1.9|no|ottdrev=e66cec8f}}||Amount of cargo transported this month (so far).
|-
|6C||||{{ottdp|1.9|no|ottdrev=e66cec8f}}||Amount of cargo produced last month.
|-
|6D||||{{ottdp|1.9|no|ottdrev=e66cec8f}}||Amount of cargo transported last month.
|-
|6E||||{{ottdp|1.9|no|ottdrev=e66cec8f}}||Date since cargo was delivered last. (in days since year 0)
|-
|6F||||{{ottdp|1.9|no|ottdrev=e66cec8f}}||Amount of waiting cargo to be processed.
|-
|8A||W||{{ottdp| | }}||Amount of produced output cargo waiting to be distributed, for the first output cargo. See also variable 69.
|-
|8C||W||{{ottdp| | }}||Amount of produced output cargo waiting to be distributed, for the 2nd output cargo. See also variable 69.
|-
|93||B||{{ottdp| | }}||Production level. Normally between 4 and 128, default starting level is 16. A level of 0 means imminent closure.
|-
|94||W||{{ottdp| | }}||Production this month of first output cargo. See also variable 6A.
|-
|96||W||{{ottdp| | }}||Production this month of 2nd output cargo. See also variable 6A.
|-
|98||W||{{ottdp| | }}||Amount of cargo transported this month of the first output cargo. See also variable 6B.
|-
|9A||W||{{ottdp| | }}||Amount of cargo transported this month of the 2nd output cargo. See also variable 6B.
|-
|9C||B||{{ottdp| | }}||Fraction of cargo transported last month of the first output cargo
|-
|9D||B||{{ottdp| | }}||Fraction of cargo transported last month of the 2nd output cargo
|-
|9E||W||{{ottdp| | }}||Production last month of the first output cargo. See also variable 6C.
|-
|A0||W||{{ottdp| | }}||Production last month of the 2nd output cargo. See also variable 6C.
|-
|A2||W||{{ottdp| | }}||Amount of cargo transported last month of the first output cargo. See also variable 6D.
|-
|A4||W||{{ottdp| | }}||Amount of cargo transported last month of the 2nd output cargo. See also variable 6D.
|-
|A7||B||{{ottdp| |2.5|ttdprev=alpha 74}}||Industry founder information
|-
|A8||B||{{ottdp| | }}||Random (company) colour, chosen during construction
|-
|B0||W||{{ottdp| | }}||Date when industry was built in days since 1920
|-
|B3||B||{{ottdp| | }}||Construction type
|-
|B4||W||{{ottdp| |2.6|ttdprev=r1321}}||Date when cargo was last accepted in days since 1920, or 0 if no cargo was ever accepted. See also variable 6E.
|}

For other 80+x variables confer the [http://marcin.ttdpatch.net/sv1codec/TTD-locations.html#_IndustryArray TTD industry structure].

=== Waiting cargo (40..42) ===

If bit 1 or 2 is set in property 21, these variables contain the amount of incoming cargo waiting to be processed. (40 gives the amount of the first type waiting, 41 gives the same for the second type etc.) These variables are capped at FFFFh (65535).

See also variable 6F.

=== Manhattan distance of closest dry/land tile (43) ===

This variable works the same way as var. 8B does during callback 28: if your industry is built on water, it gives the distance of the closest dry land tile, otherwise it gives the distance of the closest water tile. However, you can't use this variable during callback 28; you must always use 8B.

'''PLEASE NOTE''': This variable is rather expensive to compute because, in the worst case, it has to check all tiles on the map before it gives up looking for a good tile. Try to avoid it in frequent callbacks such as the production callback, animation callbacks (unless the animation is slow, around 1 frame per game day or slower). It is, however, OK to use it during the production change callbacks.

=== Layout number (44) ===
T
his variable returns the number of the current layout. The first layout will return 01, the second 02, etc. In other words, this is one larger than what you get in variable 86 during callback 28.

If the industry was created using an earlier version of TTDPatch, or while newindustries was off, the result will be zero.

=== Player info (45) ===

As [[VarAction2Vehicles#Player info 43|vehicle variable 43]], except that the no-player state is indicated by var A7 being 10h.

=== Date when industry was built in days since year 0 (46) ===

Exact same behaviour as var B0, but based on year 0, instead of year 1920

In TTDPatch, industry age is limited to 65535 days (approximately 180 years) -- build date is never more than 65535 days ago.

=== Get industry tile ID at offset (60) ===

The parameter of this variable is an offset from the northernmost tile of the industry: the high nibble contains the Y offset, the low one the X offset; both are unsigned. The high word of the return value is currently reserved, and the low word can be:
* 00xxh if the tile is an industry tile and was defined in the current GRF with ID xx.
* FFxxh if the tile is an industry tile of an old type, and has the ID xx.
* FFFEh if the tile is an industry tile that was defined in another GRF file
* FFFFh if the tile isn't an industry tile, or doesn't belong to the current industry

=== Get random tile bits at offset (61) ===

The parameter of this variable is an offset from the northernmost tile of the industry: the high nibble contains the Y offset, the low one the X offset; both are unsigned. If there's an industry tile on that offset and it belongs to the current industry, the lowest byte of the return value will contain the random bits of that tile. Otherwise, the lowest byte will be zero.

The other bytes are reserved for future use.

=== Land info of nearby tiles (62) ===

The parameter of this variable is an offset from the northernmost tile of the industry: the high nibble contains the Y offset, the low one the X offset; both are unsigned. This variable returns the same values as [[VarAction2IndustryTiles#Land info of nearby tiles 60|industry tile variable 60]], in the same format, except that bit 0 in the '''bb''' part is undefined. The offset should be given relatively to the north corner of the industry.

=== Animation stage of nearby tiles (63) ===

The parameter of this variable is an offset from the northernmost tile of the industry: the high nibble contains the Y offset, the low one the X offset; both are unsigned. This variable returns the same values as [[VarAction2IndustryTiles#Animation stage for nearby tiles 61|industry tile variable 61]], in the same format. The offset should be given relatively to the north corner of the industry.

=== Distance of nearest industry with given type (64) ===

The format of the parameter is the same as for industry property 16: either the ID of a new type with bit 7 set, or the ID of an old type. The returned value is FFFFFFFFh if there are no industries with the given type (not counting the current one, if it has the given type); otherwise, the returned value is the Manhattan distance of the closest industry with the given type.

=== Get [[TownZones|town zone]] and Manhattan distance of closest town (65) ===

The parameter gives an offset from the northernmost tile of the industry: the high nibble means the Y offset, the low nibble means the X offset, both signed. The returned value is rrzzdddd, where rr is reserved for future use, zz is the [[TownZones|town zone]] of the selected tile, while dddd is the Manhattan distance of the closest town.

=== Get square of Euclidean distance of closest town (66) ===

The parameter works like for var. 65, but the result is the Euclidean distance of the closest town, squared.

=== Count of industry, distance of closest instance (67, 68) ===

Variable 67 gets two parameters: the GRFID of the GRF where the industry is defined in register 100h (can be written using operator 0E of [[VarAction2Advanced|VarAction2]]) and the setID of the industry as the regular parameter. There are two special cases for the GRFID: 00000000h means you're checking for a default TTD industry type, while FFFFFFFFh can be used instead of the GRFID of the current GRF.

The return value has the format rrccdddd, where rr is reserved for future use, cc is the number of instances of the industry type and dddd is the Manhattan distance of the closest instance, of FFFFh if not appliable.

You may note that this variable can be used instead of variable 64. This variable is the preferred way to get this information since it allows you to check industries defined in other GRFs as well. Variable 64 will stay for backward compatibility only.

Variable 68 works like variable 67, except that you can put a layout number in the lowest byte of register 101. (The other bits are reserved for future use, leave them zero for now.) This layout number should be 1-based (the first layout is 01, not 00). Only industries with the given layout are considered for counting and calculating distance. As a special case, if the layout number is 00, all layouts are counted, and so the result is the same as with variable 67.

Since OpenTTD r22434, it is possible to filter by the town of the current industry. If the bit number 8 is set, only industries in the same town than the current one will be considered.

=== Cargo info variables (69..6F) ===
{{ottdp|1.9|no|ottdrev=e66cec8f}}

These variables allow to query information about accepted and produced cargos.
The variables are independent of the number of cargo types and their order. The 60+x parameter specifies the cargo type as index into the cargo translation table.

=== Industry founder information (A7) ===

This byte contains the ID of the company that funded the industry, or 10h if the industry was generated randomly. If the industry was built using an earlier TTDPatch than 2.0.1 α74 or with newindustries turned off, this field is 10h.

=== Construction type (B3) ===

This byte tells you how the industry got onto the map. The following values are possible:

{| |-
!Value!!Meaning
|-
|0||Unknown - This industry was built with newindustries being off, or in a TTDPatch version prior to TTDPatch 2.0.1 alpha 74
|-
|1||Created during normal gameplay, either by a player or the in-game random industry generator
|-
|2||Created during random map generation
|-
|3||Created in the scenario editor
|}

In case 1, you can check variable A7 to find out whether the industry was funded by a player or by the random generator.

==Example==

TTDPatchFlags

2018-11-15T21:53:32Z

Planetmaker: it was a different hash

In the table below you find all the TTDPatch flags that belong to <param-num> = 85 in Action 7 and Action 9.

{| |-
!'''Bit'''!!'''Switch (bit set = switch on)'''!!'''Correspondence in OpenTTD'''
|-
|0C||keepsmallairport||station.never_expire_airports
|-
|0D||newairports||1
|-
|0E||largestations||1
|-
|0F||longbridges||construction.longbridges
|-
|10||loadtime||0
|-
|12||presignals||1
|-
|13||extpresignals||1
|-
|16||enginespersist||vehicles.never_expire_vehicles
|-
|1B||multihead||1
|-
|1D||lowmemory||1
|-
|1E||generalfixes||1
|-
|27||moreairports||economy.station_noise_level
|-
|28||mammothtrains||1
|-
|29||trainrefit||1
|-
|2B||subsidiaries||0
|-
|2C||gradualloading||order.gradual_loading
|-
|32||(Set to bit 0 of unifiedmaglev mode)||1 (n/a)
|-
|33||(Set to bit 1 of unifiedmaglev mode)||1 (n/a)
|-
|34||bridgespeedlimits||1
|-
|36||eternalgame||1
|-
|37||newtrains||1
|-
|38||newrvs||1
|-
|39||newships||1
|-
|3A||newplanes||1
|-
|3B||signalsontrafficside||construction.signal_side
|-
|3C||electrifiedrailway||vehicle.disable_elrails
|-
|41 <ref>loadallgraphics is obsolete (and its bit unused) since revision 401. The next official versions were the 5/Jun/2006 nightly (402) and TTDPatch 2.5 beta 6 (472)</ref>||loadallgraphics||1
|-
|43||semaphores||1
|-
|4A||newobjects (since r2364)||1
|-
|4B||enhancegui||0
|-
|4C||newagerating||0
|-
|4D||buildonslopes||construction.build_on_slopes
|-
|4E||fullloadany||1
|-
|4F||planespeed||1
|-
|50 <ref>moreindustriesperclimate is obsolete (and its bit unused) since TTDPatch 2.5 beta 2.</ref>||moreindustriesperclimate||0
|-
|51||moretoylandfeatures||0
|-
|52||newstations||1
|-
|53||tracktypecostdiff||1
|-
|54||manualconvert||1
|-
|55||buildoncoasts||construction.build_on_slopes
|-
|56||canals||1
|-
|57||newstartyear||1
|-
|58||freighttrains||vehicle.freight_trains > 1
|-
|59||newhouses||1
|-
|5A||newbridges||1
|-
|5B||newtownnames||1
|-
|5C||moreanimation||1
|-
|5D||wagonspeedlimits||vehicle.wagon_speed_limits
|-
|5E||newshistory||1
|-
|5F||custombridgeheads||0
|-
|60||newcargodistribution||0
|-
|61||windowsnap||1
|-
|62||townbuildnoroads||not (economy.allow_town_roads or _generating_world)
|-
|63||pathbasedsignalling||1
|-
|64||aichoosechances||0
|-
|65||resolutionwidth||1
|-
|66||resolutionheight||1
|-
|67||newindustries||1
|-
|68||fifoloading||order.improved_load
|-
|69||townroadbranchprob||0
|-
|6A||tempsnowline||0
|-
|6B||newcargos||1
|-
|6C||enhancemultiplayer||1
|-
|6D||onewayroads||1
|-
|6E||irregularstations||1
|-
|6F||morestatistics||1
|-
|70||newsounds||1
|-
|71||autoreplace||1
|-
|72||autoslope||1
|-
|73||followvehicle||0
|-
|74||trams||1
|-
|75||enhancetunnels||0
|-
|76||shortrvs||1
|-
|77||articulatedrvs||1
|-
|78||dynamicengines||{{ottd|0.7|r12924}} vehicle.dynamic_engines
|-
|7E||variablerunningcosts (since r1421)||1
|-
|7F||set if any switches are on||1
|-
|80||-||{{ottd|1.9|g4b0b4e064}} 1 (larger persistent storage)
|}

<references />

Action0/Bridges

2018-08-08T09:22:54Z

Planetmaker:

==Introduction==

Defining properties of bridges. By default the following bridges are defined:

{| |-
!'''ID (dec)'''!!'''ID (hex)'''!!'''Description'''
|-
|0||00||Wooden Bridge
|-
|1||01||Concrete Bridge
|-
|2||02||Girder, Steel Bridge
|-
|3||03||Suspension, Concrete Bridge
|-
|4||04||Suspension, Steel (Bronze) Bridge
|-
|5||05||Suspension, Steel (Golden) Bridge
|-
|6||06||Cantilever, Steel (Bronze) Bridge
|-
|7||07||Cantilever, Steel (Brown) Bridge
|-
|8||08||Cantilever, Steel (Red) Bridg
|-
|9||09||Girder, Steel Bridge
|-
|10||0A||Tubular, Steel (Bronze) Bridge
|-
|11||0B||{{ottdp|0.6|no}} Tubular, Steel (Golden) Bridge
|-
|12||0C||{{ottdp|0.6|no}} Tubular, Silicon Bridge
|}

==Properties==

{| |-
!Number!![[GRFActionsDetailed|Size]]!!Version!!Description
|-
|00||B||{{ottdp|no|2.6|ttdprev=r1994}}||Failback Type, a default TTD Bridge ID
|-
|08<ref>The meaning of prop. 08 has changed in TTDPatch 2.0.1 alpha 34, it used to be what is now prop. 0D.</ref>||B||{{ottdp|0.6|2.5|ttdprev=alpha 34}}||Year of availability, counted from 1920 (set to 1920 for first bridge if newstartyear<1930)
|-
|09||B||{{ottdp|0.6|2.5|ttdprev=alpha 34}}||Minimum length, not counting ramps
|-
|0A||B||{{ottdp|0.6|2.5|ttdprev=alpha 34}}||Maximum length, not counting ramps
|-
|0B||B||{{ottdp|0.6|2.5|ttdprev=alpha 34}}||Cost factor
|-
|0C||W||{{ottdp|0.6|2.5|ttdprev=alpha 34}}||Max. speed
|-
|0D||V||{{ottdp|0.6|2.5|ttdprev=alpha 34}}||Sprite layout, see below
|-
|0E||B||{{ottdp|0.6|2.5|ttdprev=alpha 34}}||Various flags, bitcoded
|-
|0F||D||{{ottdp|0.6|2.5|ttdprev=r1702|ottdrev=r7191}}||Long format year of availability, counted from year 0
|-
|10||W||{{ottdp|0.6|2.5|ttdprev=r1824|ottdrev=r10269}}||Purchase text
|-
|11||W||{{ottdp|0.6|2.5|ttdprev=r1824|ottdrev=r10269}}||Description of a rail bridge
|-
|12||W||{{ottdp|0.6|2.5|ttdprev=r1824|ottdrev=r10269}}||Description of a road bridge
|-
|13||W||{{ottdp|0.7|2.6|ttdprev=r1994|ottdrev=r14172}}||Cost factor word access
|}
<references/>

Unofficial additions and changes. Don't rely on them to ever work this way or at all in OpenTTD or TTDPatch:
{| |-
!Number!![[GRFActionsDetailed|Size]]!!Version!!Description
|-
|14||W||New Map Features||Menu icons <ref name="nmf">New Map Features (NMF) adds three bridge IDs (0x0D ... 0x0F). There are no graphics. Currently Graphic Resource Management (GRM) must be used to assign real sprites.</ref>
|}
<references/>

==Descriptions==

===Sprite layout (0D)===

Property 0D sets the sprite layout for bridges. Each part of a bridge has eight sprites for each of the four types (rail, road, monorail, maglev), making 32 sprites in total. Each bridge has 7 parts, though not all of them have different graphics.

The data for property 0D is variable sized, with the format being

{| |-
!Size!!Field!!Description
|-
|B||tableid||First table to define sprites for
|-
|B||numtables||Number of tables to define sprites for
|-
|V||spritedata||spritedata, numtables*32 DWORDs with sprite numbers
|}

The tableid is the number of the first table to change. There are seven tables for each bridge, with the first six (0-5) being various middle parts and the last one (6) being the end pieces.

In each of the six middle part tables, there are four entries each for the following:
* Rail X, Rail Y, Road X, Road Y, Monorail X, Monorail Y, Maglev X, Maglev Y

Where X is a bridge in /-direction and Y a bridge in \-direction.

The four entries are
* Back & Floor, Front, Pillars, 0

Front and Pillars can be 0, meaning no sprite to draw. The fourth entry is always ignored.

In the end part table, there are again four entries each, but now for Rail flat, Rail ramp, Road flat, Road ramp, Monorail flat, Monorail ramp and Maglev flat, Maglev ramp.

The four entries in this case are
* northern end X, northern end Y, southern end X, southern end Y

The sprite numbers can be any of TTD's sprite numbers.

To summarize, there are 7 tables for each of the 11 bridges. Each table contains 4*8 entries, making it 128 (80h) bytes large. The first six tables, number 0 to 5, are middle pieces, the last table, number 6, is the end pieces.

====Colour Translations====

In order to recolour a bridge, you can add one of the values from the table below to the sprite number of the sprite you wish to recolour. The colour translations from the table will use the default colour translation tables from the base sets. These translation tables will translate the 'brownish red' as used in the default bridges to the colour you specify.

{| |-
!'''Added value'''!!'''Little Endian'''!!'''Colour'''
|-
|031B8000h||00 80 1B 03||Blue
|-
|031C8000h||00 80 1C 03||Brown
|-
|031D8000h||00 80 1D 03||Pure white
|-
|031E8000h||00 80 1E 03||Red
|-
|031F8000h||00 80 1F 03||Green
|-
|03208000h||00 80 20 03||Blueish white (concrete)
|-
|03218000h||00 80 21 03||Yellow (golden steel)
|}

Take a look at the [[RecolorSprites#Default_recolour_sprites | default recolour tables]] for other colour translations. However, other recolor maps than the seven listed above will translate other colours than those uses by original bridges.

''Example: Translate sprite 4366 to yellow''
:4366 translates to 0E 11 in little endian value and as such to 0E 11 00 00 in a dword. In order to convert to yellow you'll have to add 00 80 21 03 to the dword value. This yields 0E 91 21 03. Use the latter in your bridge table to colour one of the monorail bridgeheads grey.

====Bridge Layouts====

There are five possible bridge layouts in TTD. The numbers in the table below reflect the bridge table numbers in the NFO code.

{| |-
!Layout!!Description
|-
|__ ||Bridge without middle part
|-
|_0_||Bridge of length 3
|-
|_0(23)1_||Bridge of even length
|-
|_0(23)4(23)1_||Bridge of (uneven) lengths 5, 9, 13, 17 etc.
|-
|_0(23)253(23)1_||Bridge of (uneven) lengths 7, 11, 15, 19 etc.
|}

_ is used as a symbol to indicate bridgeheads (as defined in table 6).

Part 0 is always at the farthest end from the viewer.

Parts (23) are repeated ''n'' times as necessary, where ''n'' is any number equal or greater than 0.

===Flags (0E)===

The following flags can be set here:

{| |-
!'''Bit'''!!'''Value'''!!'''Meaning'''
|-
|0||1||Do not draw the far pillars for higher bridges
|}

===Long format year of availability (0F)===

Set the year of availability of the bridge in years since 0. The date range is from 0 to 5000000. This property must be set after property 08 to take effect.

{{ottdp|no||}} In TTDPatch, bridge introduction dates outside the range 1920..2175 will be limited to this range.

===Purchase text (10)===

Set the text appearing in the purchase window, describing what this bridge is made of, or what kind of bridge it is.

This should be the ID of an original bridge name, or a TextID in the DCxx range.

===Description of a rail(11) or road(12) bridge===

Set the text used as a description by the query tool. When the bridge is used for carrying a rail, it will use property 11, and will use property 12 when it will be for road.

This should be the ID of an original bridge name, or a TextID in the DCxx range.

===Menu icons (14)===

Previously menu icons could be replaced by an ActionA, with the exception of the six recolor bridges which always retained a recolored icon of one of the three parent bridges.
Property 14 allows all icons to be accessed including the three new bridge IDs in cirdan's New Map Features.

Note: Currently this property is only supported by New Map Features.

==Example==

Below is an example code which rebuilds the bronze steel suspension bridge (ID 04). The code fragment by itself has no use (no visual difference in game), but might be useful in order to understand the bridge code. Sprite numbers refer to the numbers in the base grf. The code might also be useful to re-enstate the default bridge if you only want to replace only one certain tracktype.

The complete recode of all default bridges including colour translations is available at TT-Forums: http://www.tt-forums.net/viewtopic.php?p=715362#p715362

<pre>//SUSPENSION, STEEL (BRONZE) bridge (04)

-1 * 0 00 06 01 01 04 0D 00 07 //action 00 bridges, 01 property, 01 ID, ID, prop 0D, tableID 00, 07 tables

//table 00

A9 09 00 00 9F 09 00 00 B1 09 00 00 00 00 00 00 //rail X: Back&Floor, Front, Pillars, 0
A5 09 00 00 97 09 00 00 AD 09 00 00 00 00 00 00 //rail Y: Back&Floor, Front, Pillars, 0
9D 09 00 00 9F 09 00 00 B1 09 00 00 00 00 00 00 //Road X: Back&Floor, Front, Pillars, 0
95 09 00 00 97 09 00 00 AD 09 00 00 00 00 00 00 //Road Y: Back&Floor, Front, Pillars, 0
F2 10 00 00 9F 09 00 00 B1 09 00 00 00 00 00 00 //Mono X: Back&Floor, Front, Pillars, 0
EE 10 00 00 97 09 00 00 AD 09 00 00 00 00 00 00 //Mono Y: Back&Floor, Front, Pillars, 0
1A 11 00 00 9F 09 00 00 B1 09 00 00 00 00 00 00 //Mlev X: Back&Floor, Front, Pillars, 0
16 11 00 00 97 09 00 00 AD 09 00 00 00 00 00 00 //Mlev Y: Back&Floor, Front, Pillars, 0
//table 01
AA 09 00 00 A0 09 00 00 B2 09 00 00 00 00 00 00 //rail X: Back&Floor, Front, Pillars, 0
A6 09 00 00 98 09 00 00 AE 09 00 00 00 00 00 00 //rail Y: Back&Floor, Front, Pillars, 0
9E 09 00 00 A0 09 00 00 B2 09 00 00 00 00 00 00 //Road X: Back&Floor, Front, Pillars, 0
96 09 00 00 98 09 00 00 AE 09 00 00 00 00 00 00 //Road Y: Back&Floor, Front, Pillars, 0
F3 10 00 00 A0 09 00 00 B2 09 00 00 00 00 00 00 //Mono X: Back&Floor, Front, Pillars, 0
EF 10 00 00 98 09 00 00 AE 09 00 00 00 00 00 00 //Mono Y: Back&Floor, Front, Pillars, 0
1B 11 00 00 A0 09 00 00 B2 09 00 00 00 00 00 00 //Mlev X: Back&Floor, Front, Pillars, 0
17 11 00 00 98 09 00 00 AE 09 00 00 00 00 00 00 //Mlev Y: Back&Floor, Front, Pillars, 0
//table 02
AC 09 00 00 A4 09 00 00 B4 09 00 00 00 00 00 00 //rail X: Back&Floor, Front, Pillars, 0
A8 09 00 00 9C 09 00 00 B0 09 00 00 00 00 00 00 //rail Y: Back&Floor, Front, Pillars, 0
A2 09 00 00 A4 09 00 00 B4 09 00 00 00 00 00 00 //Road X: Back&Floor, Front, Pillars, 0
9A 09 00 00 9C 09 00 00 B0 09 00 00 00 00 00 00 //Road Y: Back&Floor, Front, Pillars, 0
F5 10 00 00 A4 09 00 00 B4 09 00 00 00 00 00 00 //Mono X: Back&Floor, Front, Pillars, 0
F1 10 00 00 9C 09 00 00 B0 09 00 00 00 00 00 00 //Mono Y: Back&Floor, Front, Pillars, 0
1D 11 00 00 A4 09 00 00 B4 09 00 00 00 00 00 00 //Mlev X: Back&Floor, Front, Pillars, 0
19 11 00 00 9C 09 00 00 B0 09 00 00 00 00 00 00 //Mlev Y: Back&Floor, Front, Pillars, 0
//table 03
AB 09 00 00 A3 09 00 00 B3 09 00 00 00 00 00 00 //rail X: Back&Floor, Front, Pillars, 0
A7 09 00 00 9B 09 00 00 AF 09 00 00 00 00 00 00 //rail Y: Back&Floor, Front, Pillars, 0
A1 09 00 00 A3 09 00 00 B3 09 00 00 00 00 00 00 //Road X: Back&Floor, Front, Pillars, 0
99 09 00 00 9B 09 00 00 AF 09 00 00 00 00 00 00 //Road Y: Back&Floor, Front, Pillars, 0
F4 10 00 00 A3 09 00 00 B3 09 00 00 00 00 00 00 //Mono X: Back&Floor, Front, Pillars, 0
F0 10 00 00 9B 09 00 00 AF 09 00 00 00 00 00 00 //Mono Y: Back&Floor, Front, Pillars, 0
1C 11 00 00 A3 09 00 00 B3 09 00 00 00 00 00 00 //Mlev X: Back&Floor, Front, Pillars, 0
18 11 00 00 9B 09 00 00 AF 09 00 00 00 00 00 00 //Mlev Y: Back&Floor, Front, Pillars, 0
//table 04
B6 09 00 00 BA 09 00 00 BC 09 00 00 00 00 00 00 //rail X: Back&Floor, Front, Pillars, 0
B5 09 00 00 B9 09 00 00 BB 09 00 00 00 00 00 00 //rail Y: Back&Floor, Front, Pillars, 0
B8 09 00 00 BA 09 00 00 BC 09 00 00 00 00 00 00 //Road X: Back&Floor, Front, Pillars, 0
B7 09 00 00 B9 09 00 00 BB 09 00 00 00 00 00 00 //Road Y: Back&Floor, Front, Pillars, 0
F7 10 00 00 BA 09 00 00 BC 09 00 00 00 00 00 00 //Mono X: Back&Floor, Front, Pillars, 0
F6 10 00 00 B9 09 00 00 BB 09 00 00 00 00 00 00 //Mono Y: Back&Floor, Front, Pillars, 0
1F 11 00 00 BA 09 00 00 BC 09 00 00 00 00 00 00 //Mlev X: Back&Floor, Front, Pillars, 0
1E 11 00 00 B9 09 00 00 BB 09 00 00 00 00 00 00 //Mlev Y: Back&Floor, Front, Pillars, 0
//table 05
BD 09 00 00 C1 09 00 00 00 00 00 00 00 00 00 00 //rail X: Back&Floor, Front, Pillars, 0
BE 09 00 00 C2 09 00 00 00 00 00 00 00 00 00 00 //rail Y: Back&Floor, Front, Pillars, 0
BF 09 00 00 C1 09 00 00 00 00 00 00 00 00 00 00 //Road X: Back&Floor, Front, Pillars, 0
C0 09 00 00 C2 09 00 00 00 00 00 00 00 00 00 00 //Road Y: Back&Floor, Front, Pillars, 0
F8 10 00 00 C1 09 00 00 00 00 00 00 00 00 00 00 //Mono X: Back&Floor, Front, Pillars, 0
F9 10 00 00 C2 09 00 00 00 00 00 00 00 00 00 00 //Mono Y: Back&Floor, Front, Pillars, 0
20 11 00 00 C1 09 00 00 00 00 00 00 00 00 00 00 //Mlev X: Back&Floor, Front, Pillars, 0
21 11 00 00 C2 09 00 00 00 00 00 00 00 00 00 00 //Mlev Y: Back&Floor, Front, Pillars, 0
//table 06
86 09 00 00 88 09 00 00 85 09 00 00 87 09 00 00 //rail flat: northern end X, northern end Y, southern end X, southern end Y
8A 09 00 00 8C 09 00 00 89 09 00 00 8B 09 00 00 //rail ramp: northern end X, northern end Y, southern end X, southern end Y
8E 09 00 00 90 09 00 00 8D 09 00 00 8F 09 00 00 //road flat: northern end X, northern end Y, southern end X, southern end Y
92 09 00 00 94 09 00 00 91 09 00 00 93 09 00 00 //road ramp: northern end X, northern end Y, southern end X, southern end Y
E7 10 00 00 E9 10 00 00 E6 10 00 00 E8 10 00 00 //mono flat: northern end X, northern end Y, southern end X, southern end Y
EB 10 00 00 ED 10 00 00 EA 10 00 00 EC 10 00 00 //mono ramp: northern end X, northern end Y, southern end X, southern end Y
0F 11 00 00 11 11 00 00 0E 11 00 00 10 11 00 00 //mlev flat: northern end X, northern end Y, southern end X, southern end Y
13 11 00 00 15 11 00 00 12 11 00 00 14 11 00 00 //mlev ramp: northern end X, northern end Y, southern end X, southern end Y

Action0/Stations

2018-08-08T09:16:30Z

Planetmaker: /* Properties */

==Introduction==

Defining properties of new stations.

Unlike vehicles, the new stations have no equivalent in TTD. The IDs are therefore free to be chosen and will in fact be allocated automatically. In action 0, you only specify IDs relative to the set, i.e. the ID of the first station type is 00, the second station type is 01 and so on.

{{ttdp|}} In TTDPatch each game can only have 255 station IDs for all active grf files.

The only property you '''must''' set for each station ID is 08 (in addition to defining an [[Action3|action 3]] for it), anything else can be left at the default. It must be the first property you set for each station ID, because the station ID is actually undefined until it has been assigned a class through property 08. Also, all station IDs must get their classes in the right order, starting from ID 00 onwards.

== Properties ==

{| |-
!Number!![[GRFActionsDetailed|Size]]!!Version!!Description
|-
|08||D||{{ottdp|0.6|2.5|ttdprev=alpha 19}}||Class ID, see below
|-
|09||V||{{ottdp|0.6|2.5|ttdprev=alpha 20}}||Sprite layout, see below
|-
|0A||B||{{ottdp|0.6|2.5|ttdprev=alpha 20}}||Copy sprite layout
|-
|0B||B||{{ottdp|0.6|2.5|ttdprev=alpha 22}}||Callback flags
|-
|0C||B||{{ottdp|0.6|2.5|ttdprev=alpha 22}}||Bit mask of disabled numbers of platforms
|-
|0D||B||{{ottdp|0.6|2.5|ttdprev=alpha 22}}||Bit mask of disabled platform lengths
|-
|0E||V||{{ottdp|0.6|2.5|ttdprev=alpha 22}}||Define custom layout, see below
|-
|0F||B||{{ottdp|0.6|2.5|ttdprev=alpha 22}}||Copy custom layout from stationid given by argument
|-
|10||W||{{ottdp|0.6|2.5|ttdprev=alpha 25}}||Little/lots threshold
|-
|11||B||{{ottdp|0.6|2.5|ttdprev=alpha 27}}||Pylon placement
|-
|12||D||{{ottdp|0.6|2.5|ttdprev=alpha 30}}||Bit mask of cargo type triggers for random sprites
|-
|13||B||{{ottdp|0.6|2.5|ttdprev=alpha 30}}||General flags
|-
|14||B||{{ottdp|0.6|2.5|ttdprev=alpha 47}}||Overhead wire placement
|-
|15||B||{{ottdp|0.6|2.5|ttdprev=alpha 51}}||Can train enter tile
|-
|16||W||{{ottdp|0.7|2.5|ttdprev=beta 9}}||Animation information
|-
|17||B||{{ottdp|0.7|2.5|ttdprev=beta 9}}||Animation speed
|-
|18||W||{{ottdp|0.7|2.5|ttdprev=beta 9}}||Animation triggers
|-
|19||V||{{ottdp}}||Road routing (reserved for future use)
|-
|1A||V||{{ottdp|1.2|no|ottdrev=r22518}}||Advanced sprite layout with register modifiers
|}

Unofficial additions and changes. Don't rely on them to ever work this way in OpenTTD or TTDPatch:
{| |-
!Number!![[GRFActionsDetailed|Size]]!!Version!!Description
|-
|1B||8*B||whatever-PP||Minimum bridge height for bridges over stations
|}

== Description ==

=== Station class (08) ===
TTDPatch groups sets of new station graphics into various classes.  The classes can be selected by the top dropdown list in the construction window, and the individual stations within the class from the bottom dropdown list.  In addition, each station can alter its appearance using [[VariationalAction2|variational]] and/or [[RandomAction2|random]] action 2 entries.

Only two classes are pre-defined:

{| |-
!Name!!Class ID!!Intended use for station
|-
|DFLT||44 46 4C 54||Default, no special station type
|-
|WAYP||57 41 59 50||Non-cargo stations, waypoints, signal boxes etc.
|}

You may simply use other classes than the above, as long as no more than (at the moment) 16 classes are used among all active .grf files at any time.

When a WAYP station is built, it will not accept cargo nor will any cargo appear from nearby industries or towns.  Trains will not stop at WAYP stations, regardless of the non-stop order and/or the nonstop switch.

=== Sprite layout (09) ===
This controls what sprites are displayed, where they are displayed, and in what order.  The property is variable sized, and contains the data for all 8 possible station tile types.  If this property is set, the num-ent in the corresponding [[Action1|action 1]] need not be equal to 12 (hex), it can in fact be any number, and any number of sprites can be displayed in any order.

The data is specified as data for all eight tiles in this way:

<pre><num> <data1> <data2> ... <datan></pre>

{| |-
!Size!!Name!!Meaning
|-
|B*||num||Number of different tiles supported (see below)
|-
|V||data1...||The variable size data for each of the <num> tiles, as specified below
|}

===== Number of tiles supported =====
* Normally this is 8, but you can specify fewer as well
* Using callback flags bit 1, specifying more makes sense too
* This value must be the same for all stations set by this action 0, even though it must be repeated for the prop. 09 definition of each station ID as well

(Note that num is an extended byte, see [[GRFActionsDetailed]].)

The content of each of the (usually eight) data sets is either a new sprite layout:

{| |-
!Size!!Name!!Meaning
|-
|D||groundsprite||the sprite to draw for the rails; this is by default a TTD sprite, but with bit 31 set an [[Action1|action 1]] sprite (42D+X) may be specified
|-
|V||spritedata||the data for station sprites, see below; each has a size of 10 bytes, and there may be several
|-
|B||80||a literal 80 ends the list of sprites for this tile
|}
or, alternatively, the instruction to use TTD's layout by using four zero bytes 00 00 00 00 instead of the groundsprite bytes. You can use [http://www.bytetransfer.de/projects/ttdpatch/docs/spriteidmapping.php the online sprite ID converter] to look up the sprite IDs you can use for all the climates.

One can draw two types of sprites.  One type is one that establishes a new 3D bounding box for use by the sprite sorter.  The other type shares the 3D bounding box of the previous sprite(s).  It must not be larger than the sprite which established the bounding box, nor must any part of it be outside this box.  For simplicity, it should have the exact same dimensions as the sprite it shares the bounding box with.  The latter type is supported in the station construction window display only since TTDPatch 2.6 r1684.

The spritedata of sprites with their own bounding box has this format:

{| |-
!Size!!Name!!Meaning
|-
|B||xofs||x-offset from northern tile corner
|-
|B||yofs||y-offset from northern tile corner
|-
|B||zofs||z-offset from northern tile corner
|-
|B||xextent||size of sprite in x direction
|-
|B||yextent||size of sprite in y direction
|-
|B||zextent||size of sprite in z direction
|-
|D||sprite||sprite number to draw
|}

The spritedata of sprites sharing the bounding box has this format:

{| |-
!Size!!Name!!Meaning
|-
|B||xofs||x-offset relative to previous sprite
|-
|B||yofs||y-offset relative to previous sprite
|-
|B||80||a literal 80
|-
|B||00||(ignored)
|-
|B||00||(ignored)
|-
|B||00||(ignored)
|-
|D||sprite||sprite number to draw
|}

Since OpenTTD r18959 you can draw multiple ground sprites for a tile, which is useful if you want to use the usual rail/grass/concrete groundtile, but still need to add features to it without using a new bounding box. To do so use the syntax of sprites sharing the previous bounding box, but use it before the first bounding box definition. xpixeloffset and ypixeloffset refer to the usual spot of groundtiles. The same feature is also partially supported in TTDPatch since TTDPatch 2.6 r2312: TTDPatch ignores the xofs and yofs fields and always uses (0,0) for the offset. If you are developing a GRF that needs to be compatible with both OpenTTD and TTDPatch, you should always keep xofs and yofs zero to get the same effect in both games.
Note however that both implementations do not consider the [[Action0/Stations#General_Flags_.2813.29|setting of prop13 bit 0]], hence these "multiple ground sprites" have to be always part of the building sprites set and cannot be part of the different sprite set for ground sprites.

The sprite number can have the following values (remember to use little endian, i.e. reversed byte order):

{| |-
!Number!!Sprite
|-
|0000042D+X||use sprite X from the corresponding [[Action1|action 1]] block (i.e. 0000042D for the first, 0000042E for the second, etc.)
|-
|0000842D+X||same, but draw it using company colour translation
|-
|0322442D+X||same, but draw in transparent mode (actual colours of the sprite are disregarded entirely); supported in station construction window display since TTDPatch 2.6 r1683
|-
|RRRR842D+X||draw sprite with colour translation defined in sprite RRRR; available since TTDPatch 2.6 r1683
|}

With bit 31 set, this sprite will refer to a TTD sprite, not the action 1 sprite. For the first ground sprite the reverse meaning applies.

Depending on the railtype the sprites may get additional offsets:

{| |-
! !! Normal/electrified rail !! Monorail !! Maglev
|-
|TTD sprites || 0 || 82 || 164
|-
|Action 1 sprite (first ground sprite) || 0 || 1 || 2
|-
|Action 1 sprite (other sprites in the layout) || 0 || 0 || 0
|}

So, TTD sprites and the first ground sprite are affected by the railtype, while other action 1 sprites in the layout are not. The offset "82" refers to the offset between the default TTD track sprites; if you are using non-track ground sprites which are not from an action 1, you need to supply fake spritenumbers which preemptively reverse the offsets (that is, you need different sprite layouts for every railtype your station is available for).

Setting bit 30 forces this sprite to be displayed normally even in "transparent buildings" mode (supported only in TTDPatch 2.6 r1695 and later).

See below for an example of linked sprites as well as transparent sprites (e.g. for a station roof).

Note that the coordinates here are 3D coordinates with x running from top-right to bottom-left and y running from top-left to bottom-right, with the tile dimensions being 16x16 (and 8 for one height level). This means the x and y values should always be within 0-15 (decimal).

This is different to and independent from the x/y offsets used in the actual .NFO file.  The 3D bounding box is used by TTD's sprite sorter to figure out the order in which to draw the sprites, as well as telling it which sprites to draw, because those whose bounding box falls outside the currently updated screen rectangle will not be drawn.  Make sure the 3D bounding box is large enough to contain the entire sprite, but not so large that the sprite sorter can't determine which sprites should be in front.

This means that the order in which you specify sprites is irrelevant.  Sprites will get drawn from back to front, in the order which the sprite sorter determines as correct, from their bounding boxes.  There are two exceptions, however:
* Sprites sharing the same bounding box will always be drawn in the given order.
* The station construction window display doesn't use the sprite sorter. Tiles that may be displayed in that window need to be specified in the correct drawing order, back to front.

=== Copy sprite layout (0A) ===

This is not a property as such, but an action.  It takes as argument a byte which is interpreted as station-ID to copy the custom sprite layout from.

=== Callback flags (0B) ===
For stations, the following [[callbacks]] can be defined by setting the corresponding bit in property 0B:

{| |-
!Bit!!Value!!Variable 0C value!!Callback
|-
|0||1||13||Whether to make station available in construction window (non-zero callback return) or not (callback returns zero)
|-
|1||2||14||Use callback to select sprite layout
|-
|2||4||141||Decide next animation frame
|-
|3||8||142||Decide animation speed
|-
|4||10||149||Custom slope check
|}
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 [[VariationalAction2|VarAction2]] for callbacks.

=== Selection of numbers of platforms and length (0C, 0D) ===

By default all platform lengths and any number of platforms is available for the new stations.  Using these properties, you can choose which ones should be unavailable by setting the corresponding bit in the property.

The values are a byte, used as a bit mask.  Bits 0 to 6 control the availability of number or length 1 to 7, and bit 7 controls the availability of the "+7" button.  Each bit that is set disables the corresponding length or number of platforms.

For compatibility with "largestations off", at least one length between 1 and 5 (bits 0 to 4) and one number of platforms between 1 and 4 (bits 0 to 3) must be available, i.e. at least one of these bits must be unset.

=== Define custom layout (0E) ===

This allows choosing which tile type is built at which tile of a newly built

station.  There are four different types, which TTD normally defines as

{| |-
!Tile type!!Appearance
|-
|00||plain platform
|-
|02||platform with building
|-
|04||platform with roof, left side
|-
|06||platform with roof, right side
|}

These numbers are used for stations in NE-SW direction, or these numbers plus one for stations in the NW-SE direction.  To define a custom layout, use this format:

{| |-
!Size!!Name!!Meaning
|-
|B||length||length of platforms for this layout
|-
|B||number||number of platforms for this layout
|-
|V||tiles||length*number bytes of tile types, one platform after another, only 00, 02, 04 or 06 are allowed as values
|}

Repeat this as often as necessary to define the layouts for all supported combinations of length and number.  End the definitions with a 00 00 (zero length and zero number).  Any combinations that are not defined will be built using TTD's default layout.
Note that it may be easier to draw different sprite sets using a [[VariationalAction2|VarAction2]] based on [[VarAction2Stations#Platform info 40 41 46 47 49|station variable 40]], rather than redefining the layout.  In addition, [[Callbacks#Custom station layout 24|callback 24]] will be used to further customize the layout as defined by this property (or by TTD if no prop 0E layout is available). This may also be easier than defining a prop 0E layout for every combination of length and number of platforms.

=== Copy custom layout (0F) ===

Similar to property 0A, this copies the custom layout from the station-ID given by the argument.

=== Little/lots threshold (10) ===
Amount of cargo for switching from "little" to "lots" of cargo.  TTDPatch separates the full range of cargo amounts (0 to 4095) into two separate subranges, "little" and "lots" of cargo.  This allows better control of cargo amount based graphics (if needed).  Property 10 specifies at what amount of cargo the patch is to switch from one to the other subrange.  See [[Action2Stations|Action 2 for stations]] for more information.

=== Pylon placement (11) and wire placement (14) ===
Prop. 11 sets which tile types should have pylons when used with electrified tracks. By default, tiles 0-3 (default stations without roof) have pylons, and tiles 4-7 (default stations with roof) don't. This is a bit mask of tile types, with a bit set meaning that a pylon should be drawn. The tile types here do not consider [[Callbacks#Station sprite layout 14|callback 14]], but rather the type as it was built, i.e. from prop. 0E.

Prop. 14 works in a similar way, except that it sets the tile types on which there should be ''no'' wires displayed. With the default value of "00", wires are displayed everywhere, and for each bit set, the wire is omitted on that tile type.

This property should only be used when the wires cause problems with the sprite sorter, because even when the wire is obscured by a station hall or similar, it should still show up in transparent mode so that each tile can easily be verified as being electrified.

=== Cargo types for random triggers (12) ===

This sets which cargo types should trigger re-randomizing. The cargo types are given as a bitmask of the bits from column 3 (type B) in CargoTypes.  If nothing is set (the default), the no random triggers will happen, to conserve CPU time.

With GRF version 7 and above, the interpretation of bits changes. Instead of climate-dependent cargo slot numbers (type B), you have to set the bits of climate-independent cargo ID (type A).

=== General Flags (13) ===

{| |-
!Bit!!Value!!Version!!Meaning
|-
|0||1||{{ottdp|0.7|2.5}}||use different sprite set for ground sprites ([[GlobalVariables#Extra_callback_info_.2810_.2F_-.29_and_.2818_.2F_-.29|var. 10]] is 1 for ground sprites, 0 otherwise)
|-
|1||2||{{ottdp|0.6|2.5}}||when calculating the cargo amount to display, divide the amount by the station size (to simulate cargo distributed over the area of the station)
|-
|2||4||{{ottdp|0.7|2.5}}||[[Callbacks#Next animation frame (1A/26/141/153/158)|callback 141]] needs random bits in var. 10
|-
|3||8||{{ottdp|1.0|2.6}}||Use custom foundations on sloped tiles (the lowest byte of [[GlobalVariables#Extra_callback_info_.2810_.2F_-.29_and_.2818_.2F_-.29|var. 10]] is 2 for foundation sprites)
|-
|4||10||{{ottdp|1.0|2.6}}||When bit 3 is set, use extended foundation block instead of the simple one
|}

Bit 3 works somewhat similarly to bit 0: your sprite selection will be called again, with 2 in the lowest byte of [[GlobalVariables#Extra_callback_info_.2810_.2F_-.29_and_.2818_.2F_-.29|variable 10]]. If the chain ends on a callback result, the program will assume the foundation selection has failed and will use the default foundaton sprites. The low word of [[GlobalVariables#Extra_callback_info_.2810_.2F_-.29_and_.2818_.2F_-.29|variable 18]] will contain the tile type of the current tile; if you have [[Callbacks#Station sprite layout (14)|callback 14]] enabled, this will be the its return value - otherwise, the default TTD types (platform with building, platform with left roof etc.) are used. In either case, one is added for the NW-SE orientation, in case your station needs different foundations depending on its orientation. Bits 16 and 17 are set if the NW and and NE foundations are to merged with the corresponding neighbour tile, so you shouldn't draw the corresponding edge in the foundation sprite. Other bits of variable 10 and variable 18 are reserved for future use.

Your sprite selection code should select a foundation sprite block. The contents of this block depends on whether bit 4 is set or not.
* Bit 4 clear (simple foundations):
[[File:simple_foundations.png]]

The programme will combine the needed foundation from these 8 sprites depending on the current slope. You don't need to care about the merge data in bits 16..17 of [[GlobalVariables#Extra_callback_info_.2810_.2F_-.29_and_.2818_.2F_-.29|variable 18]]; it will be taken care of that automatically by adding the 7th and 8th sprite only when necessary.
* Bit 4 set (extended foundations):
[[File:extended_foundations.png]]

You need to have one sprite for every slope that's possible below a rail station. The correct one will be automatically selected depending on the current slope. It can't handle the merging itself, however, so you need four foundation blocks: one with no edges removed, one with the NW edge removed, one with the NE edge removed and one with both north edges removed. Your sprite selection code is responsible for selecting the correct of those blocks according to the merge info in [[GlobalVariables#Extra_callback_info_.2810_.2F_-.29_and_.2818_.2F_-.29|variable 18]].

In both cases, you can put an additional value into register 100h, which will serve as an offset into the selected block. If you don't modify register 100h during the chain, it will default to 0. It is important that the dimensions of these sprites remain the same - thus bit 6 in the real sprites must be set to prevent GRFCodec from trimming the empty blue areas. The offset of these foundations must be -31 to the X direction and -9 to the Y direction.

=== Can train enter tile (15) ===

Like props. 11 and 14, this value contains eight bits relating to the eight possible tile types. If a bit is set, trains are prevented from routing through or entering any tile of this type.

=== Animation information (16) ===

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 station (this is the default value).
Since you can't have properties for individual station tiles, this property applies for every tile of the station. If you don't want to animate some tiles, you should check the current position during [[Callbacks#Animation control (1B/25/140/152/159)|callback 140]] and return FD if the current tile doesn't need to be animated. If you also need animations of different length per tile, you'll have to use [[Callbacks#Next animation frame (1A/26/141/153/158)|callback 141]] for that.

=== Animation speed (17) ===
The meaning is the same as for [[Action0Houses#Animation Speed 1B|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 (18) ===
This is a bit mask of events that should trigger [[Callbacks#Animation control (1B/25/140/152/159)|callback 140]], allowing to change the animation state

{| |-
!Bit!!Value!!Version!!Meaning!!Happens on!!Var 18
|-
|0||1||{{ottdp|0.7|2.5}}||Station part is built||the newly built tiles||
|-
|1||2||{{ottdp|0.7|2.5}}||New cargo arrives to station||whole station||<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>
|-
|2||4||{{ottdp|0.7|2.5}}||A cargo type gets removed from station||whole station||<ref name="cargotype"/>
|-
|3||8||{{ottdp|0.7|2.5}}||Train enters station (starts loading/unloading)||platform where the train is||
|-
|4||10||{{ottdp|0.7|2.5}}||Train leaves station (done loading/unloading)||platform where the train is||
|-
|5||20||{{ottdp|1.2|2.5|ottdrev=r22746}}||Train loads/unloads cargo||platform where the train is||
|-
|6||40||{{ottdp|0.7|2.5}}||Every 250 ticks||whole station||
|}

The remaining bits are reserved for future triggers, they must be zero for now.

The "happens on" column tells which tiles will [[Callbacks#Animation control (1B/25/140/152/159) |callback 140]] be called on.

<references/>

=== Road routing (19 - reserved for future use) ===

Will allow to have routing informations for road vehicles on rail stations,

generally you need to deny rail vehicle traveling via prop 15

This property is not yet implemented {{ottd|no}}{{ttdp|no}}.

=== Advanced sprite layout with register modifiers (1A) ===

{{ottdp|1.2|no|ottdrev=r22518}}
Format:
1A <num-layouts> <0x40 + num-sprites>
<groundsprite> <flags> [<register/value>]...
[ <buildingsprite> <flags>
( <xoffset> <yoffset> <zoffset> <xextent> <yextent> <zextent>
| <xpixeloffset> <ypixeloffset> 80)
[<register/value>]...
]...

For further details see [http://wiki.openttd.org/Frosch/Advanced_Sprite_Layout#Stations here] for now.

=== Minimum bridge height (1B) ===

This property allows building bridges over stations.

The bridge height property defines minimum clearances required for a bridge for each of the four [[Action0/Stations#Define_custom_layout_.280E.29|tile types]] of this station (or zero to not allow any bridge). Values are given in "height level" units (1 level == 8px).

{| class="wikitable" |-
!Height (1)!!Appearance
|-
| style="text-align:center;" |x1 y1 ||plain platform
|-
| style="text-align:center;" |x2 y2 ||platform with building
|-
| style="text-align:center;" |x3 y3 ||platform with roof, left side
|-
| style="text-align:center;" |x4 y4 ||platform with roof, right side
|}
(1) where the values are one byte pairs (x-direction, y-direction) expressed in hexadecimal notation.

Syntax:

1B <1st pair> <2nd pair> <3rd pair> <4th pair><br />
1B x1 y1 x2 y2 x3 y3 x4 y4<br />
1B 01 01 02 02 03 03 03 03 // 8px 16px 24px 24px

This property is currently only available for the developmental "New Map Features" (NMF) fork of OpenTTD.

== Examples ==

=== Using TTD's sprite layouts for certain tiles ===

To use TTD's layout, you use <code>00 00 00 00</code> for the ground sprite number and leave off everything else.

So instead of for example

F4 03 00 00
00 00 00 10 05 02 2E 84 00 00
00 0B 00 10 05 02 30 84 00 00
80

you just put

00 00 00 00

=== Using transparent sprites ===

You can use transparent sprites to make for example the roof translucent like in TTD's stations. The roof of TTD's stations is made like this:

00 00 10 10 10 0A 37 84 00 00
00 00 80 00 00 00 3B 44 22 03

The first sprite here is the non-transparent frame of the roof, drawn in company colours (it has bit 15 set). The second part is a special "linked" sprite without its own bounding box, it shares that of the previous sprite. That's done by setting the z offset to 80.

To make that second sprite transparent, bit 14 is set in the sprite number, and the upper word is set to 322 (*), so 0322443B means to take sprite 43B and draw it in transparent mode. The colours of that sprite are ignored entirely, every pixel in colour 0 is fully transparent, and all other pixels are semi-transparent (essentially just causing what they are drawn over to become darker).

(*) This is the [[RecolorSprites#Default_recolour_sprites | recolour sprite]] for the glass effect.

Language IDs

2016-04-07T16:27:32Z

Planetmaker: Link to plural forms. That column is NOT the number of plurals

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

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

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

NML:Industries

2015-08-26T10:52:06Z

Planetmaker: /* Industry properties */ elaborate more on 'prob_random'

{{NMLNavPropVarCB}}

This page contains information on industry properties, variables and callbacks. [[NML:IndustryTiles|Industry tiles]] are closely related.

== Industry ID allocation ==
Industry IDs are local to the NewGRF, you are free to choose any ID in the 0..127-range. You should start your item definition with the 'substitute'-property, which allocates a new industry. The value of this property should be the ID of a [[IndustryDefaultProps|default industry]], 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 industry to be replaced with your item. You should use this if you are for example defining a coal mine which changes production more dynamically. If your type is not a direct replacement of an existing item, don't set this property.

==Industry properties==

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

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

===Industry special flags===

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

{{NML:IndustryCommonVariables}}

==Industry variables==

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

<br /> Variables that require some parameters.

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

==Industry callbacks==

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

{{NML:LocationCheckResults}}

===Production change callback results===

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

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

===Industry creation types===

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

NML:Industries

2015-07-08T08:57:14Z

Planetmaker: /* Industry callbacks */ Use version template for minimum OpenTTD version

{{NMLNavPropVarCB}}

This page contains information on industry properties, variables and callbacks. [[NML:IndustryTiles|Industry tiles]] are closely related.

== Industry ID allocation ==
Industry IDs are local to the NewGRF, you are free to choose any ID in the 0..127-range. You should start your item definition with the 'substitute'-property, which allocates a new industry. The value of this property should be the ID of a [[IndustryDefaultProps|default industry]], 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 industry to be replaced with your item. You should use this if you are for example defining a coal mine which changes production more dynamically. If your type is not a direct replacement of an existing item, don't set this property.

==Industry properties==

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

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

===Industry special flags===

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

{{NML:IndustryCommonVariables}}

==Industry variables==

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

<br /> Variables that require some parameters.

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

==Industry callbacks==

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

{{NML:LocationCheckResults}}

===Production change callback results===

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

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

===Industry creation types===

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

NML:Getting started

2015-04-11T07:35:39Z

Planetmaker: /* Syntax highlighting */ Update links

{{NMLNavNoSubpages}}

== What is NML? ==
NML is a a python-based compiler, capable to compile NML files (along with their associated language, sound and graphic files) into grf and / or nfo files.

== Installation ==
=== pip ===
If you are familiar with python and pip then you can just use
pip install nml
This will install the required dependancies. Note that you may need administrator privileges for this to work.

=== Windows ===
Windows users can install the [http://bundles.openttdcoop.org/nml/nightlies/LATEST/ windows binary] which contains a binary which bundles (most) required libraries.

If execution fails due to missing MSVCR libraries or due to an invalid application configuration or similar error, you need to install [http://www.microsoft.com/en-gb/download/details.aspx?id=5555 this package from Microsoft].

If you go for a python install and the packages themselves (e.g. mingw or msys) instead of the pre-compiled binary: Apparently you can prevent a lot of problems by installing the 32bit version of python, even if you have a 64bit windows installation. Installing PIL might be troublesome if you do install the 64bit version of python.

=== Linux ===
Users on other OS need to install them separately, best by means of their packet manager. In order to work, the following items are required:

* '''python'''
** python 3.2 or newer (for nightly builds or NML 0.4.0 or newer, earlier versions require python 2.6 or 2.7)
** downloadable from from http://www.python.org/)
* '''python image library'''
** downloadable from https://pypi.python.org/pypi/Pillow/
* '''ply'''
** downloadable from http://www.dabeaz.com/ply/
* '''NML itself'''
** the latest (nightly) build can be downloaded from http://bundles.openttdcoop.org/nml/push/LATEST/

If you don't install these with the packet manager of your choice (or there is none like on windows and you don't use the pre-compiled binary file), you should install these libraries as well as NML itself using <code style="color:darkgreen">python setup.py install</code> from your command prompt.

For debian or ubunutu you might try to use pip for PIL/pillow when it is not in the package manager for python3:
sudo apt-get install python3
sudo apt-get install python3-ply
sudo apt-get install pip
sudo /usr/bin/pip-3.2 install pillow

=== OSX ===
OS X users have two choices: install the dependencies manually as described in the Linux section above, for use with the python version that ships with OS X. Or install everything from macports, including a new python version (using macports eases upgrading). However using macports to install the dependencies for the bundled system python is likely to fail.

=== Installing manually (any system) ===
We assume that you have a python setup (2.6 ... 2.7) where the distutils are available so that setup.py can be executed. You'll additionally need a gcc compiler in your path. On linux it is strongly recommended to use your package manager to install these packages.

==== Install PLY ====
This is easy. Get the library from the link as mentioned above.
Install it from the unpacked PLY directory via
sudo python setup.py install

==== Install the Python Imaging Library (PIL) ====
Get the library from the above mentioned link (the source kit for PIL 1.1.7). From the PIL source directory, test the setup for all available dependencies:
python setup.py build_ext -i
You should get an output like which concludes with a summary of the available dependencies:
PIL 1.1.7 SETUP SUMMARY
--------------------------------------------------------------------
--- TKINTER support available
--- JPEG support available
--- ZLIB (PNG/ZIP) support available
--- FREETYPE2 support available
--- LITTLECMS support available
--------------------------------------------------------------------
If you're missing zlib or jpeg support, install those libraries, too.

If that build shows everything available, test the setup:
python selftest.py
A successful selftest will result in
--------------------------------------------------------------------
PIL 1.1.7 TEST SUMMARY
--------------------------------------------------------------------
Python modules loaded from ./PIL
Binary modules loaded from ./PIL
--------------------------------------------------------------------
--- PIL CORE support ok
--- TKINTER support ok
--- JPEG support ok
--- ZLIB (PNG/ZIP) support ok
--- FREETYPE2 support ok
--- LITTLECMS support ok
--------------------------------------------------------------------
Running selftest:
--- 57 tests passed.
If all is successful, finally install the library:
sudo python setup.py install

==== Install NML ====
Now, that you have installed ply and pil, then you can install NML from the unpacked nml directory:
sudo python setup.py install

== Testing the installation ==
To verify that everything is installed, enter <code style="color:darkgreen">nmlc --version</code> in your command line. This should output the version of NML as well as the version of the installed libraries.

Examples for small NML "projects" are found in the <code style="color:darkgreen">examples</code> and <code style="color:darkgreen">regression</code> folder of NML. Generally it's assumed that the language files are in a separate language folder <code style="color:darkgreen">lang</code>, thus a simple project may look like this:

mynewgrf.nml
graphics.png
funny_sound.wav

lang/english.lng

The compiler itself <code style="color:darkgreen">nmlc</code> is a command line tool and can take a number of parameters, at least the nml filename which it shall process, e.g. <code style="color:darkgreen">nmlc mynewgrf.nml</code> will compile your nml file into the grf-file <code style="color:darkgreen">mynewgrf.grf</code>.

The full syntax is:

Usage: nmlc [options] <filename>
Where <filename> is the nml file to parse

Options:
--version show program's version number and exit
-h, --help show this help message and exit
-d, --debug write the AST to stdout
-s, --stack Dump stack when an error occurs
--grf=<file> write the resulting grf to <file>
--md5=<file> Write an md5sum of the resulting grf to <file>
--nfo=<file> write nfo output to <file>
-M output a rule suitable for make describing the
graphics dependencies of the main grf file (requires
input file or --grf)
--MF=<file> When used with -M, specifies a file to write the
dependencies to
--MT=<file> target of the rule emitted by dependency generation
(requires -M)
-c crop extraneous transparent blue from real sprites
-u save uncompressed data in the grf file
--nml=<file> write optimized nml to <file>
-o <file>, --output=<file>
write output(nfo/grf) to <file>
-t <file>, --custom-tags=<file>
Load custom tags from <file> [default:
custom_tags.txt]
-l <dir>, --lang-dir=<dir>
Load language files from directory <dir> [default:
lang]
--default-lang=<file>
The default language is stored in <file> [default:
english.lng]
--start-sprite=<num> Set the first sprite number to write (do not use
except when you output nfo that you want to include in
other files)
-p <palette>, --palette=<palette>
Force nml to use the palette <pal> [default: ANY].
Valid values are 'DEFAULT', 'LEGACY', 'ANY'
--quiet Disable all warnings. Errors will be printed normally.
-n, --no-cache Disable caching of sprites in .cache[index] files,
which may reduce compilation time.

== Syntax highlighting ==
For some editors a matching syntax highlighting file is generated for each build of NML:

* [http://bundles.openttdcoop.org/nml/push/LATEST/nml_notepadpp.xml Notepad++]
* [http://bundles.openttdcoop.org/nml/push/LATEST/nml_kate.xml Kate]

For a few editors there exist syntax highlighting rules, made at a certain point, see the [http://dev.openttdcoop.org/projects/home/documents DevZone documents] for details. These files might be more or less outdated and not support the full syntax of NML:
* [http://dev.openttdcoop.org/documents/26 Geany]
Please make available to us any updates you might have made. If you want the highlighting files automatically generated for your editor, we'll happily accept patches. See [https://hg.openttdcoop.org/nml/files/tip/nml/editors here] for the existing generation scripts.

NML:Getting started

2015-04-11T07:26:37Z

Planetmaker: /* Windows */ some hint on python 32bit vs 64 bit

{{NMLNavNoSubpages}}

== What is NML? ==
NML is a a python-based compiler, capable to compile NML files (along with their associated language, sound and graphic files) into grf and / or nfo files.

== Installation ==
=== pip ===
If you are familiar with python and pip then you can just use
pip install nml
This will install the required dependancies. Note that you may need administrator privileges for this to work.

=== Windows ===
Windows users can install the [http://bundles.openttdcoop.org/nml/nightlies/LATEST/ windows binary] which contains a binary which bundles (most) required libraries.

If execution fails due to missing MSVCR libraries or due to an invalid application configuration or similar error, you need to install [http://www.microsoft.com/en-gb/download/details.aspx?id=5555 this package from Microsoft].

If you go for a python install and the packages themselves (e.g. mingw or msys) instead of the pre-compiled binary: Apparently you can prevent a lot of problems by installing the 32bit version of python, even if you have a 64bit windows installation. Installing PIL might be troublesome if you do install the 64bit version of python.

=== Linux ===
Users on other OS need to install them separately, best by means of their packet manager. In order to work, the following items are required:

* '''python'''
** python 3.2 or newer (for nightly builds or NML 0.4.0 or newer, earlier versions require python 2.6 or 2.7)
** downloadable from from http://www.python.org/)
* '''python image library'''
** downloadable from https://pypi.python.org/pypi/Pillow/
* '''ply'''
** downloadable from http://www.dabeaz.com/ply/
* '''NML itself'''
** the latest (nightly) build can be downloaded from http://bundles.openttdcoop.org/nml/push/LATEST/

If you don't install these with the packet manager of your choice (or there is none like on windows and you don't use the pre-compiled binary file), you should install these libraries as well as NML itself using <code style="color:darkgreen">python setup.py install</code> from your command prompt.

For debian or ubunutu you might try to use pip for PIL/pillow when it is not in the package manager for python3:
sudo apt-get install python3
sudo apt-get install python3-ply
sudo apt-get install pip
sudo /usr/bin/pip-3.2 install pillow

=== OSX ===
OS X users have two choices: install the dependencies manually as described in the Linux section above, for use with the python version that ships with OS X. Or install everything from macports, including a new python version (using macports eases upgrading). However using macports to install the dependencies for the bundled system python is likely to fail.

=== Installing manually (any system) ===
We assume that you have a python setup (2.6 ... 2.7) where the distutils are available so that setup.py can be executed. You'll additionally need a gcc compiler in your path. On linux it is strongly recommended to use your package manager to install these packages.

==== Install PLY ====
This is easy. Get the library from the link as mentioned above.
Install it from the unpacked PLY directory via
sudo python setup.py install

==== Install the Python Imaging Library (PIL) ====
Get the library from the above mentioned link (the source kit for PIL 1.1.7). From the PIL source directory, test the setup for all available dependencies:
python setup.py build_ext -i
You should get an output like which concludes with a summary of the available dependencies:
PIL 1.1.7 SETUP SUMMARY
--------------------------------------------------------------------
--- TKINTER support available
--- JPEG support available
--- ZLIB (PNG/ZIP) support available
--- FREETYPE2 support available
--- LITTLECMS support available
--------------------------------------------------------------------
If you're missing zlib or jpeg support, install those libraries, too.

If that build shows everything available, test the setup:
python selftest.py
A successful selftest will result in
--------------------------------------------------------------------
PIL 1.1.7 TEST SUMMARY
--------------------------------------------------------------------
Python modules loaded from ./PIL
Binary modules loaded from ./PIL
--------------------------------------------------------------------
--- PIL CORE support ok
--- TKINTER support ok
--- JPEG support ok
--- ZLIB (PNG/ZIP) support ok
--- FREETYPE2 support ok
--- LITTLECMS support ok
--------------------------------------------------------------------
Running selftest:
--- 57 tests passed.
If all is successful, finally install the library:
sudo python setup.py install

==== Install NML ====
Now, that you have installed ply and pil, then you can install NML from the unpacked nml directory:
sudo python setup.py install

== Testing the installation ==
To verify that everything is installed, enter <code style="color:darkgreen">nmlc --version</code> in your command line. This should output the version of NML as well as the version of the installed libraries.

Examples for small NML "projects" are found in the <code style="color:darkgreen">examples</code> and <code style="color:darkgreen">regression</code> folder of NML. Generally it's assumed that the language files are in a separate language folder <code style="color:darkgreen">lang</code>, thus a simple project may look like this:

mynewgrf.nml
graphics.png
funny_sound.wav

lang/english.lng

The compiler itself <code style="color:darkgreen">nmlc</code> is a command line tool and can take a number of parameters, at least the nml filename which it shall process, e.g. <code style="color:darkgreen">nmlc mynewgrf.nml</code> will compile your nml file into the grf-file <code style="color:darkgreen">mynewgrf.grf</code>.

The full syntax is:

Usage: nmlc [options] <filename>
Where <filename> is the nml file to parse

Options:
--version show program's version number and exit
-h, --help show this help message and exit
-d, --debug write the AST to stdout
-s, --stack Dump stack when an error occurs
--grf=<file> write the resulting grf to <file>
--md5=<file> Write an md5sum of the resulting grf to <file>
--nfo=<file> write nfo output to <file>
-M output a rule suitable for make describing the
graphics dependencies of the main grf file (requires
input file or --grf)
--MF=<file> When used with -M, specifies a file to write the
dependencies to
--MT=<file> target of the rule emitted by dependency generation
(requires -M)
-c crop extraneous transparent blue from real sprites
-u save uncompressed data in the grf file
--nml=<file> write optimized nml to <file>
-o <file>, --output=<file>
write output(nfo/grf) to <file>
-t <file>, --custom-tags=<file>
Load custom tags from <file> [default:
custom_tags.txt]
-l <dir>, --lang-dir=<dir>
Load language files from directory <dir> [default:
lang]
--default-lang=<file>
The default language is stored in <file> [default:
english.lng]
--start-sprite=<num> Set the first sprite number to write (do not use
except when you output nfo that you want to include in
other files)
-p <palette>, --palette=<palette>
Force nml to use the palette <pal> [default: ANY].
Valid values are 'DEFAULT', 'LEGACY', 'ANY'
--quiet Disable all warnings. Errors will be printed normally.
-n, --no-cache Disable caching of sprites in .cache[index] files,
which may reduce compilation time.

== Syntax highlighting ==
For a few editors there exist syntax highlighting rules, see the [http://dev.openttdcoop.org/projects/home/documents DevZone documents] for details.
There are rules for
* [http://dev.openttdcoop.org/documents/26 Geany]
* [http://dev.openttdcoop.org/documents/24 Notepad++]
* [http://dev.openttdcoop.org/documents/38 Kate]

NML:Getting started

2015-04-11T07:25:08Z

Planetmaker: /* Linux */ rework linux instructions slightly

{{NMLNavNoSubpages}}

== What is NML? ==
NML is a a python-based compiler, capable to compile NML files (along with their associated language, sound and graphic files) into grf and / or nfo files.

== Installation ==
=== pip ===
If you are familiar with python and pip then you can just use
pip install nml
This will install the required dependancies. Note that you may need administrator privileges for this to work.

=== Windows ===
Windows users can install the [http://bundles.openttdcoop.org/nml/nightlies/LATEST/ windows binary] which contains a binary which bundles (most) required libraries.

If execution fails due to missing MSVCR libraries or due to an invalid application configuration or similar error, you need to install [http://www.microsoft.com/en-gb/download/details.aspx?id=5555 this package from Microsoft].

=== Linux ===
Users on other OS need to install them separately, best by means of their packet manager. In order to work, the following items are required:

* '''python'''
** python 3.2 or newer (for nightly builds or NML 0.4.0 or newer, earlier versions require python 2.6 or 2.7)
** downloadable from from http://www.python.org/)
* '''python image library'''
** downloadable from https://pypi.python.org/pypi/Pillow/
* '''ply'''
** downloadable from http://www.dabeaz.com/ply/
* '''NML itself'''
** the latest (nightly) build can be downloaded from http://bundles.openttdcoop.org/nml/push/LATEST/

If you don't install these with the packet manager of your choice (or there is none like on windows and you don't use the pre-compiled binary file), you should install these libraries as well as NML itself using <code style="color:darkgreen">python setup.py install</code> from your command prompt.

For debian or ubunutu you might try to use pip for PIL/pillow when it is not in the package manager for python3:
sudo apt-get install python3
sudo apt-get install python3-ply
sudo apt-get install pip
sudo /usr/bin/pip-3.2 install pillow

=== OSX ===
OS X users have two choices: install the dependencies manually as described in the Linux section above, for use with the python version that ships with OS X. Or install everything from macports, including a new python version (using macports eases upgrading). However using macports to install the dependencies for the bundled system python is likely to fail.

=== Installing manually (any system) ===
We assume that you have a python setup (2.6 ... 2.7) where the distutils are available so that setup.py can be executed. You'll additionally need a gcc compiler in your path. On linux it is strongly recommended to use your package manager to install these packages.

==== Install PLY ====
This is easy. Get the library from the link as mentioned above.
Install it from the unpacked PLY directory via
sudo python setup.py install

==== Install the Python Imaging Library (PIL) ====
Get the library from the above mentioned link (the source kit for PIL 1.1.7). From the PIL source directory, test the setup for all available dependencies:
python setup.py build_ext -i
You should get an output like which concludes with a summary of the available dependencies:
PIL 1.1.7 SETUP SUMMARY
--------------------------------------------------------------------
--- TKINTER support available
--- JPEG support available
--- ZLIB (PNG/ZIP) support available
--- FREETYPE2 support available
--- LITTLECMS support available
--------------------------------------------------------------------
If you're missing zlib or jpeg support, install those libraries, too.

If that build shows everything available, test the setup:
python selftest.py
A successful selftest will result in
--------------------------------------------------------------------
PIL 1.1.7 TEST SUMMARY
--------------------------------------------------------------------
Python modules loaded from ./PIL
Binary modules loaded from ./PIL
--------------------------------------------------------------------
--- PIL CORE support ok
--- TKINTER support ok
--- JPEG support ok
--- ZLIB (PNG/ZIP) support ok
--- FREETYPE2 support ok
--- LITTLECMS support ok
--------------------------------------------------------------------
Running selftest:
--- 57 tests passed.
If all is successful, finally install the library:
sudo python setup.py install

==== Install NML ====
Now, that you have installed ply and pil, then you can install NML from the unpacked nml directory:
sudo python setup.py install

== Testing the installation ==
To verify that everything is installed, enter <code style="color:darkgreen">nmlc --version</code> in your command line. This should output the version of NML as well as the version of the installed libraries.

Examples for small NML "projects" are found in the <code style="color:darkgreen">examples</code> and <code style="color:darkgreen">regression</code> folder of NML. Generally it's assumed that the language files are in a separate language folder <code style="color:darkgreen">lang</code>, thus a simple project may look like this:

mynewgrf.nml
graphics.png
funny_sound.wav

lang/english.lng

The compiler itself <code style="color:darkgreen">nmlc</code> is a command line tool and can take a number of parameters, at least the nml filename which it shall process, e.g. <code style="color:darkgreen">nmlc mynewgrf.nml</code> will compile your nml file into the grf-file <code style="color:darkgreen">mynewgrf.grf</code>.

The full syntax is:

Usage: nmlc [options] <filename>
Where <filename> is the nml file to parse

Options:
--version show program's version number and exit
-h, --help show this help message and exit
-d, --debug write the AST to stdout
-s, --stack Dump stack when an error occurs
--grf=<file> write the resulting grf to <file>
--md5=<file> Write an md5sum of the resulting grf to <file>
--nfo=<file> write nfo output to <file>
-M output a rule suitable for make describing the
graphics dependencies of the main grf file (requires
input file or --grf)
--MF=<file> When used with -M, specifies a file to write the
dependencies to
--MT=<file> target of the rule emitted by dependency generation
(requires -M)
-c crop extraneous transparent blue from real sprites
-u save uncompressed data in the grf file
--nml=<file> write optimized nml to <file>
-o <file>, --output=<file>
write output(nfo/grf) to <file>
-t <file>, --custom-tags=<file>
Load custom tags from <file> [default:
custom_tags.txt]
-l <dir>, --lang-dir=<dir>
Load language files from directory <dir> [default:
lang]
--default-lang=<file>
The default language is stored in <file> [default:
english.lng]
--start-sprite=<num> Set the first sprite number to write (do not use
except when you output nfo that you want to include in
other files)
-p <palette>, --palette=<palette>
Force nml to use the palette <pal> [default: ANY].
Valid values are 'DEFAULT', 'LEGACY', 'ANY'
--quiet Disable all warnings. Errors will be printed normally.
-n, --no-cache Disable caching of sprites in .cache[index] files,
which may reduce compilation time.

== Syntax highlighting ==
For a few editors there exist syntax highlighting rules, see the [http://dev.openttdcoop.org/projects/home/documents DevZone documents] for details.
There are rules for
* [http://dev.openttdcoop.org/documents/26 Geany]
* [http://dev.openttdcoop.org/documents/24 Notepad++]
* [http://dev.openttdcoop.org/documents/38 Kate]

NML:GRF

2015-04-11T07:18:44Z

Planetmaker: /* GRF block */ must be first block. Actions before that are invalid.

{{NMLNavBlocksyntax}}

== GRF block ==

Syntax:

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

Mind: the items enclosed in [...] indicate optional lines: The [] itself are not part of the syntax.
The grf block must be the first block within a NewGRF.

Concerning the choice of the <code style="color:darkgreen">grfid</code>, see [[Action8#GRFID|these]] guidelines

== GRF parameters ==

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

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

Looking at the single entries:

<num>

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

type

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

name

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

desc

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

min_value

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

max_value

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

def_value

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

bit

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

names

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

== A simple example ==

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

NML:IndustryTiles

2015-04-08T19:54:48Z

Planetmaker: /* Industry tile callbacks */ Explicitly mention that tile_check deactivates use of landshape flags

{{NMLNavPropVarCB}}

This page contains information on industry tile properties, variables and callbacks. [[NML:Industries|Industries]] are closely related.

== Industry tile ID allocation ==
Industry tile IDs are local to the NewGRF, you are free to choose any ID in the 0..255-range. You should start your item definition with the 'substitute'-property, which allocates a new industry tile. The value of this property should be the ID of a [[IndustryTileDefaultProps|default industry 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 industry tile to be replaced with your item. You should use this if you are for example defining a coal mine which changes production more dynamically. If your type is not a direct replacement of an existing item, don't set this property.

==Industry tile properties==

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

===Land shape flags===

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

{{NML:IndustryCommonVariables}}

==Industry tile variables==

{| class="t"
! name
! value range
! comment
|-
| construction_state
| 0..3
| Current construction state of the industry tile.
|-
| terrain_type
| TILETYPE_XX
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|-
| town_zone
|
[[NML:List of town zones|town zone]]
| The town zone of the current tile.
|-
| relative_x
| 0..255
| X-coordinate (top right -> bottom left) of the tile relative to the northernmost tile.
|-
| relative_y
| 0..255
| Y-coordinate (top left -> bottom right) of the tile relative to the northernmost tile.
|-
| relative_pos
| 0xYYXX
|
A combination of relative_x and relative_y in the format 0xYYXX. Useful if you want to check for a single position. The [[NML:Builtin functions|builtin function]] relative_coord(x, y) may be useful when making comparisons.
|-
| animation_frame
| 0..255
| Current animation frame.
|}

<br />

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

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

==Industry tile callbacks==

{| class="t"
! callback
! return value
! comment
|-
| default
| Sprite layout
| Graphics for the industry tile
|-
| random_trigger
| N/A
|
See [[NML:Random switch|random switch]] for more information.
|-
| anim_next_frame
| Next animation frame or CB_RESULT_XXX
| Called for every animation frame, returns the next frame to display. Alternatively, return CB_RESULT_NEXT_FRAME or CB_RESULT_STOP_ANIMATION to show the next frame or stop animation, respectively. <code style="color:darkgreen">extra_callback_info1</code> contains random bits, if enabled in the <code style="color:darkgreen">special_flags</code> property. Returning a sound effect in the high byte will cause that sound effect to be played.
|-
| anim_control
| Next animation frame or CB_RESULT_XXX
|
Called whenever an animation trigger happens. Return the animation frame to show, or CB_RESULT_XXX with XXX = [CB_RESULT_START_ANIMATION <nowiki>|</nowiki> STOP_ANIMATION <nowiki>|</nowiki> DO_NOTHING] to respectively start the animation in its current frame, stop the animation or do nothing. <code style="color:darkgreen">extra_callback_info1</code> contains random bits, if enabled in the <code style="color:darkgreen">special_flags</code> property. Returning a sound effect in the high byte will cause that sound effect to be played. <code style="color:darkgreen">extra_callback_info2</code> contains the reason to trigger the animation, see the [[#Animation triggers|table]] below. Note that you need to enable the wanted triggers in the <code style="color:darkgreen">animation_triggers</code> property.
|-
| anim_speed
| 0 .. 16
| Decide the time an animation frame should last. Return value is interpreted as (num_ticks = 2^anim_speed), which each tick lasting 30 ms. Avoid using this callback if possible, since it has to be called each tick for every animated tile. This can be used to create animation frames that last between 30 ms and 33 minutes.
|-
| cargo_type_accept
| type1 + (type2 << 5) + (type3 << 10)
| Decide the cargo types that this tile accepts. If this callback is not implemented or fails, the values from <code style="color:darkgreen">accepted_cargos</code> are used instead. Bits 0..4: First cargo type. Bits 5..9: Second cargo type. Bits 10..14: Third cargo type.
|-
| cargo_amount_accept
| amt1 + (amt2 << 4) + (amt3 << 8)
| Acceptance for each cargo amount in 1/8th. If this callback is not implemented or fails, the values from <code style="color:darkgreen">accepted_cargos</code> are used instead. Cargo types are from the <code style="color:darkgreen">cargo_type_accept</code> callback, or the <code style="color:darkgreen">accepted_cargos</code> property if that callback failed. Bits 0..3: Acceptance of first cargo type. Bits 4..7: Acceptance of second cargo type. Bits 8..11: Acceptance of third cargo type.
|-
| tile_check
|
Same as for the [[#Location check results|location_check]] industry callback
|
Called before constructing the industry, so nothing exists on the map yet. Since the industry isn't built yet, so you can't access industry variables. From the tile variables, relative x/y/position, town zone are available, as well as the class, height, slope, terrain type and water status of nearby tiles. <code style="color:darkgreen">extra_callback_info2</code> contains the industry layout number in the lowest (first) byte and the [[#Industry creation types|creation type]] in the second byte. Note: use of this callback will deactivate the use of the landshape flags. If this callback is not implemented or fails, the <code style="color:darkgreen">land_shape_flags</code> property will be used instead to determine if the slope is suitable. This also means that without this callback, the tile may not be built on steep slopes.
|-
| foundations
| CB_RESULT[_NO]_FOUNDATIONS
| Return CB_RESULT_FOUNDATIONS to draw standard foundations (default) or CB_RESULT_NO_FOUNDATIONS to not draw them.
|-
| autoslope
| CB_RESULT[_NO]_AUTOSLOPE
| Return CB_RESULT_AUTOSLOPE to allow autoslope (altering the ground below a tile) or CB_RESULT_NO_AUTOSLOPE to disallow it.
|}

{{NML:LocationCheckResults}}

===Animation triggers===

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

NML:IndustryTiles

2015-04-08T19:53:05Z

Planetmaker: /* Land shape flags */ use callback name instead of its hex equivalent

{{NMLNavPropVarCB}}

This page contains information on industry tile properties, variables and callbacks. [[NML:Industries|Industries]] are closely related.

== Industry tile ID allocation ==
Industry tile IDs are local to the NewGRF, you are free to choose any ID in the 0..255-range. You should start your item definition with the 'substitute'-property, which allocates a new industry tile. The value of this property should be the ID of a [[IndustryTileDefaultProps|default industry 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 industry tile to be replaced with your item. You should use this if you are for example defining a coal mine which changes production more dynamically. If your type is not a direct replacement of an existing item, don't set this property.

==Industry tile properties==

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

===Land shape flags===

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

{{NML:IndustryCommonVariables}}

==Industry tile variables==

{| class="t"
! name
! value range
! comment
|-
| construction_state
| 0..3
| Current construction state of the industry tile.
|-
| terrain_type
| TILETYPE_XX
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|-
| town_zone
|
[[NML:List of town zones|town zone]]
| The town zone of the current tile.
|-
| relative_x
| 0..255
| X-coordinate (top right -> bottom left) of the tile relative to the northernmost tile.
|-
| relative_y
| 0..255
| Y-coordinate (top left -> bottom right) of the tile relative to the northernmost tile.
|-
| relative_pos
| 0xYYXX
|
A combination of relative_x and relative_y in the format 0xYYXX. Useful if you want to check for a single position. The [[NML:Builtin functions|builtin function]] relative_coord(x, y) may be useful when making comparisons.
|-
| animation_frame
| 0..255
| Current animation frame.
|}

<br />

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

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

==Industry tile callbacks==

{| class="t"
! callback
! return value
! comment
|-
| default
| Sprite layout
| Graphics for the industry tile
|-
| random_trigger
| N/A
|
See [[NML:Random switch|random switch]] for more information.
|-
| anim_next_frame
| Next animation frame or CB_RESULT_XXX
| Called for every animation frame, returns the next frame to display. Alternatively, return CB_RESULT_NEXT_FRAME or CB_RESULT_STOP_ANIMATION to show the next frame or stop animation, respectively. <code style="color:darkgreen">extra_callback_info1</code> contains random bits, if enabled in the <code style="color:darkgreen">special_flags</code> property. Returning a sound effect in the high byte will cause that sound effect to be played.
|-
| anim_control
| Next animation frame or CB_RESULT_XXX
|
Called whenever an animation trigger happens. Return the animation frame to show, or CB_RESULT_XXX with XXX = [CB_RESULT_START_ANIMATION <nowiki>|</nowiki> STOP_ANIMATION <nowiki>|</nowiki> DO_NOTHING] to respectively start the animation in its current frame, stop the animation or do nothing. <code style="color:darkgreen">extra_callback_info1</code> contains random bits, if enabled in the <code style="color:darkgreen">special_flags</code> property. Returning a sound effect in the high byte will cause that sound effect to be played. <code style="color:darkgreen">extra_callback_info2</code> contains the reason to trigger the animation, see the [[#Animation triggers|table]] below. Note that you need to enable the wanted triggers in the <code style="color:darkgreen">animation_triggers</code> property.
|-
| anim_speed
| 0 .. 16
| Decide the time an animation frame should last. Return value is interpreted as (num_ticks = 2^anim_speed), which each tick lasting 30 ms. Avoid using this callback if possible, since it has to be called each tick for every animated tile. This can be used to create animation frames that last between 30 ms and 33 minutes.
|-
| cargo_type_accept
| type1 + (type2 << 5) + (type3 << 10)
| Decide the cargo types that this tile accepts. If this callback is not implemented or fails, the values from <code style="color:darkgreen">accepted_cargos</code> are used instead. Bits 0..4: First cargo type. Bits 5..9: Second cargo type. Bits 10..14: Third cargo type.
|-
| cargo_amount_accept
| amt1 + (amt2 << 4) + (amt3 << 8)
| Acceptance for each cargo amount in 1/8th. If this callback is not implemented or fails, the values from <code style="color:darkgreen">accepted_cargos</code> are used instead. Cargo types are from the <code style="color:darkgreen">cargo_type_accept</code> callback, or the <code style="color:darkgreen">accepted_cargos</code> property if that callback failed. Bits 0..3: Acceptance of first cargo type. Bits 4..7: Acceptance of second cargo type. Bits 8..11: Acceptance of third cargo type.
|-
| tile_check
|
Same as for the [[#Location check results|location_check]] industry callback
|
Called before constructing the industry, so nothing exists on the map yet. Since the industry isn't built yet, so you can't access industry variables. From the tile variables, relative x/y/position, town zone are available, as well as the class, height, slope, terrain type and water status of nearby tiles. <code style="color:darkgreen">extra_callback_info2</code> contains the industry layout number in the lowest (first) byte and the [[#Industry creation types|creation type]] in the second byte. If this callback is not implemented or fails, the <code style="color:darkgreen">land_shape_flags</code> property will be used instead to determine if the slope is suitable. This also means that without this callback, the tile may not be built on steep slopes.
|-
| foundations
| CB_RESULT[_NO]_FOUNDATIONS
| Return CB_RESULT_FOUNDATIONS to draw standard foundations (default) or CB_RESULT_NO_FOUNDATIONS to not draw them.
|-
| autoslope
| CB_RESULT[_NO]_AUTOSLOPE
| Return CB_RESULT_AUTOSLOPE to allow autoslope (altering the ground below a tile) or CB_RESULT_NO_AUTOSLOPE to disallow it.
|}

{{NML:LocationCheckResults}}

===Animation triggers===

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

NML:Vehicles

2015-03-03T08:31:32Z

Planetmaker: move paragraph on vehicleIDs to the end of the page

{{NMLNavPropVarCB}}
==Properties common to all vehicle types==

{| class="t"
! property
! value range
! available for<br />articulated<br />vehicle
! comment
|-
| <code style="color:green">name</code>
| (string)
| yes
| for example <code style="color:darkgreen">string(STR_NAME_HEREFORD_TRAM)</code>
|-
| <code style="color:green">climates_available</code>
| bitmask(CLIMATE_XXX, CLIMATE_YYY, ...)
| set to <code style="color:green">NO_CLIMATE</code>
|
;CLIMATE_TEMPERATE
;CLIMATE_ARCTIC
;CLIMATE_TROPICAL
;CLIMATE_TOYLAND
;NO_CLIMATE
:Vehicle is availble in no climate (e.g. for articulated parts)
;ALL_CLIMATES
:Vehicle is available irrespective of climate

To make a vehicle available in all climates except toyland you could use: <code style="color:green">ALL_CLIMATES & ~bitmask(CLIMATE_TOYLAND)</code>.
|-
| <code style="color:green">introduction_date</code>
| <code style="color:green">date</code>(yyyy,mm,dd)
| no
| Valid range for yyyy is 0 ... 5000000. In TTDPatch, dates after 2044 will be limited to 2044. Unless the engine is introduced within two years after game-start (always 1920 in TTDPatch), a random number of days between 0 and 511 will be added to this.
|-
| <code style="color:green">model_life</code>
| 0 ... 254 (years) or <code style="color:green">VEHICLE_NEVER_EXPIRES</code>
| no
|
Number of years a model is "supported" by the manufacturer, see [[#Engine life cycle|below]].
|-
| <code style="color:green">retire_early</code>
| -128 ... 127 (years)
| no
|
Retire the vehicle (make it unavailable in the purchase menu) this many years before reliability starts dropping, see [[#Engine life cycle|below]]. May be negative.
|-
| <code style="color:green">vehicle_life</code>
| 0 ... 255 (years)
| no
| Life length of an individual vehicle, before it is considered too old and in need of replacement.
|-
| <code style="color:green">reliability_decay</code>
| 0 ... 255
| no
| Default vehicles use 20. The higher the value the faster reliability decays, the more frequent service is needed. 0 means reliability never decreases if the vehicle is not too old
|-
| <code style="color:green">refittable_cargo_classes</code>
|
bit set of [[NML:Cargos#Cargo classes|cargo classes]]
| yes
| for example: <code style="color:darkgreen">bitmask(CC_BULK, CC_COVERED)</code>
|-
| <code style="color:green">non_refittable_cargo_classes</code>
|
bit set of [[NML:Cargos#Cargo classes|cargo classes]]
| yes
| for example: <code style="color:darkgreen">bitmask(CC_OVERSIZED, CC_SPECIAL)</code>
|-
| <code style="color:green">refittable_cargo_types</code>
| bit mask of entries into the cargo translation table
| yes
| As of NML 0.3, do not use this. Use cargo_[dis]allow_refit (see below) instead.
|-
| <code style="color:green">cargo_allow_refit</code>
| Array of cargo labels from the [[NML:Cargotable|cargotable]]
| Yes
| {{ottdp|1.2|no|ottdrev=r23291}} A list of cargo types to allow refitting to, irrespective of cargo classes. Example: <code style="color:darkgreen">[COAL, IORE]</code>
|-
| <code style="color:green">cargo_disallow_refit</code>
| Array of cargo labels from the [[NML:Cargotable|cargotable]]
| Yes
| {{ottdp|1.2|no|ottdrev=r23291}} A list of cargo types to disallow refitting to, irrespective of cargo classes. Example: <code style="color:darkgreen">[MAIL]</code>
|-
| <code style="color:green">loading_speed</code>
| 0 ... 255 (cargo units)
| yes
| Units of cargo loaded per time unit. Default vehicles use 5 for trains and road vehicles, 10 for ships and 20 for aircraft. This amount of cargo is loaded to or unloaded from the vehicle every 40 ticks for trains, every 20 ticks for road vehicles and aircraft and every 10 ticks for ships.
|-
| <code style="color:green">cost_factor</code>
| 0 ... 255
| Set to 0
| multiplier to the base purchase cost
|-
| <code style="color:green">running_cost_factor</code>
| 0 ... 255
| Set to 0
| multiplier to the base running costs
|-
| <code style="color:green">cargo_age_period</code>
| 0 ... 65535
| yes
|
{{ottd|1.2|r22713}} This property specifies after how many ticks cargo is aged. Default value is 185. 74 ticks is equal to 1 day.
|}

===Refittability===

To determine whether your vehicle can be refitted to a certain cargo, OpenTTD uses the following table

{| class="t"
! Cargo matches refittable_cargo_classes
! Cargo matches non_refittable_cargo_classes
! Cargo in cargo_allow_refit
! Cargo in cargo_disallow_refit
! Result
|-
| Yes
| No
| Doesn't matter
| No
| Refittable
|-
| No
| Doesn't matter
| No
| Doesn't matter
| Not refittable
|-
| Doesn't matter
| Doesn't matter
| Yes
| No
| Refittable
|-
| Doesn't matter
| Doesn't matter
| Doesn't matter
| Yes
| Not refittable
|}

For those that prefer boolean logic, the formula is as follows:

refittable = ((cargo classes in refittable_cargo_classes AND NOT cargo classes in non_refittable_cargo_classes) OR cargo in cargo_allow_refit) AND NOT (cargo in cargo_disallow_refit)

In general, you should use refittable_cargo_classes and non_refittable_cargo_classes to decide to which cargos your vehicle is refittable, and only then use cargo_allow_refit and cargo_disallow_refit to allow/disallow specific cargos.

===Engine life cycle===

The life cycle of a vehicle model consists of three phases, as outlined in the following table. When starting a new game, a random amount between 31 months and 17 years is added to the model life as well.

{| class="t"
! phase
! duration
! reliability
|-
| 1
| 7 to 38 months
| increases from 48-73% to 75-100%
|-
| 2
| <code style="color:darkgreen">model_life</code> - 8 years
| stays constant at peak, 75-100%
|-
| 3
| 10 to 20.5 years
| decreases from peak to 25-50%
|}

If <code style="color:darkgreen">model_life</code> is set to <code style="color:darkgreen">VEHICLE_NEVER_EXPIRES</code>, the engine remains in phase 2 forever.

Normally, the vehicle is removed from the purchase menu at the and of phase 3. However if you set the <code style="color:darkgreen">retire_early</code> property, it will be retired this many years before (or after, if the value is negative) the end of phase 2.

==Train properties==

{| class="t"
! property
! value range
! available for<br />articulated<br />vehicle
! comment
|-
| <code style="color:green">sprite_id</code>
| <code style="color:green">SPRITE_ID_NEW_TRAIN</code>
| yes
| Set this property to enable new graphics
|-
| <code style="color:green">speed</code>
| 0 ... 65000 (float, speed units)
| no
| Max speed for engines, speed limit for wagons
|-
| <code style="color:green">misc_flags</code>
| bitmask(TRAIN_FLAG_XXX, ...)
| FLIP should not be set, TILT and MU TO the same value as the 1st part
|
;TRAIN_FLAG_TILT
: enable the tilt bonus (20% speed in curves, if all vehicles in consist have it set)
;TRAIN_FLAG_2CC
:Enable use of the 2nd company colour
;TRAIN_FLAG_MU
:act as multiple unit (used for livery selection only)
;TRAIN_FLAG_FLIP
:Allow vehicle to be flipped (reversed) in depot
;TRAIN_FLAG_AUTOREFIT
:Allow autoreffitting. To enable autorefit, furthermore the [[#Vehicle callbacks|refit_cost]]-callback has to allow it, or else (if this callback is not implemented or fails) the <code style="color:green">refit_cost</code>-property (see below) must be set to 0.
;TRAIN_FLAG_NO_BREAKDOWN_SMOKE
:{{nml|0.3}} {{ottdp|1.3|no|ottdrev=r24124}} Disable breakdown smoke effect
|-
| <code style="color:green">refit_cost</code>
| 0 ... 255
| yes
| in 50% units of the purchase price cost base
|-
| <code style="color:green">callback_flags</code>
| bitmask(VEH_CBF_XXX, ...)
| yes
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| <code style="color:green">track_type</code>
| item from railtypetable
| must be the same as front
| Default railtype table: RAIL, MONO, MGLV. If you install a railtypetable yourself you'll always get the railtype you specified. If you want a vehicle to run on electric rail and you don't have a railtypetable, set <code style="color:green">track_type</code> to RAIL and make sure that you set <code style="color:green">engine_class</code> to <code style="color:green">ENGINE_CLASS_ELECTRIC</code>.
|-
| <code style="color:green">ai_special_flag</code>
| [<code style="color:green">AI_FLAG_PASSENGER</code> <nowiki>|</nowiki> <code style="color:green">AI_FLAG_CARGO</code>]
| no
|
;<code style="color:green">AI_FLAG_PASSENGER</code>
:Tell computer players that it's an engine that should only be used for passenger service.
|-
| <code style="color:green">power</code>
| 0 ... 65000 hp (float, power units)
| Set to 0
|
|-
| <code style="color:green">running_cost_base</code>
| RUNNING_COST_XXX
| Set to RUNNING_COST_NONE
|
;RUNNING_COST_STEAM
;RUNNING_COST_DIESEL
;RUNNING_COST_ELECTRIC
;RUNNING_COST_ROADVEH
;RUNNING_COST_NONE
:no running costs
|-
| <code style="color:green">dual_headed</code>
| [0 <nowiki>|</nowiki> 1]
| Set to 0 for all parts of an articulated vehicle
| 1 = dual_headed, otherwise normal engine
|-
| <code style="color:green">default_cargo_type</code>
| An identifier from the [[NML:Cargotable|cargo table]], or DEFAULT_CARGO_FIRST_REFITTABLE
| Yes
| If the vehicle is refittable to at least one cargo, but the chosen default cargo is not available or is set to DEFAULT_CARGO_FIRST_REFITTABLE, then the first refittable cargo is used. The first refittable is chosen according to the order in your [[NML:Cargotable|cargo table]]. If this property is set to a valid cargo but the vehicle cannot refit to any cargo type, then the vehicle will be able to carry only this cargo, but it cannot be refitted (like e.g. the default train wagons).
|-
| <code style="color:green">cargo_capacity</code>
| 0 .. 255
| yes
| By default, passenger capacity is 4x, and mail/goods capacity 2x larger than capacity for other cargoes. The capacity set here is used for the default (i.e. first refittable) cargo. Use the <code style="color:green">cargo_capacity</code> callback to avoid this effect.
|-
| <code style="color:green">weight</code>
| 0 .. 1279 ton (float, mass units)
| Set to 0
|
|-
| <code style="color:green">ai_engine_rank</code>
| 0 ... 255
| no
| TTDPatch only: Higher values make the engine for the TTDPatch AI more attractive
|-
| <code style="color:green">engine_class</code>
| ENGINE_CLASS_XXX
| no
|
Defines which livery colour settings apply to the vehicle. It also sets the corresponding sound effect of the engine, and if visual_effect_and_powered is not set, the visual effect as well.
;ENGINE_CLASS_STEAM
;ENGINE_CLASS_DIESEL
;ENGINE_CLASS_ELECTRIC
;ENGINE_CLASS_MONORAIL
;ENGINE_CLASS_MAGLEV
|-
| <code style="color:green">extra_power_per_wagon</code>
| 0 ... 65000 hp (float, power units)
| Set to 0
| Only wagons with a livery override for this engine will add power
|-
| <code style="color:green">tractive_effort_coefficient</code>
| 0 ... 1 (float)
| Set to 0
| Fraction of the vehicle weight that is available as tractive effort. Tractive effort (in kN) is calculated as (TE coefficient) * 10 * weight (in tons), with 10 being an approximation of the acceleration of gravity (9.81 m/s). A good value for rail tracks is 0.3.
|-
| <code style="color:green">air_drag_coefficient</code>
| 0 ... 1 (float)
| Set to 0
| Coefficient of the relative air drag, in arbitrary units. The default value is approximately (8 / max_speed), with max_speed in km/h, clamped to the range 0.004 .. 0.75.
|-
| <code style="color:green">length</code>
| 1 ... 8
| yes
| Length of the vehicle in arbitrary units. Use a value of 8 (equal to the predefined constant VEHICLE_LENGTH) for a full-length vehicle.
|-
| <code style="color:green">visual_effect_and_powered</code>
| <code style="color:green">visual_effect_and_powered</code> (VISUAL_EFFECT_XXX, offset, <code style="color:green">ENABLE_WAGON_POWER</code> or <code style="color:green">DISABLE_WAGON_POWER</code>)
| yes
|
There are two methods to set the visual effect of a vehicle:
* <code style="color:green">visual_effect_and_powered</code>: Easy method for simple effects.
* <code style="color:green">effect_spawn_model_and_powered</code> + callback <code style="color:green">create_effect</code>: {{ottdp|1.5|no|ottdrev=r26747}} Harder to use, but also more powerful.
For each vehicle you have to decide for the method. You cannot use them both for the same vehicle 'item'.

Set the type of visual effect for the vehicle and its positional offset with respect to the vehicle. An offset of 0 is default, negative values mean more to the front and positive values are backwards. Minimum offset is -8, maximum is 7.

;VISUAL_EFFECT_DEFAULT
:No effect, unless for the default vehicles
;VISUAL_EFFECT_STEAM
:Steam like from steam engine
;VISUAL_EFFECT_DIESEL
:Steam from internal combustion engine
;VISUAL_EFFECT_ELECTRIC
:Electric sparks
;VISUAL_EFFECT_DISABLE
:No effect
|-
| <code style="color:green">effect_spawn_model_and_powered</code>
| <code style="color:green">EFFECT_SPAWN_MODEL_XXX</code> or <code style="color:green">EFFECT_SPAWN_MODEL_XXX <nowiki>|</nowiki> ENABLE_WAGON_POWER</code>
| yes
|
There are two methods to set the visual effect of a vehicle:
* <code style="color:green">visual_effect_and_powered</code>: Easy method for simple effects.
* <code style="color:green">effect_spawn_model_and_powered</code> + callback <code style="color:green">create_effect</code>: {{ottdp|1.5|no|ottdrev=r26747}} Harder to use, but also more powerful.
For each vehicle you have to decide for the method. You cannot use them both for the same vehicle 'item'.

{{ottdp|1.5|no|ottdrev=r26747}} Set the spawning model of visual effects for the vehicle, that is when the vehicle emits visual effects.
The visual appearance itself is defined by the callback 'create_effect'.

;EFFECT_SPAWN_MODEL_NONE
: Do not spawn any effects.
;EFFECT_SPAWN_MODEL_STEAM
: Gradually less effects when approaching max speed.
;EFFECT_SPAWN_MODEL_DIESEL
: Effect proportional to acceleration, no effect when idling at top speed.
;EFFECT_SPAWN_MODEL_ELECTRIC
: Random effect, gradually less likely when approaching max speed.
|-
| <code style="color:green">extra_weight_per_wagon</code>
| 0 ... 255 ton (float, mass units)
| Set to 0
| Adds extra weight for powered wagons, see <code style="color:green">extra_power_per_wagon</code>
|-
| <span #id="bitmask_vehicle_info"></span><code style="color:green">bitmask_vehicle_info</code>
| 8-bit bitmask
| yes
|
Used for obtaining [[#bitmask consist info|<code style="color:green">bitmask_consist_info</code>]]
|}

==Road vehicle properties==

{| class="t"
! property
! value range
! available for<br />articulated<br />vehicle
! comment
|-
| sprite_id
| SPRITE_ID_NEW_ROADVEH
| yes
| Set this property to enable new graphics
|-
| speed
| 0 ... 514km/h (float, speed units)
| no
|
|-
| misc_flags
| bitmask(ROADVEH_FLAG_XXX, ...)
| partly; tram flag must the same
|
;ROADVEH_FLAG_TRAM
:The vehicle requires tram tracks to run on
;ROADVEH_FLAG_2CC
:Enable 2nd company colour
;ROADVEH_FLAG_AUTOREFIT
:Allow autorefitting. To enable autorefit, furthermore the [[#Vehicle callbacks|refit_cost]]-callback has to allow it, or else (if this callback is not implemented or fails) the <code style="color:green">refit_cost</code>-property (see below) must be set to 0.
;ROADVEH_FLAG_NO_BREAKDOWN_SMOKE
:{{nml|0.3}} {{ottdp|1.3|no|ottdrev=r24124}} Disable breakdown smoke effect
|-
| refit_cost
| 0 ... 255
| yes
| in 25% units of the purchase price cost base
|-
| callback_flags
| bitmask(VEH_CBF_XXX, ...)
| yes
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| running_cost_base
| RUNNING_COST_XXX
| set to RUNNING_COST_NONE
|
;RUNNING_COST_STEAM
;RUNNING_COST_DIESEL
;RUNNING_COST_ELECTRIC
;RUNNING_COST_ROADVEH
;RUNNING_COST_NONE
:no running costs
|-
| power
| 0 ... 2550hp (float, power units)
| Set to 0
|
|-
| weight
| 0 ... 63.75ton (float, mass units)
| Set to 0
|
|-
| tractive_effort_coefficient
| 0 ... 1 (float)
| Set to 0
| Fraction of the vehicle weight that is available as tractive effort. Tractive effort (in kN) is calculated as (TE coefficient) * 10 * weight (in tons), with 10 being an approximation of the acceleration of gravity (9.81 m/s). Default value is 0.3.
|-
| air_drag_coefficient
| 0 ... 1 (float)
| Set to 0
| Coefficient of the relative air drag, in arbitrary units. The default value is approximately (8 / max_speed), with max_speed in km/h, clamped to the range 0.004 .. 0.75.
|-
| <code style="color:green">default_cargo_type</code>
| An identifier from the [[NML:Cargotable|cargo table]], or DEFAULT_CARGO_FIRST_REFITTABLE
| Yes
| If the vehicle is refittable to at least one cargo, but the chosen default cargo is not available or is set to DEFAULT_CARGO_FIRST_REFITTABLE, then the first refittable cargo is used. The first refittable is chosen according to the order in your [[NML:Cargotable|cargo table]]. If this property is set to a valid cargo but the vehicle cannot refit to any cargo type, then the vehicle will be able to carry only this cargo, but it cannot be refitted (like e.g. the default train wagons).
|-
| cargo_capacity
| 0 ... 255
| yes
| By default, passenger capacity is 4x, and mail/goods capacity 2x larger than capacity for other cargoes. The capacity set here is used for the default (i.e. first refittable) cargo. Use the <code style="color:green">cargo_capacity</code> callback to avoid this effect.
|-
| sound_effect
| SOUND_XXX
| no
|
See available [[NML:List of sound effects|sound effects]].
|-
| visual_effect
| visual_effect( VISUAL_EFFECT_XXX, offset)
| yes
|
There are two methods to set the visual effect of a vehicle:
* <code style="color:green">visual_effect</code>: Easy method for simple effects.
* <code style="color:green">effect_spawn_model</code> + callback <code style="color:green">create_effect</code>: {{ottdp|1.5|no|ottdrev=r26747}} Harder to use, but also more powerful.
For each vehicle you have to decide for the method. You cannot use them both for the same vehicle 'item'.

Set the type of visual effect for the vehicle and its positional offset with respect to the vehicle. An offset of 0 is default, negative values mean more to the front and positive values are backwards. Minimum offset is -8, maximum is 7.

;VISUAL_EFFECT_DEFAULT
:No effect, unless for the default vehicles
;VISUAL_EFFECT_STEAM
:Steam like from steam engine
;VISUAL_EFFECT_DIESEL
:Steam from internal combustion engine
;VISUAL_EFFECT_ELECTRIC
:Electric sparks
;VISUAL_EFFECT_DISABLE
:No effect
|-
| <code style="color:green">effect_spawn_model</code>
| <code style="color:green">EFFECT_SPAWN_MODEL_XXX</code>
| yes
|
There are two methods to set the visual effect of a vehicle:
* <code style="color:green">visual_effect</code>: Easy method for simple effects.
* <code style="color:green">effect_spawn_model</code> + callback <code style="color:green">create_effect</code>: {{ottdp|1.5|no|ottdrev=r26747}} Harder to use, but also more powerful.
For each vehicle you have to decide for the method. You cannot use them both for the same vehicle 'item'.

{{ottdp|1.5|no|ottdrev=r26747}} Set the spawning model of visual effects for the vehicle, that is when the vehicle emits visual effects.
The visual appearance itself is defined by the callback 'create_effect'.

;EFFECT_SPAWN_MODEL_NONE
: Do not spawn any effects.
;EFFECT_SPAWN_MODEL_STEAM
: Gradually less effects when approaching max speed.
;EFFECT_SPAWN_MODEL_DIESEL
: Effect proportional to acceleration, no effect when idling at top speed.
;EFFECT_SPAWN_MODEL_ELECTRIC
: Random effect, gradually less likely when approaching max speed.
|-
| length
| 1 ... 8
| yes
| Length of the vehicle in arbitrary units. Use a value of 8 (equal to the predefined constant VEHICLE_LENGTH) for a full-length vehicle.
|}

==Ship properties==

{| class="t"
! property
! value range
! comment
|-
| sprite_id
| SPRITE_ID_NEW_SHIP
| Set this property to enable new graphics
|-
| speed
| 0 ... 127 km/h (float, speed units)
|
|-
| misc_flags
| bitmask(SHIP_FLAG_XXX)
| Bitmask with to possible flags, set to 0 to disable all.

;SHIP_FLAG_2CC
:Enable use of the 2nd company colour
;SHIP_FLAG_AUTOREFIT
:llow autorefitting. To enable autorefit, furthermore the [[#Vehicle callbacks|refit_cost]]-callback has to allow it, or else (if this callback is not implemented or fails) the <code style="color:green">refit_cost</code>-property (see below) must be set to 0.
;SHIP_FLAG_NO_BREAKDOWN_SMOKE
:{{nml|0.3}} {{ottdp|1.3|no|ottdrev=r24124}} Disable breakdown smoke effect
|-
| refit_cost
| 0 ... 255
| in 1/32 of the default refit cost base
|-
| callback_flags
| bitmask(VEH_CBF_XXX, ...)
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| is_refittable
| [0 <nowiki>|</nowiki> 1]
| 0=false, 1=true. Note: if you do not set this property to 1, then refittable_cargo_classes / non_refittable_cargo_classes have no effect.
|-
| <code style="color:green">default_cargo_type</code>
| An identifier from the [[NML:Cargotable|cargo table]], or DEFAULT_CARGO_FIRST_REFITTABLE
| If the vehicle is refittable to at least one cargo, but the chosen default cargo is not available or is set to DEFAULT_CARGO_FIRST_REFITTABLE, then the first refittable cargo is used. The first refittable is chosen according to the order in your [[NML:Cargotable|cargo table]]. If this property is set to a valid cargo but the vehicle cannot refit to any cargo type, then the vehicle will be able to carry only this cargo, but it cannot be refitted (like e.g. the default train wagons).
|-
| cargo_capacity
| 0 ... 255
| For ships (unlike other vehicle types) the capacity set here is not affected by the cargo type.
|-
| sound_effect
| SOUND_XXX
|
See available [[NML:List of sound effects|sound effects]].
|-
| ocean_speed_fraction
| 0 ... 1 (float)
|
{{ottd|1.2|r22639}} fraction of base speed on ocean tiles (default: 1)
|-
| canal_speed_fraction
| 0 ... 1 (float)
|
{{ottd|1.2|r22639}} fraction of base speed on canal tiles (default: 1)
|-
| visual_effect
| visual_effect(VISUAL_EFFECT_XXX, offset)
|
There are two methods to set the visual effect of a vehicle:
* <code style="color:green">visual_effect</code>: Easy method for simple effects.
* <code style="color:green">effect_spawn_model</code> + callback <code style="color:green">create_effect</code>: {{ottdp|1.5|no|ottdrev=r26747}} Harder to use, but also more powerful.
For each vehicle you have to decide for the method. You cannot use them both for the same vehicle 'item'.

XXX=[DEFAULT <nowiki>|</nowiki> STEAM <nowiki>|</nowiki> DIESEL <nowiki>|</nowiki> ELECTRIC <nowiki>|</nowiki> DISABLE], it is the type of the visual effect you want for this ship. Default means no effect. Offset is the position of the effect. 0 is default, negative values mean more to the front and positive values are backwards. Minimum offset is -8, maximum is 7.
|-
| <code style="color:green">effect_spawn_model</code>
| <code style="color:green">EFFECT_SPAWN_MODEL_XXX</code>
|
There are two methods to set the visual effect of a vehicle:
* <code style="color:green">visual_effect</code>: Easy method for simple effects.
* <code style="color:green">effect_spawn_model</code> + callback <code style="color:green">create_effect</code>: {{ottdp|1.5|no|ottdrev=r26747}} Harder to use, but also more powerful.
For each vehicle you have to decide for the method. You cannot use them both for the same vehicle 'item'.

{{ottdp|1.5|no|ottdrev=r26747}} Set the spawning model of visual effects for the vehicle, that is when the vehicle emits visual effects.
The visual appearance itself is defined by the callback 'create_effect'.

;EFFECT_SPAWN_MODEL_NONE
: Do not spawn any effects.
;EFFECT_SPAWN_MODEL_STEAM
: Gradually less effects when approaching max speed.
;EFFECT_SPAWN_MODEL_DIESEL
: Effect proportional to acceleration, no effect when idling at top speed.
;EFFECT_SPAWN_MODEL_ELECTRIC
: Random effect, gradually less likely when approaching max speed.
|}

==Aircraft properties==

{| class="t"
! property
! value range
! comment
|-
| sprite_id
| SPRITE_ID_NEW_AIRCRAFT
| Set this property to enable new graphics
|-
| speed
| 0 .. 3280 km/h (float, speed units)
|
|-
| range
| 0 .. 2894
| {{nml|0.3}} {{ottdp|1.2|no|ottdrev=r23504}} Maximum (euclidean) distance the aircraft can cover between two airports. Set to 0 for unlimited range.
|-
| misc_flags
| bitmask(AIRCRAFT_FLAG_2CC, AIRCRAFT_FLAG_AUTOREFIT)
| Bitmask with to possible flags, set to 0 to disable all.

;AIRCRAFT_FLAG_2CC
:Enable 2nd company colour
;AIRCRAFT_FLAG_AUTOREFIT
:Allow autorefitting. To enable autorefit, furthermore the [[#Vehicle callbacks|refit_cost]]-callback has to allow it, or else (if this callback is not implemented or fails) the <code style="color:green">refit_cost</code>-property (see below) must be set to 0.
;AIRCRAFT_FLAG_NO_BREAKDOWN_SMOKE
:{{nml|0.3}} {{ottdp|1.3|no|ottdrev=r24124}} Disable breakdown smoke effect
|-
| refit_cost
| 0 ... 255
| in 1/32 of default refit cost base
|-
| callback_flags
| bitmask(VEH_CBF_XXX, ...)
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| aircraft_type
| AIRCRAFT_TYPE_XXX
|
;AIRCRAFT_TYPE_HELICOPTER
:Can land on helipad
;AIRCRAFT_TYPE_SMALL
:Can land on all airports with runway
;AIRCRAFT_TYPE_LARGE
:Can land on all airports with runway. But have a high crash chance on small airports
|-
| acceleration
| {{ottd|1.3.1}} 0 ... 255 <br/> {{ottd|<1.3.1}} 0 ... 19
| {{ottd|1.3.1}} Default aircraft use values in the range 18 to 50 (= 6.75 to 18.75 mph/tick = 499.5 to 1387.5 mph/day), which is generally considered quite fast.<br/>
{{ottd|<1.3.1}} In older OpenTTD, aircraft provided by NewGRF accelerate 166% faster than intended.
|-
| passenger_capacity
| 0 ... 65536
| Capacity for the passenger compartment. See also the notes at <code style="color:darkgreen">mail_capacity</code> below.
|-
| mail_capacity
| 0 ... 255
| Capacity for the mail compartment, if refitted to a cargo in the CC_PASSENGERS class. When refitted to other cargoes, this capacity is added to the passenger capacity to determine the base capacity. The actual capacity is set to this base capacity divided by 1 for mail, 2 for goods and 4 for all other cargoes. To override this effect, use the <code style="color:darkgreen">passenger_capacity</code> and <code style="color:darkgreen">mail_capacity</code> callbacks.
|-
| sound_effect
| SOUND_XXX
|
See available [[NML:List of sound effects|sound effects]].
|}

==Vehicle variables==

Below an overview of all vehicle-specific variables. Note that in the purchase list, the vehicle is not built yet and as such many variables are not available. All general variables are available, refer to the table for info on vehicle-specific variables. Trying to access a non-available variable invokes undefined behaviour. Please note that while all variables are available for all vehicles types, some of them only make sense for one or more vehicle types. For example checking current_railtype for a non-rail vehicle doesn't make sense at all.

===Variables without parameter===

{| class="t"
! name
! value range
! available in<br />purchase list?
! comment
|-
| position_in_consist
| 0 ... 255
| No
| The position of the current vehicle-part from the start of the vehicle. The engine will get value 0, the first wagon (or second engine) gets value 1, etc.
|-
| position_in_consist_from_end
| 0 ... 255
| No
| Same as position_in_consist but counted from the end. The last wagon will get value 0.
|-
| num_vehs_in_consist
| 1 ... 256
| No
| The total number of vehicles-parts in this vehicle. For aircraft this will include the shadow and the rotor.
|-
| position_in_vehid_chain
| 0 ... 255
| No
| See position_in_consist, but not of the complete vehicle but only all consecutive parts with the same id.
|-
| position_in_vehid_chain_from_end
| 0 ... 255
| No
| See position_in_consist_from_end, but not of the complete vehicle but only all consecutive parts with the same id.
|-
| num_vehs_in_vehid_chain
| 1 ... 256
| No
| See num_vehs_in_consist, but not of the complete vehicle but only all consecutive parts with the same id.
|-
| position_in_articulated_veh
| 0 ... 255
| No
| {{nml|0.3}} {{ottdp|1.4|no|ottdrev=r26157}} The position of the current articulated vehicle from the start of the vehicle. The first will get value 0, the second one gets value 1, etc.
|-
| position_in_articulated_veh_from_end
| 0 ... 255
| No
| {{nml|0.3}} {{ottdp|1.4|no|ottdrev=r26157}} The position of the current articulated vehicle from the end of the vehicle. The last will get value 0, the second last one gets value 1, etc.
|-
| cargo_classes_in_consist
| Bitmask of CC_XXX
| No
|
[[NML:Cargos#Cargo classes|cargo classes]]
|-
| most_common_refit
|
[[NML:Cargos#Cargo properties|cargo class]]
| No
| cargo class most often refit to
|-
| bitmask_consist_info
| Bitmask 8 bit
| No
|
Binary OR of the values of [[#bitmask vehicle info|bitmask_vehicle_info]] of all vehicles (engines, wagons) in the consist. Only available for rail vehicles.
|-
| company_num
| 0 ... 14
| Yes
| company number of the vehicle owner. TTDPatch only supports up to 8 companies (0 ... 7)
|-
| company_type
| PLAYERTYPE_XX
| Yes
|
;PLAYERTYPE_HUMAN
:human player
;PLAYERTYPE_AI
:AI player
;PLAYERTYPE_HUMAN_IN_AI
:human managing AI company
;PLAYERTYPE_AI_IN_HUMAN
:AI managing human company

OpenTTD only uses PLAYERTYPE_HUMAN and PLAYERTYPE_AI. If you cheat yourself to be part of an AI company OpenTTD will still report PLAYERTYPE_AI for the company with yourself and the AI and it'll report PLAYERTYPE_HUMAN for the now uncontrolled company.
|-
| company_colour1
| COLOUR_XXX
| Yes
|
Refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for possible values.
|-
| company_colour2
| COLOUR_XXX
| Yes
|
Same as company_colour1, if no 2nd company colour is chosen. Refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for possible values.
|-
| aircraft_height
| 0 ... 255
| No
| Height difference between the aircraft and its shadow. 8 Units are equivalent to one height level on the map.
|-
| airport_type
| AIRPORTTYPE_XX
| No
|
;AIRPORTTYPE_SMALL
;AIRPORTTYPE_LARGE
;AIRPORTTYPE_HELIPORT
;AIRPORTTYPE_OILRIG
|-
| curv_info_prev_cur
| -2 ... 2
| No
| Difference in direction between the previous (towards engine) vehicle and this vehicle. Curvature to the right is positive. 1 unit is 45 degrees.
|-
| curv_info_cur_next
| -2 ... 2
| No
| Difference in direction between this vehicle and the next (towards rear end) vehicle. Curvature to the right is positive. 1 unit is 45 degrees.
|-
| curv_info_prev_next
| -4 ... 4
| No
| Difference in direction between the previous (towards engine) and next (towards rear end) vehicle. Curvature to the right is positive. 1 unit is 45 degrees. Equal to <code style="color:darkgreen">curve_invo_prev_cur + curv_info_cur_next</code>.
|-
| curv_info
| vehicle_curv_info(''prev_cur'', ''cur_next'')''''
| No
|
Returns a magic number that represents the curvature state of the prev-cur-next vehicle triplet. Do not try to make sense of this magic number, use the [[NML:Builtin functions|builtin function]] <code style="color:darkgreen">vehicle_curv_info()</code> instead to make comparisons. <code style="color:darkgreen">curv_info == vehicle_curv_info(a, b)</code> is equivalent to <code style="color:darkgreen">(curv_info_prev_cur == a) && (curv_info_cur_next == b)</code>, however the former can easily be used in a switch-block.
|-
| motion_counter
| 0 ... 15
| Yes, always 0
| Is increased every time the vehicle moves a single step on the map. Useful for animations.
|-
| cargo_type_in_veh
| entry in cargo translation table
| Yes, for the default cargo
| 0xFF if not present in the table
|-
| cargo_unit_weight
| weight per unit in 1/16t
| Yes, for the default cargo
|
|-
| cargo_classes
| Bitmask of [[NML:Cargos#Cargo properties|cargo class]]
| Yes, for the default cargo
| class of the currently transported cargo
|-
| vehicle_is_available
| [0 <nowiki>|</nowiki> 1]
| Yes
| Value is 1 if the vehicle is available on the open market
|-
| vehicle_is_testing
| [0 <nowiki>|</nowiki> 1]
| Yes
| Value is 1 if the vehicle is currently being tested
|-
| vehicle_is_offered
| [0 <nowiki>|</nowiki> 1]
| Yes
| Value is 1 if the vehicle is currently being offered for exclusive preview
|-
| build_year
| 0 ... 5000000
| Yes
| 0-based year when the vehicle was built, current year if the vehicle is not built yet
|-
| direction
| DIRECTION_XX
| No
|
See [[NML:List of direction constants|here]] for an overview of possible values and their meaning.
|-
| cargo_capacity
| 0 ... 65535
| No
| Cargo capacity (number of units) of the vehicle
|-
| cargo_count
| 0 ... 65535
| No
| Number of cargo units of cargo in the vehicle
|-
| cargo_subtype
| 0 ... 255
| Yes, always 0
| Cargo subtype, used to provide more than one refit option for the same cargo type. See also the <code style="color:darkgreen">cargo_subtype_text</code> callback.
|-
| vehicle_is_powered
| [0 <nowiki>|</nowiki> 1]
| No
| Vehicle provides power and is on the correct track type
|-
| vehicle_is_not_powered
| [0 <nowiki>|</nowiki> 1]
| No
| Vehicle is either on a wrong track type or it doesn't provide power at all
|-
| vehicle_is_potentially_powered
| [0 <nowiki>|</nowiki> 1]
| No
| Vehicle provides power, if it is on a suitable track type
|-
| vehicle_is_reversed
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle has reversed an odd number of times
|-
| built_during_preview
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle was built during the exclusive preview stage
|-
| current_railtype
| No
| Entry from railtype translation table or 0xFF
| Don't use this variable unless you've defined a railtype translation table. If the train is running on a railtype that is not listed in your railtype translation table this variable will contain 0xFF. Available since OpenTTD r20164.
|-
| waiting_triggers
|
| No
|
Random triggers waiting to be matched. (see [[NML:Random switch|Random switch]])
|-
| random_bits
| 0 ... 255
| No
|
Random data that can be used to randomize certain descisions. (see [[NML:Random switch|Random switch]])
|-
| grfid
| 0 ... 0xFFFFFFFF
| No
|
GRFID that defined the [[NML:Graphics|graphics]]-block for this vehicle. To compare this with other grfids, use the [[NML:Builtin functions|builtin function]] <code style="color:darkgreen">str2number()</code> to convert the other GRFID to a number as well.
|-
| vehicle_type_id
| 0 ... 65535 or a name defined in item block
| No
| GRF-local ID of the vehicle, equal to the item ID. Note that vehicles from other NewGRFs may have the same ID, so you'll generally have to check the <code style="color:darkgreen">grfid</code> as well.
|-
| vehicle_is_hidden
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle is hidden in a depot or tunnel.
|-
| vehicle_is_stopped
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle is stopped, or if it is braking for a stop (trains only).
|-
| vehicle_is_crashed
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle has crashed.
|-
| vehicle_is_broken
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle is broken down.
|-
| date_of_last_service
| date(year, month, day)
| No
|
|-
| breakdowns_since_last_service
| 0 ... 255
| No
| Number of breakdowns since the last service
|-
| reliability
| 0 ... 100
| No
| Reliability (percentage)
|-
| age_in_days
| 0 ... 65535
| No
| Vehicle age in days.
|-
| max_age_in_days
| 0 ... 65535
| No
| Maximum vehicle age in days.
|-
| current_speed
| (speed units)
| No
| The current speed of the vehicle in m/s
|-
| max_speed
| (speed units)
| No
| The maximum speed of the vehicle in m/s
|-
| current_max_speed
| (speed units)
| No
| {{nml|0.3}} {{ottdp|1.3|no|ottdrev=r24246}} Current maximum speed of the vehicle in m/s. This includes e.g. track or timetable limits. Only valid for front vehicle.
|-
| vehicle_is_in_depot
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle is inside a depot
|-
| vehicle_is_unloading
| [0 <nowiki>|</nowiki> 1]
| No
| {{ottdp|1.5|2.5|ottdrev=r26430}} Value is 1 if the vehicle is unloading at a station and has not yet started loading new cargo.
|}

===Variables that require an argument===

{| class="t"
! name
! Argument
! value range
! available in<br />purchase list?
! comment
|-
| count_veh_id
| The vehicle ID to look for.
| 0..255
| No
| The number of vehicles in the current consist that have the given ID.
|-
| other_veh_curv_info
| Offset in the chain from the current vehicle.<ref name="offset">Argument range is -128..127. Positive values are interpreted as towards the end, negative values as towards the front. If the offset is outside the vehicle chain, the result value will be 0.</ref>
| -4..4
| No
| Difference in direction between the other vehicle and this vehicle. Curvature to the right is positive. 1 unit is 45 degrees.
|-
| other_veh_is_hidden
| Offset in the chain from the current vehicle.<ref name="offset"/>
| [0 <nowiki>|</nowiki> 1]
| No
| 1 the other vehicle is hidden in a depot or tunnel, 0 otherwise
|-
| other_veh_x_offset
| Offset in the chain from the current vehicle.<ref name="offset"/>
| -128..127
| No
| Signed difference in X-position (top-right to bottom-left) between the other vehicle and this vehicle.
|-
| other_veh_y_offset
| Offset in the chain from the current vehicle.<ref name="offset"/>
| -128..127
| No
| Signed difference in Y-position (top-left to bottom-right) between the other vehicle and this vehicle.
|-
| other_veh_z_offset
| Offset in the chain from the current vehicle.<ref name="offset"/>
| -128..127
| No
| Signed difference in Z-position (upwards) between the other vehicle and this vehicle.
|}
<references/>

==Vehicle callbacks==
The following table contains a list of available vehicle callbacks. Additionally, it's possible to provide cargo-specific graphics, using the identifier from the [[NML:Cargotable|cargo table]] as callback name. These callbacks will be used if the vehicle is refitted to the corresponding cargo type. If no cargo-specific graphics match the cargo that the vehicle is carrying, the <code style="color:darkgreen">default</code> callback is used instead. Cargo-specific graphics callbacks are never called from the purchase menu, refer to the <code style="color:darkgreen">purchase</code> callback below instead.

Note that the above affects '''graphics only''', other callbacks are unaffected.

{| class="t"
! Name
! Available for
! In purchase menu?
! value range
! comment
|-
| default
| All
| Yes, unless <code style="color:darkgreen">purchase</code> is set separately
| Sprite group
| 'Normal' vehicle graphics, if no cargo-specific graphics apply. See also the section on [[#Sprites in GUI|GUI sprites]].
|-
| purchase
| All
| Yes, only
| Sprite group
| Graphics to show in the buy menu (only the horizontal view is needed, except for dual-headed trains. With the <code>dual_headed</code> property set, special rules for the purchase menu sprite apply: two sprites are drawn (for front and back) as if the vehicle is normally constructed. If you supply one purchase menu sprite, it will be used for both vehicle parts in the purchase menu. Provide a set of 8 sprites, and the 7th resp. 3rd sprite will be drawn; provide a set of 8 blank sprites except the 7th if you want to fully control a single purchase menu sprite for a dual-headed engine. ) See also the section on [[#Sprites in GUI|GUI sprites]].
|-
| rotor
| Aircraft (helicopters)
| No
| Sprite group
| Graphics for the helicopter rotor (4 sprites; 1 stopped and 3 moving)
|-
| random_trigger
| All
| No
| N/A
| See [[NML:Random switch|random switch]] for more information.
|-
| cargo_subtype_text
| All
| No
| String, or CB_RESULT_NO_TEXT
| With this callback, you can display extra text after the cargo in the vehicle information window. This callback is called during refitting, with succesively increased values of the <code style="color:darkgreen">cargo_subtype</code> variable, until the callback returns CB_RESULT_NO_TEXT. All returned strings are then displayed as refit options. The chosen refit option is saved in the <code style="color:darkgreen">cargo_subtype</code> variable, so it can be used later for other things. In the HEQS grf for example, this mechanism is used to let the user choose between different capacities of the same vehicle.
|-
| additional_text
| All
| Yes, only
| String
| Additional text to show in the purchase list.
|-
| colour_mapping
| All
| Yes, unless <code style="color:darkgreen">purchase_colour_mapping</code> is set separately
| Recolour sprite number
|
With this callback, you can use a different recolour sprite instead of the standard 1cc / 2cc company colour remappings. See [[NML:List of default colour translation palettes|here]] for a list of default palettes. See the [[NML:Builtin functions|builtin function]] <code style="color:darkgreen">reserve_sprites()</code> for info on how to allocate your own sprite. For performance, the result is cached and only updated if the <code style="color:darkgreen"> every_32_days</code> callback requires so. Add CB_RESULT_COLOUR_MAPPING_ADD_CC to the result to add the company colour to the sprites, this requires 16 (1cc) or 256 (2cc) sprites in total.
|-
| start_stop
| All
| No
| String or CB_RESULT_NO_TEXT
| Called when starting or stopping a vehicle. Mainly useful to prevent vehicles from leaving the depot unless a certain condition is met. Return CB_RESULT_NO_TEXT to allow or a string (containing an error message) to disallow starting/stopping.
|-
| every_32_days
| All
| No
| bitmask(CB_RESULT_32_DAYS_XXX, ...)
| Called every 32 days. Set CB_RESULT_32_DAYS_TRIGGER in the bitmask to trigger TRIGGER_VEHICLE_32_CALLBACK. Set CB_RESULT_32_DAYS_COLOUR_MAPPING in the bitmask to update the colour mapping by re-running the <code style="color:darkgreen">colour_mapping</code> callback.
|-
| sound_effect
| All
| No
| SOUND_XXX, sound("sound.wav"), import_sound(grfid, number) or CB_RESULT_NO_SOUND
|
Called to play various vehicle sounds. <code style="color:darkgreen">extra_callback_info1</code> contains the sound event, see the [[#Sound events|table]] below. Return SOUND_XXX (see [[NML:List_of_sound_effects|here]]) to return a default sound. <code style="color:darkgreen">sound("soundfile")</code> imports a sound from a .wav file. <code style="color:darkgreen">import_sound(grfid, number)</code> imports a sound from another grf. A failed (or not implemented) callback will cause the default sound to be played. Return CB_RESULT_NO_SOUND to play no sound at all.
|-
| articulated_part
| Trains, Road Vehicles
| Yes (no separate callback)
| Vehicle ID, or CB_RESULT_NO_MORE_ARTICULATED_PARTS
| With this callback, you can add articulated parts (e.g. tenders) to your vehicle. Called repeatedly, until CB_RESULT_NO_MORE_ARTICULATED_PARTS is returned. After each call, the returned vehicleID is added to your vehicle. <code style="color:darkgreen">extra_callback_info1</code> contains 1 during the first call, 2 during the second, etc. Note that callback may be called from the purchase list, using vehicle variables is not possible. Or CB_RESULT_REVERSED_VEHICLE to the returned vehicle ID to display the vehicle backwards.

For NML 0.2 and lower the vehicle ID of the articulated part must be in the range 0 .. 127.
|-
| can_attach_wagon
| Trains
| No
| String or CB_RESULT_ATTACH_XXX
| Called when a wagon is being attached, to allow or disallow attaching. If a wagon is inserted in the middle, all wagons are removed and attached one-by-one in the new order. This callback has to be defined at the engine. The scopes behave different than usual though:
* <code style="color:darkgreen">SELF</code> refers to the wagon being attached. (despite the callback being defined at the engine)
* <code style="color:darkgreen">PARENT</code> refers to the consist of the engine up to the wagon before <code style="color:darkgreen">SELF</code>, i.e. not (yet) including the wagon being attached.
Return a string to disallow with the string as error message. Return CB_RESULT_ATTACH_DISALLOW to disallow with standard message ("incompatible railtypes"), CB_RESULT_ATTACH_ALLOW to allow or CB_RESULT_ATTACH_ALLOW_IF_RAILTYPES to allow if the railtypes match (default).
|-
| refit_cost
| {{ottdp|1.2|no|ottdrev=r23089}} All
| Yes
| -8192 .. 8191 as refit cost. Add <code style="color:darkgreen">CB_RESULT_AUTOREFIT</code> if you want to allow autorefit.
| When returning a negative value, encode the cost as (cost & <code style="color:darkgreen">CB_RESULT_REFIT_COST_MASK</code>) before (possibly) adding <code style="color:darkgreen">CB_RESULT_AUTOREFIT</code>. To allow autorefitting, the corresponding bit in the <code style="color:darkgreen">misc_flags</code> must be set as well. Variable <code style="color:darkgreen">extra_callback_info1</code> contains information about the target cargo type in the format 0xccccsstt, with tt being the new cargo type, ss the new cargo subtype (see <code style="color:darkgreen">cargo_subtype_text</code>-callback) and cccc a bitmask of the [[NML:Cargos#Cargo_classes|cargo classes]] of the target cargo type. Note that this callback may also be called when the vehicle does not exist yet, so the available variables are limited.
|-
| create_effect
| {{ottdp|1.5|no|ottdrev=r26747}} Trains, Road Vehicles, Ships
| No
| 0 .. 3 for number of effects. Optionally add <code style="color:darkgreen">CB_RESULT_CREATE_EFFECT_CENTER</code> and/or <code style="color:darkgreen">CB_RESULT_CREATE_EFFECT_NO_ROTATION</code>
| Called when a effect spawning model is defined via <code style="color:darkgreen">effect_spawn_model</code> resp. <code style="color:darkgreen">effect_spawn_model_and_powered</code>.

The result specifies how many effects shall be created.
The position and appearance of the individual effects is returned via registers 0x100 to 0x103:
<pre style="color:blue">
switch (FEAT_XXX, SELF, switch_name, [
STORE_TEMP(create_effect(EFFECT_SPRITE_XXX, 8, -3, 10), 0x100), // first effect,
STORE_TEMP(create_effect(EFFECT_SPRITE_YYY, 8, 3, 10), 0x101) // second effect, ...
]) {
return 2; // number of effects
}
</pre>
The register values are created using the <code style="color:darkgreen">create_effect(''effect_sprite'', ''l_x_offset'', ''t_y_offset'', ''z_offset'')</code> function:
* ''effect_sprite'': Sprite for the effect. One of <code style="color:darkgreen">EFFECT_SPRITE_</code>[<code style="color:darkgreen">NONE</code>|<code style="color:darkgreen">STEAM</code>|<code style="color:darkgreen">DIESEL</code>|<code style="color:darkgreen">ELECTRIC</code>|<code style="color:darkgreen">AIRCRAFT_BREAKDOWN_SMOKE</code>].
* ''l_x_offset'': Longitudinal or X position of the effect, depending on callback result <code style="color:darkgreen">CB_RESULT_CREATE_EFFECT_NO_ROTATION</code>.
* ''t_y_offset'': Transversal or Y position of the effect, depending on callback result <code style="color:darkgreen">CB_RESULT_CREATE_EFFECT_NO_ROTATION</code>.
* ''z_offset'': Z position of the effect.

Additional to the number of effects, the callback result may specify these flags:
;<code style="color:darkgreen">CB_RESULT_CREATE_EFFECT_CENTER</code>
:(Train and road vehicle only) If set, position effect relative to vehicle center instead of relative to vehicle sprite. (behaves the same for vehicles with length 8/8)
;<code style="color:darkgreen">CB_RESULT_CREATE_EFFECT_NO_ROTATION</code>
*If not set, the parameters to <code style="color:darkgreen">effect_sprite</code> describe longitudinal/transversal positions, which are rotate wrt. vehicle orientation.
*If set, the parameters to <code style="color:darkgreen">effect_sprite</code> describe X and Y positions, which are not automatically rotated.
|}

The following callbacks all have an equivalent property. The property description applies here also, except where otherwise noted.

{| class="t"
! Name
! Available for
! In purchase menu?
! comment
|-
| loading_speed
| All
| No
|
|-
| speed
| All
| Yes, unless <code style="color:darkgreen">purchase_speed</code> is set separately
| Units are not (yet) available
|-
| cost_factor
| All
| Yes, only
|
|-
| running_cost_factor
| All
| Yes, unless <code style="color:darkgreen">purchase_running_cost_factor</code> is set separately
|
|-
| cargo_age_period
| All
| No
|
|-
| cargo_capacity
| All except aircraft
| Yes, unless <code style="color:darkgreen">purchase_cargo_capacity</code> is set separately
|
|-
| passenger_capacity
| Aircraft
| Yes, unless <code style="color:darkgreen">purchase_passenger_capacity</code> is set separately
|
|-
| mail_capacity
| Aircraft
| Yes, unless <code style="color:darkgreen">purchase_mail_capacity</code> is set separately
|
|-
| range
| Aircraft
| Yes, unless <code style="color:darkgreen">purchase_range</code> is set separately
|
|-
| visual_effect_and_powered
| Trains
| No
|
|-
| visual_effect
| Road Vehicles, Ships
| No
|
|-
| effect_spawn_model_and_powered
| Trains
| No
|
|-
| effect_spawn_model
| Road Vehicles, Ships
| No
|
|-
| power
| Trains, Road Vehicles
| Yes, unless <code style="color:darkgreen">purchase_power</code> is set separately
| Units are not (yet) available
|-
| weight
| Trains, Road Vehicles
| Yes, unless <code style="color:darkgreen">purchase_weight</code> is set separately
| Units are not (yet) available
|-
| length
| Trains, Road vehicles
| No
|
|-
| tractive_effort_coefficient
| Trains, Road Vehicles
| Yes, unless <code style="color:darkgreen">purchase_tractive_effort_coefficient</code> is set separately
| Value range is 0 .. 255 instead of 0 .. 1.
|-
| bitmask_vehicle_info
| Trains
| No
|
|}

===Sprites in GUI===
{{ottdp|1.2|no|ottdrev=r23080}} Since OpenTTD r23080 you can use variable <code style="color:darkgreen">extra_callback_info1</code> to display different sprites in the GUI and on the map. Currently these cases are available:
{| |-
! Lowest byte of extra_callback_info1 !! Meaning
|-
| 0x00 || Vehicle is drawn in a viewport, i.e. on the map.
|-
| 0x01..0x0F || reserved
|-
| 0x10 || Vehicle is drawn in the depot GUI. <ref>OpenTTD also uses this value with the purchase-list chain (cargotype FF) to determine the gridsize in ship and aircraft depots.</ref>
|-
| 0x11 || Vehicle is drawn in the vehicle details GUI. (This includes the refit GUI.)
|-
| 0x12 || Vehicle is drawn in the vehicle list.
|-
| 0x13..0x1F || reserved for other future GUIs.
|-
| 0x20 || Vehicle is drawn in the purchase list. (This includes the autoreplace GUI.)
|-
| 0x21 || Vehicle is drawn in the exclusive preview GUI or in the advertisement news.
|-
| 0x22..0x2F || reserved for other future GUIs with non-purchased vehicles.
|-
| 0x30..0xFF || reserved
|}
<references/>
The other bytes of variable <code style="color:darkgreen">extra_callback_info1</code> are reserved, and must be masked.
The cases 0x20..0x2F are called using the <code style="color:darkgreen">purchase</code>-callback, the other cases are called for the <code style="color:darkgreen">default</code>- or cargo-specific callbacks. Exception is the the special depot-gridsize call, which uses the <code style="color:darkgreen">purchase</code>-callback.

===Sound events===

{| class="t"
! Event
! Description
|-
| SOUND_EVENT_START
| Vehicle leaves station or depot, plane takes off
|-
| SOUND_EVENT_TUNNEL
| Vehicle enters tunnel
|-
| SOUND_EVENT_BREAKDOWN
| Vehicle breaks down (not for planes)
|-
| SOUND_EVENT_RUNNING
| Once per engine tick, but no more than once per vehicle motion
|-
| SOUND_EVENT_TOUCHDOWN
| Aircraft touches down
|-
| SOUND_EVENT_VISUAL_EFFECT
| Visual effect is generated (steam plume, diesel smoke, electric spark)
|-
| SOUND_EVENT_RUNNING_16
| Every 16 engine ticks if in motion
|-
| SOUND_EVENT_STOPPED
| Every 16 engine ticks if stopped
|-
| SOUND_EVENT_LOAD_UNLOAD
| Consist loads or unloads cargo
|}

== Vehicle IDs ==
Picking an item ID requires keeping two cases in mind: OpenTTD with the engine pool enabled and OpenTTD with engine pool disabled / TTDPatch. The status of the engine pool may be checked with the global variable [[NML:General#General_variables|dynamic_engines]].

=== Engine pool enabled ===
With the engine pool enabled, each NewGRF has its own ID range, NewGRFs don't influence each other. IDs may freely be chosen between 0 and 65535. If the chosen ID belongs to an existing vehicle, this vehicle is overridden by your vehicle. If another NewGRF is already overriding that vehicle, a new vehicle will be allocated, but all the properties will be copied from the old vehicle. If you define an ID for which no original vehicle exists, a new (blank) vehicle is allocated.

This behaviour can be modified using an [[NML:Overriding_vehicles_in_other_NewGRFs|engine_override]], this allows changing the properties of vehicles defined in other NewGRFs instead of allocating a new vehicle.

=== TTDPatch / Engine pool disabled ===
Each new vehicle has to replace an existing vehicle. If multiple NewGRFs try to replace the same vehicle, the last NewGRF loaded 'wins'. [[VehicleIDs|This page]] contains a list of valid vehicle IDs for each vehicle type, look in the 'NML ID' column. Note that IDs are not bound to a specific sort of vehicle (e.g. monorail wagons) but to a feature (e.g. trains, road vehicles).

In general, you should take the following steps:
* If your NewGRF is intended as a complete replacement for the default vehicles, disable the relevant default vehicles using [[NML:Disable_items|disable_item]].
* Re-use IDs of existing vehicles as much as possible.
* If your NewGRF uses IDs outside of the normal range (for example, because you there are more vehicles than slots available), let your code check if dynamic_engies is enabled. If not, skip the vehicles outside the normal range (using an if-statement) and make sure that the remaining vehicles allow for reasonable gameplay. It is recommended to issue a warning to the user about this. Alternatively, it is also possible to disable your entire NewGRF. If you don't do this check and dynamic_engines is off, OpenTTD may disable your NewGRF with the somewhat cryptic message 'Attempt to use invalid ID', which will likely lead to bug reports about your NewGRF and/or your OpenTTD.

NML:Changes 0.4

2015-02-19T13:21:14Z

Planetmaker: style for variables, callbacks and constants

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

== Change to python3 ==
With NML 0.4 we change some of its foundations, it now is written in python3 and requires python 3.2 or newer. Requirements are:
* python 3.2 or newer
* python3-pillow (imaging library)
* python3-ply (lexer library)

== Other changes ==
* New warnings about and flags for realsprites: (NO)ALPHA, (NO)WHITE and (NO)ANIM. See explanation in [[NML:Realsprites|realsprite page]].
* Rigerous caching of real sprites. This improves encoding speed a lot on subsequent runs, especially for NewGRFs with many real sprites, more so for 32bpp
* Statistics on the NewGRF on used IDs for vehicles, houses, etc as well as available switches, parameters etc

== Language additions ==
* Feature: vehicle property <code style="color:darkgreen">effect_spawn_model_and_powered</code> and related callback <code style="color:darkgreen">create_effect</code>
* Feature: <code style="color:darkgreen">EFFECT_SPRITE_NONE</code> constant for <code style="color:darkgreen">create_effect</code> callback
* Feature: support for <code style="color:darkgreen">OTTD_RECOLOUR</code> action5 sprite(s)
* Feature: Support for Latin translations
* Feature: <code style="color:darkgreen">wagon_speed_limits</code> variable to test for enabled wagon speed limits. (issue #6474)

There's numerous other fixes, changes and additions. For a full changelog, see http://bundles.openttdcoop.org/nml/releases/0.4.0/changelog.txt
Get the latest release version from the bundles server: http://bundles.openttdcoop.org/nml/releases/LATEST/

NML:Changes 0.4

2015-02-19T13:12:55Z

Planetmaker: Note to package maintainers not necessary here

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

== Change to python3 ==
With NML 0.4 we change some of its foundations, it now is written in python3 and requires python 3.2 or newer. Requirements are:
* python 3.2 or newer
* python3-pillow (imaging library)
* python3-ply (lexer library)

== Other changes ==
* New warnings about and flags for realsprites: (NO)ALPHA, (NO)WHITE and (NO)ANIM. See explanation in [[NML:Realsprites|realsprite page]].
* Rigerous caching of real sprites. This improves encoding speed a lot on subsequent runs, especially for NewGRFs with many real sprites, more so for 32bpp
* Statistics on the NewGRF on used IDs for vehicles, houses, etc as well as available switches, parameters etc

* Feature: [NewGRF] create_effect and effect_spawn_model
* Feature: [NewGRF] EFFECT_SPRITE_NONE constant for create_effect callback
* Feature: [NewGRF] support for OTTD_RECOLOUR action5 sprite(s)
* Feature: [NewGRF] Support for Latin translations
* Feature: [NewGRF] Variable to test for enabled wagon speed limits. (issue #6474)
* Feature: [NewGRF] Warn about usage of animation and semi-transparent colours, and add spriteset flags to enable/disable the checks. (issue #1085)

There's numerous other fixes, changes and additions. For a full changelog, see http://bundles.openttdcoop.org/nml/releases/0.4.0/changelog.txt
Get the latest release version from the bundles server: http://bundles.openttdcoop.org/nml/releases/LATEST/

NML:Changes 0.4

2015-02-19T13:12:28Z

Planetmaker: Changes in NML 0.4.0

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

== Change to python3 ==
With NML 0.4 we change some of its foundations, it now is written in python3 and requires python 3.2 or newer. Requirements are:
* python 3.2 or newer
* python3-pillow (imaging library)
* python3-ply (lexer library)

== Other changes ==
* New warnings about and flags for realsprites: (NO)ALPHA, (NO)WHITE and (NO)ANIM. See explanation in [[NML:Realsprites|realsprite page]].
* Rigerous caching of real sprites. This improves encoding speed a lot on subsequent runs, especially for NewGRFs with many real sprites, more so for 32bpp
* Statistics on the NewGRF on used IDs for vehicles, houses, etc as well as available switches, parameters etc

* Feature: [NewGRF] create_effect and effect_spawn_model
* Feature: [NewGRF] EFFECT_SPRITE_NONE constant for create_effect callback
* Feature: [NewGRF] support for OTTD_RECOLOUR action5 sprite(s)
* Feature: [NewGRF] Support for Latin translations
* Feature: [NewGRF] Variable to test for enabled wagon speed limits. (issue #6474)
* Feature: [NewGRF] Warn about usage of animation and semi-transparent colours, and add spriteset flags to enable/disable the checks. (issue #1085)

There's numerous other fixes, changes and additions. For a full changelog, see http://bundles.openttdcoop.org/nml/releases/0.4.0/changelog.txt
Get the latest release version from the bundles server: http://bundles.openttdcoop.org/nml/releases/LATEST/

Note to package maintainers:

Dependency change: python 3.2+
Dependency change: preferably use pillow for python3 as imaging library instead of PIL.
Build requirement change (optional): c compiler needed to build the optional cython module for grf encoding (nml/_lz77.c). It's an optional speed improvement over the python-only implementation.

NML:Changes 0.4

2014-11-09T01:51:38Z

Planetmaker: /* Introduction */ Not quite an introduction

NML:Changes 0.4

2014-11-09T01:50:01Z

Planetmaker: /* Other changes */ new realsprite flags

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

== Introduction ==
With NML 0.4 we change some of its foundations, it now is written in python3 and requires python 3.2 or newer. Requirements are:
* python 3.2 or newer
* python3-pillow (imaging library)
* python3-ply (lexer library)

== Other changes ==
* New warnings about and flags for realsprites: (NO)ALPHA, (NO)WHITE and (NO)ANIM. See explanation in [[NML:Realsprites|realsprite page]].

NML:General

2014-10-24T09:22:10Z

Planetmaker: /* General variables */ max map size is 4096

{{NMLNavPropVarCB}}

==General variables==

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

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

<pre style="color:blue">
traininfo_y_offset = -2;
</pre></ref>
| 0 or 1
| If 1, desert roads have pavement and street lights.
|-
| <code style="color:green">train_width_32_px</code>
| Yes <ref name=readwrite />
| 0 or 1
| If 1, train vehicles are 32 instead of 29 pixels wide in the depot view.
|-
| <code style="color:green">traininfo_y_offset</code>
| Yes <ref name=readwrite />
| -128 .. 127
| Used to correctly position the depot view of trains.
|-
| <code style="color:green">snowline_height</code>
| No
| {{nml|0.2}} 16 .. 120 in steps of 8, or 0xFF if no snow.
{{nml|0.3}} 0..max_tile_height, or 0xFF if no snow.
| {{nml|0.2}} One tile height is equivalent to 8 units.
{{nml|0.3}} It's the height in tiles.
|-
| <code style="color:green">traffic_side</code>
| Yes <ref name=gamechange />
| <code style="color:green">TRAFFIC_SIDE_LEFT</code> or <code style="color:green">TRAFFIC_SIDE_RIGHT</code>
|
|-
| <code style="color:green">freight_trains</code>
| Yes
| 1 .. 255
| Weight multiplier for freight trains
|-
| <code style="color:green">plane_speed</code>
| Yes
| 1 .. 4
| Speed multiplier for planes. Value of 1 is equal to the original speed (1/4), while 4 means that planes move at full speed (4/4)
|-
| <code style="color:green">ttdpatch_flags</code>
| Yes
|
|
|-
| <code style="color:green">current_callback</code>
| No
|
| Set to the ID of the current callback, useful for old-style callbacks.
|-
| <code style="color:green">extra_callback_info1</code>
| No
| Varies
| Extra callback information, meaning differs per callback.
|-
| <code style="color:green">extra_callback_info2</code>
| No
| Varies
| Extra callback information, meaning differs per callback.
|-
| <code style="color:green">last_computed_result</code>
| No
|
| Result of the last (previously evaluated) switch block.
|-
| <code style="color:green">base_sprite_2cc</code>
| Yes
| 0 .. 65535
| Base sprite for 2cc (dual company colour) colour-maps
|-
| <code style="color:green">base_sprite_foundations</code>
| Yes
| 0 .. 65535
| {{ottdp|1.4|no|ottdrev=r25230}} Base sprite for foundations. This sprite block does only contain the extra foundations from [[NML:Replace_new_sprites| replacenew]] type <code style="color:green">FOUNDATIONS_SLOPES_HALFTILES</code> or <code style="color:green">FOUNDATIONS_SLOPES</code>. It does not contain the default foundations of sprites 990 to 1003 (via replace)
|-
| <code style="color:green">base_sprite_shores</code>
| Yes
| 0 .. 65535
| {{ottdp|1.4|no|ottdrev=r25230}} Base sprite for shores. All coast sprites in the order of the [[Action5#0D_Coast_tile_sprites|16 sprites version]] of [[NML:Replace_new_sprites| replacenew]] type <code style="color:green">COAST_TILES</code>. Note that, it does not matter in which way the sprites were originally defined (whether via replacenew with 10 or 16 sprites, or via replace). The sprite block returned by this variable has always all sprites in the same order.
|-
| <code style="color:green">map_type</code>
| Yes
| <code style="color:green">MAP_TYPE_XXX</code> with <code style="color:green">XXX</code> = [<code style="color:green">RECTANGULAR</code> <nowiki>|</nowiki> <code style="color:green">X_BIGGER</code> <nowiki>|</nowiki> <code style="color:green">Y_BIGGER</code>]
|
|-
| <code style="color:green">map_min_edge</code>
| Yes
| 64 .. 4096
| Length of the smallest map edge (in tiles)
|-
| <code style="color:green">map_max_edge</code>
| Yes
| 64 .. 4096
| Length of the biggest map edge (in tiles)
|-
| <code style="color:green">map_x_edge</code>
| Yes
| 64 .. 4096
| Length of the x (top-left) map edge (in tiles)
|-
| <code style="color:green">map_y_edge</code>
| Yes
| 64 .. 4096
| Length of the y (top-right) map edge (in tiles)
|-
| <code style="color:green">map_size</code>
| Yes
| 64*64 .. 4096*4096
| Total number of tiles on the map
|-
| <code style="color:green">long_bridges</code>
| Yes
| 0 or 1
|
|-
| <code style="color:green">gradual_loading</code>
| Yes
| 0 or 1
|
|-
| <code style="color:green">bridge_speed_limits</code>
| Yes
| {{ttdp|}} 0 or 1 {{ottd|}} Always 1
|
|-
| <code style="color:green">signals_on_traffic_side</code>
| Yes
| 0 or 1
|
|-
| <code style="color:green">electrified_railways</code>
| Yes
| 0 or 1
|
|-
| <code style="color:green">unified_maglev</code>
| Yes
| {{ttdp|}} 0 .. 3 {{ottd|}} Always 3
|
|-
| <code style="color:green">temperate_snowline</code>
| Yes
| {{ttdp|}} 0 or 1 {{ottd|}} Always 0
|
|-
| <code style="color:green">dynamic_engines</code>
| Yes
| 0 or 1
|
|-
| <code style="color:green">variable_runningcosts</code>
| Yes
| {{ttdp|}} 0 or 1 {{ottd|}} Always 1
|
|-
| <code style="color:green">newtrains</code>
| Yes
| {{ttdp|}} 0 or 1 {{ottd|}} Always 1
|
|-
| <code style="color:green">newrvs</code>
| Yes
| {{ttdp|}} 0 or 1 {{ottd|}} Always 1
|
|-
| <code style="color:green">newships</code>
| Yes
| {{ttdp|}} 0 or 1 {{ottd|}} Always 1
|
|-
| <code style="color:green">newplanes</code>
| Yes
| {{ttdp|}} 0 or 1 {{ottd|}} Always 1
|
|-
| <code style="color:green">newhouses</code>
| Yes
| {{ttdp|}} 0 or 1 {{ottd|}} Always 1
|
|-
| <code style="color:green">newindustries</code>
| Yes
| {{ttdp|}} 0 or 1 {{ottd|}} Always 1
|
|-
| <code style="color:green">newcargos</code>
| Yes
| {{ttdp|}} 0 or 1 {{ottd|}} Always 1
|
|}

<references />

ReadingPatchVariables

2014-10-24T09:19:39Z

Planetmaker: /* variable */ map height is variable now

== Introduction ==

Since TTDPatch 2.0.1 alpha 48, it has been possible to use action D to read various special Patch variables. These are usually switch values, but there are also a few other useful values.

== Syntax ==

<Sprite-number> * <Length> 0D <target> <operation> <variable> FE FF FF 00 00

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

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

|-
|<target>||B||Target parameter

|-
|<operation>||B||As for ActionD, but only assignment is valid.

|-
|<variable>||B||Patch variable number to read. See below.

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

|-
|FF FF 00 00||D||Indicates that a patch variable is being read
|}

== variable ==

The following patch variables are defined:

{|
!variable!!Switch!!Version!!Value
|-
|00||miscmods/-Yo||{{ottdp|no|2.5}}||Bit switch
|-
|01||experimentalfeatures/-XF||{{ottdp|no|2.5}}||Bit switch
|-
|02||morevehicles/-x||{{ottdp|no|2.5}}||Vehicle array multiplier
|-
|03||mountains and curves/-mc||{{ottdp|no|2.5}}||Two bytes with four sets of two bits
|-
|04||planecrashcontrol/-Xc||{{ottdp|no|2.5}}||Bit switch
|-
|05||autorenew/-Xa||{{ottdp|no|2.5}}||Signed value
|-
|06||multihead/-M||{{ottdp|no|2.5}}||Speed increase, in percent
|-
|07||disasters/-XD||{{ottdp|no|2.5}}||Bit switch
|-
|08||unifiedmaglev/-XM||{{ottdp|no|2.5}}||Unified maglev mode
|-
|09||bridgespeedlimits/-XX||{{ottdp|no|2.5}}||Speed fraction, in percent
|-
|0A||---||{{ottdp|no|2.5}}||TTD Language, see the "new scheme" for [[Action4#language id|action 4]]
|-
|0B||startyear/-XY||{{ottdp|0.6|2.5}}||Year-1920
|-
|0C||morebuildoptions/-YB||{{ottdp|no|2.5}}||Bit switch
|-
|0D||moresteam/-YM||{{ottdp|no|2.5}}||value=LF (two hex digits), L=length, F=frequency
|-
|0E||freighttrains/-Yf||{{ottdp|0.6|2.5}}||weight factor
|-
|0F||wagonspeedlimits/-YL||{{ottdp|0.6|2.5}}||Speed increase for empty wagons
|-
|10||planespeed/-YP||{{ottdp|0.6|2.5}}||speed factor
|-
|11||dual company colors||{{ottdp|0.6|2.5|ttdprev=r1404}}||2CC colormap base sprite
|-
|12||miscmods2/-Zm||{{ottdp|no|2.6|ttdprev=r1738}}||Bit switch
|-
|13||map size information||{{ottdp|0.6|2.6|ottdrev=r11961|ttdprev=r1817}}||Format = -MABXYSS
{| |-
| M || the type of map
* bit 0 set: squared map. Clear : rectangular map
* bit 1 set: Y is the bigger edge(bit 0 is clear).Clear : X is the bigger edge.
|-
|A || minimum edge(log2) of the map
|-
|B || maximum edge(log2) of the map
|-
|XY || edges(log2) of each side of the map.
|-
|SS || combination of both X and Y, thus giving the size(log2) of the map
|-
|}
All map sizes will be substracted by 6, as to keep the size 64 the smallest one, thus zero based
|-
|14||maximum height level||{{ottdp|1.2|no|ottdrev=r23158}}||Maximal possible height level of a tile. {{ottdp|1.5|no|ottdrev=r27010}}Any value between 1 and 255. In earlier versions fixed at 15.
|-
|15||extra foundations||{{ottdp|1.4|no|ottdrev=r25230}}||Extra foundation sprites as set via [[Action5|Action 5 type 06]]. This sprite block does only contain the extra foundations from Action 5, it does not contain the default foundations of Action A sprites 990 to 1003.
|-
|16||coast sprites||{{ottdp|1.4|no|ottdrev=r25230}}||All coast sprites in the order of the 16 sprites version of [[Action5#In_NewGRFs|Action 5 type 0D]]. Note that, it does not matter in which way the sprites were originally defined (whether via Action 5 with 10 or 16 sprites, or via Action A), the sprite block returned by this variable has always all sprites in the same order.
|}

If experimentalfeatures, miscmods, or miscmods2 are off, the corresponding value will be zero. For all other switches, the value is unspecified if the switch is off, so [[TTDPatchFlags|action 7 variable 85]] should be checked first.

NML:Houses

2014-10-23T12:07:45Z

Planetmaker: /* House variables */ c&p error

{{NMLNavPropVarCB}}
==House IDs==
House IDs are local to the NewGRF, you are free to choose any ID in the 0..255-range. You should start your item definition with the 'substitute'-property, which allocates a new house. The value of this property should be the ID of a [[NML:List_of_default_house_properties|default house type]], which will be used instead of your item if it is not available for whatever reason (for example, missing NewGRF).

Although the majority of all original houses occupy a single tile, it is possible to define a larger house of up to 2x2 tiles. For this, you should set the fourth 'size' parameter in the item-block. Valid values are HOUSE_SIZE_XXX, XXX = <nowiki>[1X1 | 1X2 | 2X1 | 2X2]</nowiki>. This size should match the size of the substitute house type.

===Multi-tile houses===
Internally, due to the way NewGRF houses work, a multi-tile house will occupy more than one item ID. If you assign item ID X to a house, item IDs X+1 (for a 2-tile house) and (X+1) .. (X+3) (for a 4-tile house) will also be used. Normally you don't have to care about this, but there are two exceptions:
* If you manually assign numeric ids to your houses. You are recommended to just set all ids to -1 and let NML figure it out for you.
* When working with several variables that work with house type IDs. Keep in mind that tiles of a multi-tile house may have IDs X .. X + N - 1, with X being the assigned id and N the number of house tiles.

==House properties==

{| class="t"
! property
! value range
! comment
|-
| name
| string
| for example string(STR_NAME_EIFFEL_TOWER)
|-
| substitute
| 0 ... 109
| Number of the default house that replaces this one, if this house is not available for some reason. This property ''must'' be set first, before any other properties or graphics. All properties of the old type are copied to your new house, except for the church / stadium flags (see below). The old house must have the same size as the new house, see the list of [[NML:List_of_default_house_properties|default house types]] for a list of possible substitute IDs.
|-
| override
| 0 ... 109
| id of the default house which this house replaces (and thus disabling the default). This is ignored, if the default house has already been overridden (disabling it another time is pointless). You can define this property multiple times. Your house and the overridden house must have the same size, see the list of [[NML:List_of_default_house_properties|default house types]].
|-
| building_flags.
| bitmask(HOUSE_FLAG_XXX,...)
|
;HOUSE_FLAG_NOT_SLOPED
:Can only be built on flat terrain. Note that 2x2 buildings will always only be built on flat land, even if this bit isn't set.
;HOUSE_FLAG_ANIMATE
:Enable animation
;HOUSE_FLAG_CHURCH
:House is a church (only 1 will be built per town)
;HOUSE_FLAG_STADIUM
:House is a stadium (only 1 will be built per town)
;HOUSE_FLAG_ONLY_SE
:Can only be built in the scenario editor
;HOUSE_FLAG_PROTECTED
:Will not be removed by the game
;HOUSE_FLAG_SYNC_CALLBACK
:Animation callback <code style="color:darkgreen">anim_control</code> is called at the same time for all tiles.
;HOUSE_FLAG_RANDOM_ANIMATION
:Enable random bits in the <code style="color:darkgreen">anim_next_frame</code>-callback.
|-
| population
| 0 ... 255
| number of inhabitants the building adds to the town, if present
|-
| mail_multiplier
| 0 ... 255
|
|-
| accepted_cargos
| Array with up to 3 [cargo_id, amount]-pairs.
| The cargos that are accepted by each tile of the house. CargoID is a cargo type from your cargo translation table, amount is the acceptance of the given cargo in 1/8 units.<br /> Example: to make a tile fully accept both PASS and MAIL you could use this: <code style="color:darkgreen"><nowiki>accepted_cargos: [[PASS, 8], [MAIL, 8]];</nowiki></code><br /> Example: for a house tile that doesn't accept any cargos at all you'd use: <code style="color:darkgreen">accepted_cargos: [];</code>
|-
| local_authority_impact
| 0 ... 65525
| amount of happiness decrease of the city council, if the building is destroyed. Town ratings can vary between -1000 (appalling) and +1000 (outstanding).
|-
| removal_cost_multiplier
| 0 ... 255
|
|-
| probability
| 0 ... 15 (float)
| Probability with respect to the default houses (=1). Mind that these are relative probabilities with respect to all houses defined. If all probabilities are defined as 16, they'll all have the same probability as if they had all a probability of 1.
|-
| years_available
| array of two int
| [xx, yy] where xx and yy indicate the introduction year and the last year the building can be built
|-
| minimum_lifetime
| 0 ... 255
| number of years the building will remain at least
|-
| availability_mask
|
[bitmask([[NML:List of town zones|town zones]]), bitmask(CLIMATE_XXX, ...)]
|
An array with two bitmasks, the first bitmask is a mask of town zones where this house is available. The second bitmask is a mask of climates combined with the special value ABOVE_SNOWLINE which you need to set for houses available in the arctic climate above the snowline.<br /> Examples:

* Available in the centre town zone in toyland only: <code>[bitmask(TOWNZONE_CENTRE), bitmask(CLIMATE_TOYLAND)]</code>
* Available in all town zones in the arctic climate both above and below the snowline: <code>[ALL_TOWNZONES, bitmask(CLIMATE_ARCTIC, ABOVE_SNOWLINE)]</code>
* Available everywhere except on the town edge: <code>[ALL_TOWNZONES & ~bitmask(TOWNZONE_EDGE), ALL_CLIMATES | bitmask(ABOVE_SNOWLINE)</code>
|-
| callback_flags
| bitmask(HOUSE_CBF_XX)
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| random_colours
| array of 4, each COLOUR_XXX
|
colour values in an array, refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for a list of possible values.
|-
| refresh_multiplier
| 0 ... 63
| Defines the frequency with which the tile will be re-randomized which has an impact for random animation. The tile will be processed by the periodic tile processing loop every (X + 1)*256 ticks, with X being the value of this property.
|-
| animation_info
| Array [ANIMATION_XXX, frame-count]
|
Type of animation and its length (1...128 frames):

;ANIMATION_LOOPING
;ANIMATION_NON_LOOPING
|-
| animation_speed
| 2 ... 16
|
Speed of animation, see [[NML:Animation speed|animation speed table]] for the meaning of the values.
|-
| building_class
| 0 .. 254
| An arbitrary number. You can check for the presence of buildings of the same class when building new buildings or using animation. Only the north tile of a multi-tile building is assigned a class.
|
|-
| watched_cargo_types
| array of values from your [[NML:Cargotable|cargo table]]
| {{ottdp|1.2|2.6|ottdrev=r23072|ttdprev=r1677}}List of cargo types to watch, to be used with the <code style:darkgreen>watched_cargo_accepted</code> callback.
|}

==House variables==

{| class="t"
! name
! value range
! comment
|-
| construction_state
| 0..3
| Current construction state of the house tile. 0..2 = under construction, 3 = finished.
|-
| pseudo_random_bits
| 0..3
| Some pseudo-random bits, based on the tile position. TTD houses use this to randomize their appearance.
|-
| random_bits
| 0..255
| 8 random bits, also used for [[NML:Random_switch|random switch]]-blocks. Initially these are the same for all tiles of a multi-tile house.
|-
| age
| 0..255
| Age of the house in years, limited to 255
|-
| town_zone
| [[NML:List of town zones|town zone]]
| The town zone of the current tile
|-
| terrain_type
| TILETYPE_XX
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|-
| same_house_count_town
| 0..255
| Number of the houses with the same ID in the same town as this house
|-
| same_house_count_map
| 0..255
| Number of the houses with the same ID on the entire map
|-
| same_class_count_town
| 0..255
| Number of the houses with the same <code style="color:darkgreen">building_class</code> in the same town as this house. The class of the north tile of the use is used for this purpose, as other tiles don't normally have a class.
|-
| same_class_count_map
| 0..255
| Number of the houses with the same <code style="color:darkgreen">building_class</code> on the entire map. The class of the north tile of the use is used for this purpose, as other tiles don't normally have a class.
|-
| generating_town
| [0 <nowiki>|</nowiki> 1]
| 1 a random town is currently being created, 0 otherwise. Note that while generating a random town, [[NML:Towns#Town variables|town variables]] <code style="color:darkgreen">population</code> and <code style="color:darkgreen">building_count</code> are incorrect. The population variable contains the population of buildings generated ''yet'', the final value may be larger. The building_count is surely higher than the final value will be.
|-
| animation_frame
| 0..255
| Current animation frame
|-
| x_coordinate
| 0..2047
| X-coordinate (top right -> bottom left) of the tile on the map
|-
| y_coordinate
| 0..2047
| Y-coordinate (top left -> bottom right) of the tile on the map
|-
| relative_x
| 0..1
| X-coordinate (top right -> bottom left) of the tile relative to the northernmost tile.
|-
| relative_y
| 0..1
| 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.
|-
| house_tile
| HOUSE_TILE_XXX, XXX = <nowiki>[NORTH | EAST | WEST | SOUTH]</nowiki>
| What tile of a multi-tile house this is.
|-
| house_type_id
| 0..255
| Item ID of this house type, that was assigned to the item. See the note above about [[#Multi-tile houses|multi-tile houses]].
|}

The following variables require one or more arguments
{| class="t"
! name
! arguments
! value range
! comment
|-
| old_house_count_town
| ID of old house type (0..109)
| 0..255
| Number of old houses with a given ID in the same town as the current house
|-
| old_house_count_map
| ID of old house type (0..109)
| 0..255
| Number of old houses with a given ID on the whole map
|-
| other_house_count_town
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses with a given ID in the same town as the current house.
|-
| other_house_count_map
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses with a given ID on the whole map
|-
| other_class_count_town
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses, with the same class as the house with the given ID, in the same town as the current house
|-
| other_class_count_map
| ID of house defined in this NewGRF (0..255)
| 0..255
| Number of houses, with the same class as the house with the given ID, on the whole map
|-
| nearby_tile_slope
| x- and y-offset (both signed, range -8..7)
| SLOPE_XXX
| See [[NML:List of tile slopes|tile slopes]] for an overview of possible values
|-
| nearby_tile_is_water
| x- and y-offset (both signed, range -8..7)
| [0 <nowiki>|</nowiki> 1]
| 1 if the tile is water, 0 otherwise
|-
| nearby_tile_terrain_type
| x- and y-offset (both signed, range -8..7)
| TILETYPE_XX
| TILETYPE_NORMAL, TILETYPE_DESERT, TILETYPE_RAIN_FOREST, TILETYPE_SNOW
|-
| nearby_tile_water_class
| x- and y-offset (both signed, range -8..7)
| WATER_CLASS_XXX
| XXX = [NONE <nowiki>|</nowiki> SEA <nowiki>|</nowiki> CANAL <nowiki>|</nowiki> RIVER] Note that tiles for which <code style="color:darkgreen">nearby_tile_is_water</code> is 0 may still have a water class, e.g. industry tiles with water beneath them.
|-
| nearby_tile_height
| x- and y-offset (both signed, range -8..7)
| 0..255 (currently limited to 0..15)
| Height of the lowest corner of the tile. 1 unit is one height level of 8 pixels.
|-
| nearby_tile_class
| x- and y-offset (both signed, range -8..7)
|
[[NML:List of tile classes|Tile class]]
|
|-
| nearby_tile_animation_frame
| x- and y-offset (both signed, range -8..7)
| 0..255
| Animation frame of the given tile
|-
| cargo_accepted_nearby_ever
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby">Cargo type should be from your cargo translation table. X- and y-offset are optional, if provided both must be in range -128..127. A station is considered nearby if the tile is in the station's acceptance area. This is the purpose of the x- and y-offset, as other tiles may have other stations nearby.</ref>
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was ever accepted at a nearby station, 0 otherwise
|-
| cargo_accepted_nearby_last_month
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was accepted at a nearby station in the last month, 0 otherwise
|-
| cargo_accepted_nearby_this_month
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was ever accepted at a nearby station in this month, 0 otherwise
|-
| cargo_accepted_nearby_last_bigtick
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was ever accepted at a nearby station since the last periodic processing, which happens every 250 ticks. 0 otherwise
|-
| cargo_accepted_nearby_watched
| cargo type, x- and y-offset <ref name="cargo_accepted_nearby" />
| [0 <nowiki>|</nowiki> 1]
| 1 if the given cargo type was one of the cargo types that triggered the <code style="color:darkgreen">watched_cargo_accepted</code>-callback (only during this callback), 0 otherwise
|-
| nearest_house_matching_criterion
| radius (1..63) and criterion (SEARCH_HOUSE_BY_XXX, XXX = [<nowiki>TYPE | CLASS | GRFID</nowiki>])
| 1..63, or 0 if not found
| Perform a circular search for a house matching either the id, <code style="color:darkgreen">building_class</code> or GRFID of this house, depending on the second parameter. The first parameter specifies the maximum search radius. Return value is the Manhattan distance of the closest matching house tile, or 0 if no match was found. Note that tiles of the originating house never match. See also the note above about [[#Multi-tile houses|multi-tile houses]].
|-
| nearby_tile_house_id
| x- and y-offset (both signed, range -8..7)
| -1, or 0 .. 767
| Return value is -1 if the tile is not a house tile, X (0..255) if the tile contains old house type X, 256+X if the tile contains a house from this NewGRF with ID X, 512+X if the tile contains a house from a different NewGRF with ID X. See the note above about [[#Multi-tile houses|multi-tile houses]].
|-
| nearby_tile_house_class
| x- and y-offset (both signed, range -8..7)
| -1, 0, or 256 .. 767
| Return value is -1 if the tile is not a house tile, 0 if the house tile does not have a class (this includes all old house types), 256+X (X = 0..255) if the house has been defined by this NewGRF with <code style="color:darkgreen">building_class</code> X or 512+X if the house has been defined by a different NewGRF with <code style="color:darkgreen">building_class</code> X. Note that for a multi-tile house, generally only the north tile has a sensible class value.
|-
| nearby_tile_house_grfid
| x- and y-offset (both signed, range -8..7)
| -1, 0 or a GRFID
| Return value is -1 if the tile is not a house tile, 0 if the house tile contains an old house type, or else the GRFID of the NewGRF defining the house.
|}
<references/>

==House callbacks==
Unless noted otherwise, callbacks may be called for any of the tiles of a multi-tile house.

{| class="t"
! callback
! return value
! comment
|-
| default
| Sprite layout
| Graphics for the house tile
|-
| graphics_xxx, xxx = <nowiki>[north | east | south | west]</nowiki>
| Sprite layout
| Tile-specific graphics for one of the tiles of a multi-tile house. Of course, this is callback is called for that tile only.
|-
| random_trigger
| N/A
|
See [[NML:Random switch|random switch]] for more information.
|-
| anim_next_frame
| Next animation frame or CB_RESULT_XXX
| Called for every animation frame, returns the next frame to display. Alternatively, return CB_RESULT_NEXT_FRAME or CB_RESULT_STOP_ANIMATION to show the next frame or stop animation, respectively. <code>extra_callback_info1</code> contains 32 random bits, if enabled in the <code>building_flags</code> property. Returning a sound effect in the high byte will cause that sound effect to be played.
|-
| anim_control
| Next animation frame or CB_RESULT_XXX
| Called every 256 ticks. Return the animation frame to show, or CB_RESULT_XXX with XXX = <nowiki>[CB_RESULT_START_ANIMATION | STOP_ANIMATION | DO_NOTHING]</nowiki> to respectively start the animation in its current frame, stop the animation or do nothing. <code>extra_callback_info1</code> contains 32 random bits. The low 16 bits are always different for each house tile, but the high 16 bits are the same for each tile if synchronized animation is enabled in the <code>building_flags</code>-property. Returning a sound effect in the high byte will cause that sound effect to be played.
|-
| construction_anim
| Same as <code>anim_control</code>
| Works the same as the <code>anim_control</code> callback, except that it's called when the construction state changes.
|-
| watched_cargo_accepted
| Same as <code>anim_control</code>
| Works the same as the <code>anim_control</code> callback, except that it's called when one of the watched cargo types is accepted.
|-
| anim_speed
| 0 .. 16
| Decide the time an animation frame should last. Return value is interpreted as (num_ticks = 2^anim_speed), which each tick lasting 30 ms. Avoid using this callback if possible, since it has to be called each tick for every animated tile. This can be used to create animation frames that last between 30 ms and 33 minutes.
|-
| cargo_type_accept
| type1 + (type2 << 5) + (type3 << 10)
| Decide the cargo types that this tile accepts. If this callback is not implemented or fails, the values from <code>accepted_cargo</code> are used instead. Bits 0..4: First cargo type. Bits 5..9: Second cargo type. Bits 10..14: Third cargo type.
|-
| cargo_amount_accept
| amt1 + (amt2 << 4) + (amt3 << 8)
| Acceptance for each cargo amount in 1/8th. If this callback is not implemented or fails, the values from the acceptance properties are used instead. Cargo types are from the <code>cargo_type_accept</code> callback, or the <code>accepted_cargo</code> property if that callback failed. Bits 0..3: Acceptance of first cargo type. Bits 4..7: Acceptance of second cargo type. Bits 8..11: Acceptance of third cargo type.
|-
| cargo_production
| (cargo_type * 256) + amount, or <code>CB_RESULT_HOUSE_NO_MORE_PRODUCTION</code>
| Called every 256 ticks. The return value specifies what cargo and what amount is produced. The callback is called multiple times until <code>CB_RESULT_HOUSE_NO_MORE_PRODUCTION</code> is returned. <code>extra_callback_info1</code> contains the number of iterations so far, <code>extra_callback_info2</code> contains random bits.
|-
| foundations
| CB_RESULT[_NO]_FOUNDATIONS
| Return CB_RESULT_FOUNDATIONS to draw standard foundations (default) or CB_RESULT_NO_FOUNDATIONS to not draw them.
|-
| autoslope
| CB_RESULT[_NO]_AUTOSLOPE
| Return CB_RESULT_AUTOSLOPE to allow autoslope (altering the ground below a tile) or CB_RESULT_NO_AUTOSLOPE to disallow it.
|-
| name
| String
| Name of the building (when using tile query tool)
|-
| colour
| Palette number
|
Used to recolour the building. See here [[NML:List of default colour translation palettes|here]] for an overview of default palettes.
|-
| construction_check
| 0 or 1
| Return 1 to allow building the house or 0 to disallow. Called only for the north tile.
|-
| destruction
| 0 or 1
| Called periodically. Return 0 to keep the building or 1 to destroy it. Called only for the north tile.
|-
| protection
| 0 or 1
| Return 0 to allow destruction, or 1 to disallow
|}

Action4

2014-10-12T08:46:51Z

Planetmaker: /* language IDs */ make use of language_IDs in order to de-duplicate language lists

==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 16 colour codes are available for use:

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

==Example==

NML:Language files

2014-10-12T08:35:14Z

Planetmaker: /* LanguageIDs */ Use the shared list of languageIDs

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

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

Language files MUST have the extension <code style="color:darkgreen">.lng</code><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
|-
|SILVER || switch to silver text
|-
|GOLD || switch to golden text
|-
|RED || switch to red text
|-
|PURPLE || switch to purple text
|-
|LTBROWN || switch to light brown text
|-
|ORANGE || switch to orange text
|-
|GREEN || switch to green text
|-
|YELLOW || switch to yellow text
|-
|DKGREEN || switch to dark green text
|-
|CREAM || switch to cream-coloured text
|-
|BROWN || switch to brown text
|-
|WHITE || switch to white text
|-
|LTBLUE || switch to light blue text
|-
|GRAY || switch to gray text
|-
|DKBLUE || switch to dark blue text
|-
|BLACK || switch to black text
|}
== String parameters ==
The above tags can be used in almost all strings. There are also a number of tags that need an argument they'll read from the textstack. The textstack is only available for certain callbacks an properties.
{|
!width="150pt"|Tag
!width="600pt"|Meaning
!Size (number of bytes read from stack)
!Example
|-
|COMMA || signed number with decimal separator between 1000's. || 4
|-
|SIGNED_WORD || signed number with decimal separator between 1000's. || 2
|-
|UNSIGNED_WORD || unsigned number with decimal separator between 1000's. || 2
|-
|CURRENCY || money in proper currency units || 4 || 24,492 €
|-
|VELOCITY || velocity in proper units || 2 || 35 km/h
|-
|VOLUME || volume in proper units || 2 || 29,000 litres
|-
|VOLUME_SHORT || volume in proper units in short form || 2 || 29,000l
|-
|POWER || power in proper units || 2 || 2,030 kW
|-
|WEIGHT || weight in proper units || 2 || 5 tonnes
|-
|WEIGHT_SHORT || weight in proper units in short form || 2 || 5t
|-
|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.

Language IDs

2014-10-12T08:28:57Z

Planetmaker: no double title

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

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

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

Language IDs

2014-10-12T08:28:27Z

Planetmaker: languageIDs as separate page to avoid duplication

== LanguageIDs ==
Currently, the scheme is to use international phone codes as language IDs, unless they're out of range. When creating a new translation for OpenTTD pick a number vaguely related in some way. Or something else.

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

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

NML:Replace new sprites

2014-09-21T11:30:21Z

Planetmaker: add additional recolour sprite(s)

{{NMLNavBlocksyntax}}

Over time, several features have been added to OpenTTD that require new sprites. As these sprites are not present in the original base graphics and only found in the extra grf of each base set. They cannot be replaced using a normal <code style="color:darkgreen">replace</code> block. Instead, a <code style="color:darkgreen">replacenew</code> block has to be used. The semantics are like this:

replacenew [<block-name>](<type>, [<image-file>[, <offset>]]) {
[[NML:Realsprites|list of realsprites]]
}

A <code style="color:darkgreen"><block_name></code> is optional but required, if you want to define [[NML:Alternative sprites|alternative sprites]] for the sprite block so that it can be referenced there.

The <code style="color:darkgreen"><type></code> parameter indicates the type of sprites that will be replaced. It should be an identifier from the first column of the following table.

For information on what sprites are needed and in what order, it's generally best to look at the OpenGFX source [http://hg.openttdcoop.org/opengfx/file/tip/sprites/extra], in the sprites/extra directory.

{| class="t"
! Type
! Number of sprites
|-
| PRE_SIGNAL
| 48
|-
| PRE_SIGNAL_SEMAPHORE
| 112
|-
| PRE_SIGNAL_SEMAPHORE_PBS
| 240
|-
| CATENARY
| 48
|-
| FOUNDATIONS_SLOPES
| 74
|-
| FOUNDATIONS_SLOPES_HALFTILES
| 90
|-

| CANALS
| 65
|-
| ONE_WAY_ROAD
| 6
|-
| COLOURMAP_2CC
| 256
|-
| TRAMWAY
| 113
|-

| COAST_TILES
| 16<ref name="no_offset">This type does not support the use of an offset. Thus the exact amount of sprites must be supplied.</ref>
|-
| COAST_TILES_BASEGFX
| 10<ref name="no_offset" />
|-
| COAST_TILES_DIAGONAL
| 18<ref name="no_offset" />
|-

| SLOPED_RAILS
| 12
|-
| AIRPORTS
| 15
|-
| ROAD_STOPS
| 8
|-
| AQUEDUCTS
| 8
|-
| AUTORAIL
| 55
|-
| FLAGS
| 36
|-
| OTTD_GUI
| 175
|-
| AIRPORT_PREVIEW
| 9
|-
| RAILTYPE_TUNNELS
| 16
|-
| OTTD_RECOLOUR
| 1
|}

Parameter two <code style="color:darkgreen"><image-file></code> (optional) is a literal (quoted) string that specifies the default file where the sprites are located. This may be overridden per-sprite.

Parameter <code style="color:darkgreen"><offset></code> is optional and has a default value of 0. Setting this value sets an offset into the block of sprites, so only a subset of the sprites (starting at <code style="color:darkgreen">offset</code>) will be replaced. An offset is not allowed in the case of the sprite types marked with <ref name="no_offset" />. Don't use offsets, if you want you NewGRF compatible with TTDPatch.

<references />

NML:Spritelayout

2014-09-02T19:21:28Z

Planetmaker: /* Positioning */ re-order description a bit

{{NMLNavBlocksyntax}}

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

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

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

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

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

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

===Sprite===

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

* <code style="color:darkgreen">GROUNDSPRITE_NORMAL<ref name="spritenames">These constants can be used for sprites on flat ground. There are also equivalent sprites for sloped ground, however. These sprites follow the initial ground sprite, the [[NML:Builtin functions|builtin function]] <code style="color:darkgreen">slope_to_sprite_offset(''slope'')</code> may be used to compute the required offset. Refer to the reference on [[NML:List of tile slopes|slopes]] or the [[#Example_.28advanced.29_Spritelayout|example]] below.</ref></code> default terrain type for that climate (temperate, toyland: normal, arctic: without snow, tropical: rainforest).
* <code style="color:darkgreen">GROUNDSPRITE_DESERT <ref name="spritenames" /></code> desert tile
* <code style="color:darkgreen">GROUNDSPRITE_DESERT_1_2 <ref name="spritenames" /></code> transition tile between desert and grass
* <code style="color:darkgreen">GROUNDSPRITE_SNOW <ref name="spritenames" /></code> snowy ground tile
* <code style="color:darkgreen">GROUNDSPRITE_SNOW_1_4 <ref name="spritenames" /></code> 1/4 snowy ground tile
* <code style="color:darkgreen">GROUNDSPRITE_SNOW_2_4 <ref name="spritenames" /></code> half-snowy ground tile
* <code style="color:darkgreen">GROUNDSPRITE_SNOW_3_4 <ref name="spritenames" /></code> 3/4 snowy ground tile
* <code style="color:darkgreen">GROUNDSPRITE_SNOW_4_4 <ref name="spritenames" /></code> snowy ground tile
* <code style="color:darkgreen">GROUNDSPRITE_CONCRETE</code> concrete ground tile
* <code style="color:darkgreen">GROUNDSPRITE_WATER</code> flat water tile
* <code style="color:darkgreen">GROUNDSPRITE_CLEARED <ref name="spritenames" /></code> ground tile that has just been bulldozed (with brown colour)

<references />

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

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

===Recolouring===

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

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

===Display yes/no===

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

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

===Positioning===

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

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

===Example (advanced) Spritelayout===

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

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

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

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

1
]) {
company_land_layout;
}
</pre>

NML:Spritelayout

2014-09-02T19:15:59Z

Planetmaker: /* Positioning */ rather recommend to accept nml's default (and not manually define these). Also explain the units for offsets and extents.

{{NMLNavBlocksyntax}}

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

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

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

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

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

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

===Sprite===

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

* <code style="color:darkgreen">GROUNDSPRITE_NORMAL<ref name="spritenames">These constants can be used for sprites on flat ground. There are also equivalent sprites for sloped ground, however. These sprites follow the initial ground sprite, the [[NML:Builtin functions|builtin function]] <code style="color:darkgreen">slope_to_sprite_offset(''slope'')</code> may be used to compute the required offset. Refer to the reference on [[NML:List of tile slopes|slopes]] or the [[#Example_.28advanced.29_Spritelayout|example]] below.</ref></code> default terrain type for that climate (temperate, toyland: normal, arctic: without snow, tropical: rainforest).
* <code style="color:darkgreen">GROUNDSPRITE_DESERT <ref name="spritenames" /></code> desert tile
* <code style="color:darkgreen">GROUNDSPRITE_DESERT_1_2 <ref name="spritenames" /></code> transition tile between desert and grass
* <code style="color:darkgreen">GROUNDSPRITE_SNOW <ref name="spritenames" /></code> snowy ground tile
* <code style="color:darkgreen">GROUNDSPRITE_SNOW_1_4 <ref name="spritenames" /></code> 1/4 snowy ground tile
* <code style="color:darkgreen">GROUNDSPRITE_SNOW_2_4 <ref name="spritenames" /></code> half-snowy ground tile
* <code style="color:darkgreen">GROUNDSPRITE_SNOW_3_4 <ref name="spritenames" /></code> 3/4 snowy ground tile
* <code style="color:darkgreen">GROUNDSPRITE_SNOW_4_4 <ref name="spritenames" /></code> snowy ground tile
* <code style="color:darkgreen">GROUNDSPRITE_CONCRETE</code> concrete ground tile
* <code style="color:darkgreen">GROUNDSPRITE_WATER</code> flat water tile
* <code style="color:darkgreen">GROUNDSPRITE_CLEARED <ref name="spritenames" /></code> ground tile that has just been bulldozed (with brown colour)

<references />

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

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

===Recolouring===

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

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

===Display yes/no===

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

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

===Positioning===

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

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

===Example (advanced) Spritelayout===

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

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

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

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

1
]) {
company_land_layout;
}
</pre>

NML:Spritelayout

2014-09-02T19:04:14Z

Planetmaker: /* Positioning */ Suggested default values for offsets and extents

{{NMLNavBlocksyntax}}

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

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

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

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

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

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

===Sprite===

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

* <code style="color:darkgreen">GROUNDSPRITE_NORMAL<ref name="spritenames">These constants can be used for sprites on flat ground. There are also equivalent sprites for sloped ground, however. These sprites follow the initial ground sprite, the [[NML:Builtin functions|builtin function]] <code style="color:darkgreen">slope_to_sprite_offset(''slope'')</code> may be used to compute the required offset. Refer to the reference on [[NML:List of tile slopes|slopes]] or the [[#Example_.28advanced.29_Spritelayout|example]] below.</ref></code> default terrain type for that climate (temperate, toyland: normal, arctic: without snow, tropical: rainforest).
* <code style="color:darkgreen">GROUNDSPRITE_DESERT <ref name="spritenames" /></code> desert tile
* <code style="color:darkgreen">GROUNDSPRITE_DESERT_1_2 <ref name="spritenames" /></code> transition tile between desert and grass
* <code style="color:darkgreen">GROUNDSPRITE_SNOW <ref name="spritenames" /></code> snowy ground tile
* <code style="color:darkgreen">GROUNDSPRITE_SNOW_1_4 <ref name="spritenames" /></code> 1/4 snowy ground tile
* <code style="color:darkgreen">GROUNDSPRITE_SNOW_2_4 <ref name="spritenames" /></code> half-snowy ground tile
* <code style="color:darkgreen">GROUNDSPRITE_SNOW_3_4 <ref name="spritenames" /></code> 3/4 snowy ground tile
* <code style="color:darkgreen">GROUNDSPRITE_SNOW_4_4 <ref name="spritenames" /></code> snowy ground tile
* <code style="color:darkgreen">GROUNDSPRITE_CONCRETE</code> concrete ground tile
* <code style="color:darkgreen">GROUNDSPRITE_WATER</code> flat water tile
* <code style="color:darkgreen">GROUNDSPRITE_CLEARED <ref name="spritenames" /></code> ground tile that has just been bulldozed (with brown colour)

<references />

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

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

===Recolouring===

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

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

===Display yes/no===

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

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

===Positioning===

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

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

===Example (advanced) Spritelayout===

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

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

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

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

1
]) {
company_land_layout;
}
</pre>

NML:Graphic files

2014-07-18T08:04:53Z

Planetmaker: update links to palette files

{{NMLNavNoSubpages}}

All graphic files must be in a format that can be loaded by the python imaging library and they must have a valid palette. You can chose either the default (DOS) palette (recommended as it contains a few more colours) or the legacy (windows) palette.

Palette files for several editors:

* [http://dev.openttdcoop.org/attachments/download/1741/ttd-newgrf-dos.gpl Default (DOS) palette for GIMP]
* [http://dev.openttdcoop.org/attachments/download/1738/ttd-newgrf-win.gpl Legacy (Windows) palette for GIMP]
* [http://dev.openttdcoop.org/attachments/download/1749/photoshop-ttd-dos.act Default (DOS) palette for Photoshop]
* [http://dev.openttdcoop.org/attachments/download/1746/pal_win_png.act Legacy (Windows) palette for Photoshop]
* (another collection of palette files on the [http://dev.openttdcoop.org/documents/1 #openttdcoop DevZone])

'''Note''': Windows versions of NML do NOT support graphics in the pcx format due to missiong support within the PIL.

NML:GRF

2014-06-24T15:52:52Z

Planetmaker: link to guidelines for choosing a grfid

{{NMLNavBlocksyntax}}

== GRF block ==

Syntax:

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

Mind: the items enclosed in [...] indicate optional lines: The [] itself are not part of the syntax.

Concerning the choice of the <code style="color:darkgreen">grfid</code>, see [[Action8#GRFID|these]] guidelines

== GRF parameters ==

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

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

Looking at the single entries:

<num>

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

type

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

name

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

desc

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

min_value

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

max_value

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

def_value

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

bit

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

names

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

== A simple example ==

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

Action0/Vehicles

2014-06-24T14:27:13Z

Planetmaker: loading speed better describes prop. 0x07

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

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

== Properties ==

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

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

== Description ==

=== Date of introduction ===

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

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

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

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

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

=== Reliability decay speed ===

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

=== Vehicle life ===

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

=== Model life ===

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

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

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

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

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

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

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

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

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

=== Climate availability ===

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

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

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

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

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

=== Loading speed ===
This is the amount of cargo transferred per unit of time if using gradualloading. The default is 5 for trains and road vehicles, 10 for ships and 20 for aircraft. This amount of cargo is loaded to or unloaded from the vehicle every 40 ticks for trains, every 20 ticks for road vehicles and aircraft and every 10 ticks for ships.

If [[Action0/Vehicles/Trains#Miscellaneous_flags_.2827.29|Miscellaneous flag 5]] is set, the load amount specified in this property is scaled using [[Action0/Cargos#Capacity_multiplier_.281D.29|Cargo property 1D]].

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

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

Action8

2014-06-23T22:49:01Z

Planetmaker: /* Used ranges */ FIRS & Co need fewer IDs

==Introduction==

Define GRFID, Name and Description

There are many new graphic sets available to TTD players. Of course, we need to make sure that we never get sets mixed up. To make sure this will never happen you can set an ID. Another useful feature of Action 8 is the ability to include useful information into the final .grf file. Here, we explain how Action 8 works.

== Syntax ==

Like all other pseudo-sprites, Action 8 consists of hexadecimal bits. There is no limitation in the total amount of hexadecimal bits you can use in Action 8. One term does have a limit though. Let's give an example of what an Action 8 line looks like:

<pre><sprite-number> * <length> 08 <version> <grf-id> <name> <description></pre>

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
|-
|08||B||Action 08
|-
|<version>||B||GRF version
|-
|<grf-id>||4*B||A unique ID for your .grf file
|-
|<name>||S||A short text containing the name of this set
|-
|<description>||S||A longer description of this set
|}

== Descriptions ==

=== Sprite-number ===

The number of this sprite.

Action 8 has to be one of the first pseudosprites in the .NFO file. It is however valid to have other actions before it, except those that define new sprites or vehicle (etc.) properties.

Actions 6, 7, 9, B, C, D (except [[GRFResourceManagement|resource management]] sprites), 10 and 14 are valid before an action 8.

=== Length ===

The total number of bytes in Action 8.

=== GRF Version ===

This should be the graphics version that your file is written for. This is the version of the [[Version_numbers#GRF_version|GRF format]], not the [[Version_numbers#Version_of_a_specific_NewGRF|version of your GRF]]!
It is also not the "[[Version_numbers#NFO_version|NFO version]]" you put at the top of ".nfo" files to announce the used syntax for GRFCodec.

Valid values are:

{| |-
!'''Value'''!!'''Compatibility'''!!'''[[Version_numbers#TTDPatch_version|TTDPatch version]]'''!!'''[[Version_numbers#OpenTTD_version|OpenTTD support]]'''
|-
|08||02..08|| - || {{ottd|1.2|r23159}}
|-
|07||02..07||2.5 beta 1 or higher|| {{ottd|0.6}}
|-
|06||02..06||2.0.1 alpha 13 or higher|| {{ottd|0.6}}
|-
|05||02..05||2.0r1 Stable TTDPatch + TTDPatch 2.0.1 alphas up to 12|| {{ottd|0.6}}
|-
|04||02..04||2.0 Stable TTDPatch||{{ottd|0.6}}
|-
|01||00..01||1.9.1 alpha 28 or higher||{{ottd|no}}
|-
|00||00||1.9.1 alphas up to 27||{{ottd|no}}
|}

Entries for 00 and 01 are included only for completeness, and to aid with updating existing graphics. They should not be used with new graphics, because they will be incompatible with current TTDPatch and OpenTTD versions. OpenTTD 1.1.0 and later will disable NewGRFs with non-supported GRF versions.

Make sure to set a version number no lower than the minimum version that supports all features which are used by your file.

The compatibility column means how low a version number is supported by the given TTDPatch version, e.g. TTDPatch 2.0r1 supports graphics files with any version from 02 to 05, but not for example 01 or 06.

Version 07 and 08 introduce a few minor semantic changes to some graphics features, i.e. the file will behave slightly differently depending on whether it's declared as version 06, 07 or 08. These changes are described in more detail in the pages for the features they affect.

=== GRFID ===

This is a series of 4 bytes. It's a convention to
* use the first '''three bytes''' for the creator's '''initials''' in ASCII code, e.g. 54 57 48 for "TWH".
* The last (fourth) byte typically identies which of the author's sets this is. See the next subsection for grfID ranges that are already in use.
* Version numbers for NewGRFs are communicated via preceeding [[Action14]].

In principle, you are free what to use for the GRFID as long as you are sure it is unique, but generally it is best to follow the above guidelines. See the last subsection for locations where to find already used GRFIDs.

Note that GRFIDs starting with FF (i.e. the first byte is FF, such as in FF123456) are reserved for internal purposes and should not be used by regular .grf files. These GRFs can't be disabled; TTDPatch displays them with a blue flag in the GRF Status Window.

The extra newgrf file, part of OpenTTD base sets, have to have a GRFID starting with FF "OT".
See the table below:

{|
!GRFID!!purposes
|-
|00 00 00 00||n/a
|-
|00 00 00 01 .. FE FF FF FF||normal NewGRFs
|-
|FF 00 00 00 .. FF FF FF FF||reserved
|-
|FF "OT" 00 .. FF "OT" FF||extra base GRFs
|-
|FF "OT" 01|| OpenGFX
|-
|FF "OTD"|| OpenTTD (extra) base graphics: openttdd.grf (OpenTTD 0.6 - 1.0)
|-
|FF "OTT"|| OpenTTD (extra) base graphics: openttd.grf (OpenTTD >= 1.1)
|-
|FF "OTW"|| OpenTTD (extra) base graphics: openttdw.grf (OpenTTD 0.6 - 1.0)
|-
|FF FF FF FF|| TTDPatch (extra) base graphics
|}

==== Used ranges ====

The following table shows ranges of GRFIDs that are in use by several authors of NewGRFs. People choosing new GRFIDs are asked to not use a GRFID that falls within the ranges of one of the following. This list is in no way exhaustive; if you want to claim your own range, please update the table. For legacy reasons there are some broader ranges of GRFIDs reserved by some people. When you want to reserve a broader range than a variation in only the last byte, think twice and consider how long it will take you to write 255 sensible completely different NewGRFs (as the version of a single grf is encoded in the action14, thus a new ID will even hurt and kill your backward compatibility with older versions).

{|
!Range (hex)!!ASCII!!Usage
|-
|41 4E XX XX||A N _ _||FISH ship set
|-
|41 50 XX XX||A P _ _||HEQS (Heavy Equipment Set)
|-
|43 41 XX XX||C A _ _||OzTrans; older versions of Canadian and some North American sets
|-
|43 48 XX XX||C H _ _||CHIPS Has Improved Players' Stations
|-
|44 44 XX XX||D D _ _||Pikkabird; UKRS, NARS, Av8
|-
|4A 56 XX XX||J V _ _||juzza1; Various Finnish sets
|-
|4F 47 2B XX||O G + _||OpenGFX+ sets
|-
|4D 65 XX XX||M e _ _||George; ECS, Long vehicles
|-
|6D 62 XX XX||m b _ _||Michael Blunck; DBsetXL, NewStations, MariCo
|-
|97 87 XX XX||? ? _ _||OzTrans; newer versions of Canadian sets
|-
|F1 25 00 XX||? ? ? _||FIRS Industry Replacement Set
|-
|FB FB XX XX||? ? _ _||FooBar; Dutch sets, Transrapid/metro tracks
|-
|FF XX XX XX||? _ _ _||System reserved
|}

==== Used GRFIDs ====

There are several places that have/show lists of GRFIDs that are definitely in use by someone. Absence of a GRFID in any of these lists is not proof that it is not used though.

* [http://bananas.openttd.org/en/newgrf/] Bananas shows the GRFIDs of all currently active NewGRFs that are distributed by the system
* [http://grfcrawler.tt-forums.net/index.php?do=search&mode=advanced] GRFCrawler allows one to search on GRFIDs of NewGRFs in its system
* [http://devs.openttd.org/~rubidium/newgrf.html] OpenTTD generates a list that shows all NewGRFs that were ever used in a multiplayer game

=== Name ===
This short field should contain the name of the set. See [[GRFActionsDetailed#Strings|GRFActionsDetailed]] for instructions to generate the necessary byte codes, and for restrictions on what characters you may use.
The name must be short because it should fit on one line of the [[GRFStatusWindow|GRF Status window]].

=== Description ===
This is a longer description of the set. Typically it contains the name of the author and a copyright notice or other attribution. See [[GRFActionsDetailed#Strings|GRFActionsDetailed]] for instructions to generate the necessary byte codes, and for restrictions on what characters you may use.
The description may be quite long, but should be short enough to fit in the description part of the [[GRFStatusWindow|GRF Status window]], or a part of it may be cut off.

== Example ==

Below is an example of what a real Action 8 pseudo-sprite could look like.

1 * 43 '''08''' 07 "TW" 01 06 "Tutorial Example" 00 "Changes nothing. Author: A kind person" 00

Let's clarify it bit by bit. In order to understand what the bits say you could use a hexadecimal editor.

{| |-
!'''Byte'''!!'''Meaning'''
|-
|1||<sprite-number>
|-
|43||<length> of the action in bytes; start counting at 08 (<action>)
|-
|08||<action>: sets this pseudo-sprite to function as action 8
|-
|07||<version>: GRF format version 7 (this is the version of the used GRF format, not of your GRF)
|-
|54 57 01 06||<-grf-id>: ASCII code for TW, then the numbers 1 and 6 to indicate version 6 of TW's first set
|-
|"Tutorial..." 00||<name>: Name of the NewGRF
|-
|"Changes..." 00||<description>: Description of the NewGRF
|}

Action8

2014-06-23T22:44:34Z

Planetmaker: /* GRFID */ reword the three-letter initials rule

==Introduction==

Define GRFID, Name and Description

There are many new graphic sets available to TTD players. Of course, we need to make sure that we never get sets mixed up. To make sure this will never happen you can set an ID. Another useful feature of Action 8 is the ability to include useful information into the final .grf file. Here, we explain how Action 8 works.

== Syntax ==

Like all other pseudo-sprites, Action 8 consists of hexadecimal bits. There is no limitation in the total amount of hexadecimal bits you can use in Action 8. One term does have a limit though. Let's give an example of what an Action 8 line looks like:

<pre><sprite-number> * <length> 08 <version> <grf-id> <name> <description></pre>

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
|-
|08||B||Action 08
|-
|<version>||B||GRF version
|-
|<grf-id>||4*B||A unique ID for your .grf file
|-
|<name>||S||A short text containing the name of this set
|-
|<description>||S||A longer description of this set
|}

== Descriptions ==

=== Sprite-number ===

The number of this sprite.

Action 8 has to be one of the first pseudosprites in the .NFO file. It is however valid to have other actions before it, except those that define new sprites or vehicle (etc.) properties.

Actions 6, 7, 9, B, C, D (except [[GRFResourceManagement|resource management]] sprites), 10 and 14 are valid before an action 8.

=== Length ===

The total number of bytes in Action 8.

=== GRF Version ===

This should be the graphics version that your file is written for. This is the version of the [[Version_numbers#GRF_version|GRF format]], not the [[Version_numbers#Version_of_a_specific_NewGRF|version of your GRF]]!
It is also not the "[[Version_numbers#NFO_version|NFO version]]" you put at the top of ".nfo" files to announce the used syntax for GRFCodec.

Valid values are:

{| |-
!'''Value'''!!'''Compatibility'''!!'''[[Version_numbers#TTDPatch_version|TTDPatch version]]'''!!'''[[Version_numbers#OpenTTD_version|OpenTTD support]]'''
|-
|08||02..08|| - || {{ottd|1.2|r23159}}
|-
|07||02..07||2.5 beta 1 or higher|| {{ottd|0.6}}
|-
|06||02..06||2.0.1 alpha 13 or higher|| {{ottd|0.6}}
|-
|05||02..05||2.0r1 Stable TTDPatch + TTDPatch 2.0.1 alphas up to 12|| {{ottd|0.6}}
|-
|04||02..04||2.0 Stable TTDPatch||{{ottd|0.6}}
|-
|01||00..01||1.9.1 alpha 28 or higher||{{ottd|no}}
|-
|00||00||1.9.1 alphas up to 27||{{ottd|no}}
|}

Entries for 00 and 01 are included only for completeness, and to aid with updating existing graphics. They should not be used with new graphics, because they will be incompatible with current TTDPatch and OpenTTD versions. OpenTTD 1.1.0 and later will disable NewGRFs with non-supported GRF versions.

Make sure to set a version number no lower than the minimum version that supports all features which are used by your file.

The compatibility column means how low a version number is supported by the given TTDPatch version, e.g. TTDPatch 2.0r1 supports graphics files with any version from 02 to 05, but not for example 01 or 06.

Version 07 and 08 introduce a few minor semantic changes to some graphics features, i.e. the file will behave slightly differently depending on whether it's declared as version 06, 07 or 08. These changes are described in more detail in the pages for the features they affect.

=== GRFID ===

This is a series of 4 bytes. It's a convention to
* use the first '''three bytes''' for the creator's '''initials''' in ASCII code, e.g. 54 57 48 for "TWH".
* The last (fourth) byte typically identies which of the author's sets this is. See the next subsection for grfID ranges that are already in use.
* Version numbers for NewGRFs are communicated via preceeding [[Action14]].

In principle, you are free what to use for the GRFID as long as you are sure it is unique, but generally it is best to follow the above guidelines. See the last subsection for locations where to find already used GRFIDs.

Note that GRFIDs starting with FF (i.e. the first byte is FF, such as in FF123456) are reserved for internal purposes and should not be used by regular .grf files. These GRFs can't be disabled; TTDPatch displays them with a blue flag in the GRF Status Window.

The extra newgrf file, part of OpenTTD base sets, have to have a GRFID starting with FF "OT".
See the table below:

{|
!GRFID!!purposes
|-
|00 00 00 00||n/a
|-
|00 00 00 01 .. FE FF FF FF||normal NewGRFs
|-
|FF 00 00 00 .. FF FF FF FF||reserved
|-
|FF "OT" 00 .. FF "OT" FF||extra base GRFs
|-
|FF "OT" 01|| OpenGFX
|-
|FF "OTD"|| OpenTTD (extra) base graphics: openttdd.grf (OpenTTD 0.6 - 1.0)
|-
|FF "OTT"|| OpenTTD (extra) base graphics: openttd.grf (OpenTTD >= 1.1)
|-
|FF "OTW"|| OpenTTD (extra) base graphics: openttdw.grf (OpenTTD 0.6 - 1.0)
|-
|FF FF FF FF|| TTDPatch (extra) base graphics
|}

==== Used ranges ====

The following table shows ranges of GRFIDs that are in use by several authors of NewGRFs. People choosing new GRFIDs are asked to not use a GRFID that falls within the ranges of one of the following. This list is in no way exhaustive; if you want to claim your own range, please update the table. For legacy reasons there are some broader ranges of GRFIDs reserved by some people. When you want to reserve a broader range than a variation in only the last byte, think twice and consider how long it will take you to write 255 sensible completely different NewGRFs (as the version of a single grf is encoded in the action14, thus a new ID will even hurt and kill your backward compatibility with older versions).

{|
!Range (hex)!!ASCII!!Usage
|-
|41 4E XX XX||A N _ _||FISH ship set
|-
|41 50 XX XX||A P _ _||HEQS (Heavy Equipment Set)
|-
|43 41 XX XX||C A _ _||OzTrans; older versions of Canadian and some North American sets
|-
|43 48 XX XX||C H _ _||CHIPS Has Improved Players' Stations
|-
|44 44 XX XX||D D _ _||Pikkabird; UKRS, NARS, Av8
|-
|4A 56 XX XX||J V _ _||juzza1; Various Finnish sets
|-
|4F 47 2B XX||O G + _||OpenGFX+ sets
|-
|4D 65 XX XX||M e _ _||George; ECS, Long vehicles
|-
|6D 62 XX XX||m b _ _||Michael Blunck; DBsetXL, NewStations, MariCo
|-
|97 87 XX XX||? ? _ _||OzTrans; newer versions of Canadian sets
|-
|F1 25 XX XX||? ? _ _||FIRS Industry Replacement Set
|-
|FB FB XX XX||? ? _ _||FooBar; Dutch sets, Transrapid/metro tracks
|-
|FF XX XX XX||? _ _ _||System reserved
|}

==== Used GRFIDs ====

There are several places that have/show lists of GRFIDs that are definitely in use by someone. Absence of a GRFID in any of these lists is not proof that it is not used though.

* [http://bananas.openttd.org/en/newgrf/] Bananas shows the GRFIDs of all currently active NewGRFs that are distributed by the system
* [http://grfcrawler.tt-forums.net/index.php?do=search&mode=advanced] GRFCrawler allows one to search on GRFIDs of NewGRFs in its system
* [http://devs.openttd.org/~rubidium/newgrf.html] OpenTTD generates a list that shows all NewGRFs that were ever used in a multiplayer game

=== Name ===
This short field should contain the name of the set. See [[GRFActionsDetailed#Strings|GRFActionsDetailed]] for instructions to generate the necessary byte codes, and for restrictions on what characters you may use.
The name must be short because it should fit on one line of the [[GRFStatusWindow|GRF Status window]].

=== Description ===
This is a longer description of the set. Typically it contains the name of the author and a copyright notice or other attribution. See [[GRFActionsDetailed#Strings|GRFActionsDetailed]] for instructions to generate the necessary byte codes, and for restrictions on what characters you may use.
The description may be quite long, but should be short enough to fit in the description part of the [[GRFStatusWindow|GRF Status window]], or a part of it may be cut off.

== Example ==

Below is an example of what a real Action 8 pseudo-sprite could look like.

1 * 43 '''08''' 07 "TW" 01 06 "Tutorial Example" 00 "Changes nothing. Author: A kind person" 00

Let's clarify it bit by bit. In order to understand what the bits say you could use a hexadecimal editor.

{| |-
!'''Byte'''!!'''Meaning'''
|-
|1||<sprite-number>
|-
|43||<length> of the action in bytes; start counting at 08 (<action>)
|-
|08||<action>: sets this pseudo-sprite to function as action 8
|-
|07||<version>: GRF format version 7 (this is the version of the used GRF format, not of your GRF)
|-
|54 57 01 06||<-grf-id>: ASCII code for TW, then the numbers 1 and 6 to indicate version 6 of TW's first set
|-
|"Tutorial..." 00||<name>: Name of the NewGRF
|-
|"Changes..." 00||<description>: Description of the NewGRF
|}

Action8

2014-06-23T18:43:39Z

Planetmaker: /* GRFID */ there's no point anymore in a version byte

==Introduction==

Define GRFID, Name and Description

There are many new graphic sets available to TTD players. Of course, we need to make sure that we never get sets mixed up. To make sure this will never happen you can set an ID. Another useful feature of Action 8 is the ability to include useful information into the final .grf file. Here, we explain how Action 8 works.

== Syntax ==

Like all other pseudo-sprites, Action 8 consists of hexadecimal bits. There is no limitation in the total amount of hexadecimal bits you can use in Action 8. One term does have a limit though. Let's give an example of what an Action 8 line looks like:

<pre><sprite-number> * <length> 08 <version> <grf-id> <name> <description></pre>

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
|-
|08||B||Action 08
|-
|<version>||B||GRF version
|-
|<grf-id>||4*B||A unique ID for your .grf file
|-
|<name>||S||A short text containing the name of this set
|-
|<description>||S||A longer description of this set
|}

== Descriptions ==

=== Sprite-number ===

The number of this sprite.

Action 8 has to be one of the first pseudosprites in the .NFO file. It is however valid to have other actions before it, except those that define new sprites or vehicle (etc.) properties.

Actions 6, 7, 9, B, C, D (except [[GRFResourceManagement|resource management]] sprites), 10 and 14 are valid before an action 8.

=== Length ===

The total number of bytes in Action 8.

=== GRF Version ===

This should be the graphics version that your file is written for. This is the version of the [[Version_numbers#GRF_version|GRF format]], not the [[Version_numbers#Version_of_a_specific_NewGRF|version of your GRF]]!
It is also not the "[[Version_numbers#NFO_version|NFO version]]" you put at the top of ".nfo" files to announce the used syntax for GRFCodec.

Valid values are:

{| |-
!'''Value'''!!'''Compatibility'''!!'''[[Version_numbers#TTDPatch_version|TTDPatch version]]'''!!'''[[Version_numbers#OpenTTD_version|OpenTTD support]]'''
|-
|08||02..08|| - || {{ottd|1.2|r23159}}
|-
|07||02..07||2.5 beta 1 or higher|| {{ottd|0.6}}
|-
|06||02..06||2.0.1 alpha 13 or higher|| {{ottd|0.6}}
|-
|05||02..05||2.0r1 Stable TTDPatch + TTDPatch 2.0.1 alphas up to 12|| {{ottd|0.6}}
|-
|04||02..04||2.0 Stable TTDPatch||{{ottd|0.6}}
|-
|01||00..01||1.9.1 alpha 28 or higher||{{ottd|no}}
|-
|00||00||1.9.1 alphas up to 27||{{ottd|no}}
|}

Entries for 00 and 01 are included only for completeness, and to aid with updating existing graphics. They should not be used with new graphics, because they will be incompatible with current TTDPatch and OpenTTD versions. OpenTTD 1.1.0 and later will disable NewGRFs with non-supported GRF versions.

Make sure to set a version number no lower than the minimum version that supports all features which are used by your file.

The compatibility column means how low a version number is supported by the given TTDPatch version, e.g. TTDPatch 2.0r1 supports graphics files with any version from 02 to 05, but not for example 01 or 06.

Version 07 and 08 introduce a few minor semantic changes to some graphics features, i.e. the file will behave slightly differently depending on whether it's declared as version 06, 07 or 08. These changes are described in more detail in the pages for the features they affect.

=== GRFID ===

This is a series of 4 bytes. It's a convention to use the first three bytes for the creator's initials in ASCII code, e.g. 54 57 48 for "TWH". The last byte typically identies which of the author's sets this is. See the next subsection for grfID ranges that are already in use. Version numbers for NewGRFs are communicated via preceeding [[Action14]].

In principle, you are free what to use for the GRFID as long as you are sure it is unique, but generally it is best to follow the above guidelines. See the last subsection for locations where to find already used GRFIDs.

Note that GRFIDs starting with FF (i.e. the first byte is FF, such as in FF123456) are reserved for internal purposes and should not be used by regular .grf files. These GRFs can't be disabled; TTDPatch displays them with a blue flag in the GRF Status Window.

The extra newgrf file, part of OpenTTD base sets, have to have a GRFID starting with FF "OT".
See the table below:

{|
!GRFID!!purposes
|-
|00 00 00 00||n/a
|-
|00 00 00 01 .. FE FF FF FF||normal NewGRFs
|-
|FF 00 00 00 .. FF FF FF FF||reserved
|-
|FF "OT" 00 .. FF "OT" FF||extra base GRFs
|-
|FF "OT" 01|| OpenGFX
|-
|FF "OTD"|| OpenTTD (extra) base graphics: openttdd.grf (OpenTTD 0.6 - 1.0)
|-
|FF "OTT"|| OpenTTD (extra) base graphics: openttd.grf (OpenTTD >= 1.1)
|-
|FF "OTW"|| OpenTTD (extra) base graphics: openttdw.grf (OpenTTD 0.6 - 1.0)
|-
|FF FF FF FF|| TTDPatch (extra) base graphics
|}

==== Used ranges ====

The following table shows ranges of GRFIDs that are in use by several authors of NewGRFs. People choosing new GRFIDs are asked to not use a GRFID that falls within the ranges of one of the following. This list is in no way exhaustive; if you want to claim your own range, please update the table. For legacy reasons there are some broader ranges of GRFIDs reserved by some people, but when you want to reserve a broader range than a variation in only the last byte, consider how long it will take you to write 255 sensible completely different NewGRFs.

{|
!Range (hex)!!ASCII!!Usage
|-
|43 41 XX XX||C A _ _||OzTrans; older versions of Canadian and some North American sets
|-
|44 44 XX XX||D D _ _||Pikkabird; UKRS, NARS, Av8
|-
|4A 56 XX XX||J V _ _||juzza1; Various Finnish sets
|-
|4F 47 2B XX||O G + _||OpenGFX+ sets
|-
|4D 65 XX XX||M e _ _||George; ECS, Long vehicles
|-
|6D 62 XX XX||m b _ _||Michael Blunck; DBsetXL, NewStations, MariCo
|-
|97 87 XX XX||? ? _ _||OzTrans; newer versions of Canadian sets
|-
|F1 25 XX XX||? ? _ _||FIRS Industry Replacement Set
|-
|FB FB XX XX||? ? _ _||FooBar; Dutch sets, Transrapid/metro tracks
|-
|FF XX XX XX||? _ _ _||System reserved
|}

==== Used GRFIDs ====

There are several places that have/show lists of GRFIDs that are definitely in use by someone. Absence of a GRFID in any of these lists is not proof that it is not used though.

* [http://bananas.openttd.org/en/newgrf/] Bananas shows the GRFIDs of all currently active NewGRFs that are distributed by the system
* [http://grfcrawler.tt-forums.net/index.php?do=search&mode=advanced] GRFCrawler allows one to search on GRFIDs of NewGRFs in its system
* [http://devs.openttd.org/~rubidium/newgrf.html] OpenTTD generates a list that shows all NewGRFs that were ever used in a multiplayer game

=== Name ===
This short field should contain the name of the set. See [[GRFActionsDetailed#Strings|GRFActionsDetailed]] for instructions to generate the necessary byte codes, and for restrictions on what characters you may use.
The name must be short because it should fit on one line of the [[GRFStatusWindow|GRF Status window]].

=== Description ===
This is a longer description of the set. Typically it contains the name of the author and a copyright notice or other attribution. See [[GRFActionsDetailed#Strings|GRFActionsDetailed]] for instructions to generate the necessary byte codes, and for restrictions on what characters you may use.
The description may be quite long, but should be short enough to fit in the description part of the [[GRFStatusWindow|GRF Status window]], or a part of it may be cut off.

== Example ==

Below is an example of what a real Action 8 pseudo-sprite could look like.

1 * 43 '''08''' 07 "TW" 01 06 "Tutorial Example" 00 "Changes nothing. Author: A kind person" 00

Let's clarify it bit by bit. In order to understand what the bits say you could use a hexadecimal editor.

{| |-
!'''Byte'''!!'''Meaning'''
|-
|1||<sprite-number>
|-
|43||<length> of the action in bytes; start counting at 08 (<action>)
|-
|08||<action>: sets this pseudo-sprite to function as action 8
|-
|07||<version>: GRF format version 7 (this is the version of the used GRF format, not of your GRF)
|-
|54 57 01 06||<-grf-id>: ASCII code for TW, then the numbers 1 and 6 to indicate version 6 of TW's first set
|-
|"Tutorial..." 00||<name>: Name of the NewGRF
|-
|"Changes..." 00||<description>: Description of the NewGRF
|}

NML:Getting started

2014-06-20T17:05:30Z

Planetmaker: /* Linux */

{{NMLNavNoSubpages}}

== What is NML? ==
NML is a a python-based compiler, capable to compile NML files (along with their associated language, sound and graphic files) into grf and / or nfo files.

== Installation ==
=== pip ===
If you are familiar with python and pip then you can just use
pip install nml
This will install the required dependancies. Note that you may need administrator privileges for this to work.

=== Windows ===
Windows users can install the [http://bundles.openttdcoop.org/nml/nightlies/LATEST/ windows binary] which contains a binary which bundles all required libraries.

=== Linux ===
Users on other OS need to install them separately, best by means of their packet manager. In order to work, the following items are required:

* '''python'''
** any version from 2.6 through 2.7 will do, but not 3.x (NML 0.3.x or older)
** python 3.2 or newer (nightly builds or NML 0.4.0 or newer)
** downloadable from from http://www.python.org/)
** Advise for windows users: apparently you can prevent a lot of problems by installing the 32bit version of python, even if you have a 64bit windows installation. Installing PIL might be troublesome if you do install the 64bit version of python.
* '''python image library'''
** downloadable from https://pypi.python.org/pypi/Pillow/
* '''ply'''
** downloadable from http://www.dabeaz.com/ply/
* '''NML itself'''
** the latest (nightly) build can be downloaded from http://bundles.openttdcoop.org/nml/push/LATEST/

If you don't install these with the packet manager of your choice (or there is none like on windows and you don't use the pre-compiled binary file), you should install these libraries as well as NML itself using <code style="color:darkgreen">python setup.py install</code> from your command prompt.

=== OSX ===
OS X users have two choices: install the dependencies manually as described in the Linux section above, for use with the python version that ships with OS X. Or install everything from macports, including a new python version (using macports eases upgrading). However using macports to install the dependencies for the bundled system python is likely to fail.

=== Installing manually (any system) ===
We assume that you have a python setup (2.6 ... 2.7) where the distutils are available so that setup.py can be executed. You'll additionally need a gcc compiler in your path. On linux it is strongly recommended to use your package manager to install these packages.

==== Install PLY ====
This is easy. Get the library from the link as mentioned above.
Install it from the unpacked PLY directory via
sudo python setup.py install

==== Install the Python Imaging Library (PIL) ====
Get the library from the above mentioned link (the source kit for PIL 1.1.7). From the PIL source directory, test the setup for all available dependencies:
python setup.py build_ext -i
You should get an output like which concludes with a summary of the available dependencies:
PIL 1.1.7 SETUP SUMMARY
--------------------------------------------------------------------
--- TKINTER support available
--- JPEG support available
--- ZLIB (PNG/ZIP) support available
--- FREETYPE2 support available
--- LITTLECMS support available
--------------------------------------------------------------------
If you're missing zlib or jpeg support, install those libraries, too.

If that build shows everything available, test the setup:
python selftest.py
A successful selftest will result in
--------------------------------------------------------------------
PIL 1.1.7 TEST SUMMARY
--------------------------------------------------------------------
Python modules loaded from ./PIL
Binary modules loaded from ./PIL
--------------------------------------------------------------------
--- PIL CORE support ok
--- TKINTER support ok
--- JPEG support ok
--- ZLIB (PNG/ZIP) support ok
--- FREETYPE2 support ok
--- LITTLECMS support ok
--------------------------------------------------------------------
Running selftest:
--- 57 tests passed.
If all is successful, finally install the library:
sudo python setup.py install

==== Install NML ====
Now, that you have installed ply and pil, then you can install NML from the unpacked nml directory:
sudo python setup.py install

== Testing the installation ==
To verify that everything is installed, enter <code style="color:darkgreen">nmlc --version</code> in your command line. This should output the version of NML as well as the version of the installed libraries.

Examples for small NML "projects" are found in the <code style="color:darkgreen">examples</code> and <code style="color:darkgreen">regression</code> folder of NML. Generally it's assumed that the language files are in a separate language folder <code style="color:darkgreen">lang</code>, thus a simple project may look like this:

mynewgrf.nml
graphics.png
funny_sound.wav

lang/english.lng

The compiler itself <code style="color:darkgreen">nmlc</code> is a command line tool and can take a number of parameters, at least the nml filename which it shall process, e.g. <code style="color:darkgreen">nmlc mynewgrf.nml</code> will compile your nml file into the grf-file <code style="color:darkgreen">mynewgrf.grf</code>.

The full syntax is:

Usage: nmlc [options] <filename>
Where <filename> is the nml file to parse

Options:
--version show program's version number and exit
-h, --help show this help message and exit
-d, --debug write the AST to stdout
-s, --stack Dump stack when an error occurs
--grf=<file> write the resulting grf to <file>
--md5=<file> Write an md5sum of the resulting grf to <file>
--nfo=<file> write nfo output to <file>
-M output a rule suitable for make describing the
graphics dependencies of the main grf file (requires
input file or --grf)
--MF=<file> When used with -M, specifies a file to write the
dependencies to
--MT=<file> target of the rule emitted by dependency generation
(requires -M)
-c crop extraneous transparent blue from real sprites
-u save uncompressed data in the grf file
--nml=<file> write optimized nml to <file>
-o <file>, --output=<file>
write output(nfo/grf) to <file>
-t <file>, --custom-tags=<file>
Load custom tags from <file> [default:
custom_tags.txt]
-l <dir>, --lang-dir=<dir>
Load language files from directory <dir> [default:
lang]
--default-lang=<file>
The default language is stored in <file> [default:
english.lng]
--start-sprite=<num> Set the first sprite number to write (do not use
except when you output nfo that you want to include in
other files)
-p <palette>, --palette=<palette>
Force nml to use the palette <pal> [default: ANY].
Valid values are 'DEFAULT', 'LEGACY', 'ANY'
--quiet Disable all warnings. Errors will be printed normally.
-n, --no-cache Disable caching of sprites in .cache[index] files,
which may reduce compilation time.

== Syntax highlighting ==
For a few editors there exist syntax highlighting rules, see the [http://dev.openttdcoop.org/projects/home/documents DevZone documents] for details.
There are rules for
* [http://dev.openttdcoop.org/documents/26 Geany]
* [http://dev.openttdcoop.org/documents/24 Notepad++]
* [http://dev.openttdcoop.org/documents/38 Kate]

NML:Changes 0.4

2014-06-20T17:03:37Z

Planetmaker: add changes based on using python3

NML:Main

2014-06-20T16:59:48Z

Planetmaker: Add changes page for NML 0.4

<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]]
{|
|[[NML:General|General]] || || [[NML:General#General variables|variables]] ||
|-
|[[NML:Vehicles|Vehicles]] || [[NML:Vehicles#Properties common to all vehicle types|common properties]] || [[NML:Vehicles#Vehicle variables|variables]] || [[NML:Vehicles#Vehicle callbacks|callbacks]]
|-
| || [[NML:Vehicles#Train properties|train properties]] || ||
|-
| || [[NML:Vehicles#Road vehicle properties|road vehicle properties]] || ||
|-
| || [[NML:Vehicles#Ship properties|ship properties]] || ||
|-
| || [[NML:Vehicles#Aircraft properties|aircraft properties]] || ||
|-
|[[NML:Stations|Stations]] || [[NML:Stations#Station properties|properties]] || [[NML:Stations#Station variables|variables]] || [[NML:Stations#Station callbacks|callbacks]]
|-
|[[NML:Canals|Canals]] || [[NML:Canals#Canal properties|properties]] || [[NML:Canals#Canal variables|variables]] || [[NML:Canals#Canal callbacks|callbacks]]
|-
|[[NML:Bridges|Bridges]] || [[NML:Bridges#Bridge properties|properties]] || [[NML:Bridges#Bridge variables|variables]] || [[NML:Bridges#Bridge callbacks|callbacks]]
|-
|[[NML:Towns|Towns]] || || ||
|-
|[[NML:Houses|Houses]] || [[NML:Houses#House properties|properties]] || [[NML:Houses#House variables|variables]] || [[NML:Houses#House callbacks|callbacks]]
|-
|[[NML:Industries|Industries]]|| || [[NML:Industries#Common variables|common variables]] ||
|-
| || [[NML:Industries#Industry properties|industry properties]] || [[NML:Industries#Industry variables|industry variables]] || [[NML:Industries#Industry callbacks|industry callbacks]]
|-
| || [[NML:Industries#Industry tile properties|tile properties]] || [[NML:Industries#Industry tile variables|tile variables]] || [[NML:Industries#Industry tile callbacks|tile callbacks]]
|-
|[[NML:Cargos|Cargos]] || [[NML:Cargos#Cargo properties|properties]] || [[NML:Cargos#Cargo variables|variables]] || [[NML:Cargos#Cargo callbacks|callbacks]]
|-
|[[NML:Airports|Airports]] || [[NML:Airports#Airport properties|properties]] || [[NML:Airports#Airport variables|variables]] || [[NML:Airports#Airport callbacks|callbacks]]
|-
| || [[NML:Airports#Airport tile properties|tile properties]] || [[NML:Airports#Airport tile variables|tile variables]] || [[NML:Airports#Airport tile callbacks|tile callbacks]]
|-
|[[NML:Objects|Objects]] || [[NML:Objects#Object properties|properties]] || [[NML:Objects#Object variables|variables]] || [[NML:Objects#Object callbacks|callbacks]]
|-
|[[NML:Railtypes|Railtypes]] || [[NML:Railtypes#Railtype properties|properties]] || [[NML:Railtypes#Railtype variables|variables]] || [[NML:Railtypes#Railtype callbacks|callbacks]]
|}
;[[NML: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:Snow line

2014-05-11T17:57:03Z

Planetmaker: snow%...

{{NMLNavBlocksyntax}}

The snowline is specified by a <code style="color:darkgreen">snowline</code> statement. See the example below:

<pre style="color:blue">
snowline (linear) {
day_of_year(2, 1): 2;
day_of_year(11, 1): 4;
177: 29;
day_of_year(10, 1): 50 snow%;
}
</pre>

It starts with the <code style="color:darkgreen">snowline</code> keyword followed by the mode. It contains a number of <code style="color:darkgreen"><day-of-the-year> : <height></code> pairs. These define the height of the snowline at that day in the year. The day of the year value is actually an integer from 1 up to and including 365, so you may also define a day as a number. The values can be any value between 0 and 255. 255 means 'no snow'; other values are scaled to the number of possible heightlevels of the map. Going in steps of 16 will mean that snowline makes large jumps if more heightlevels are used. If you use the unit 'snow%' then the values give the percentage of height levels not covered with snow and 0 snow% means snow everywhere and 100 snow% snow everywhere.

For the days not listed, the program computes a height. It can do that in two modes, namely in <code style="color:darkgreen">equal</code> mode and in <code style="color:darkgreen">linear</code> mode (last line of text in the example). In <code style="color:darkgreen">equal</code> mode, the height of the snow is the same as the day before, unless the day is listed in the <code style="color:darkgreen">snowline</code> statement. In <code style="color:darkgreen">linear</code> mode, the height of the snowline gets linearly interpolated between two heights specified in the statement. In both cases, note that days `wrap around' at the end of the year, to get the snow height of January 1st (if not listed in the statement), the last specified height of the year is used in the calculation.

NML:Snow line

2014-05-11T17:55:04Z

Planetmaker: and fix again.

{{NMLNavBlocksyntax}}

The snowline is specified by a <code style="color:darkgreen">snowline</code> statement. See the example below:

<pre style="color:blue">
snowline (linear) {
day_of_year(2, 1): 2;
day_of_year(11, 1): 4;
177: 29;
day_of_year(10, 1): 50 snow%;
}
</pre>

It starts with the <code style="color:darkgreen">snowline</code> keyword followed by the mode. It contains a number of <code style="color:darkgreen"><day-of-the-year> : <height></code> pairs. These define the height of the snowline at that day in the year. The day of the year value is actually an integer from 1 up to and including 365, so you may also define a day as a number. The values can be any value between 0 and 255. 255 means 'no snow'; other values are scaled to the number of possible heightlevels of the map. Going in steps of 16 will mean that snowline makes large jumps if more heightlevels are used. If you use the unit 'snow%' then the values give the percentage of height levels covered with snow and 0% means no snow at all.

For the days not listed, the program computes a height. It can do that in two modes, namely in <code style="color:darkgreen">equal</code> mode and in <code style="color:darkgreen">linear</code> mode (last line of text in the example). In <code style="color:darkgreen">equal</code> mode, the height of the snow is the same as the day before, unless the day is listed in the <code style="color:darkgreen">snowline</code> statement. In <code style="color:darkgreen">linear</code> mode, the height of the snowline gets linearly interpolated between two heights specified in the statement. In both cases, note that days `wrap around' at the end of the year, to get the snow height of January 1st (if not listed in the statement), the last specified height of the year is used in the calculation.

NML:Snow line

2014-05-11T17:51:44Z

Planetmaker: clarify documentation a bit

{{NMLNavBlocksyntax}}

The snowline is specified by a <code style="color:darkgreen">snowline</code> statement. See the example below:

<pre style="color:blue">
snowline (linear) {
day_of_year(2, 1): 2;
day_of_year(11, 1): 4;
177: 29;
day_of_year(10, 1): 50 snow%;
}
</pre>

It starts with the <code style="color:darkgreen">snowline</code> keyword followed by the mode. It contains a number of <code style="color:darkgreen"><day-of-the-year> : <height></code> pairs. These define the height of the snowline at that day in the year. The day of the year value is actually an integer from 1 up to and including 365, so you may also define a day as a number. Heights run from 0 to 255 in levels above sea level. Thus a value of 17 is already sufficient to remove all traces of snow from the game. And any value lower than 2 will cover the whole map in snow. If you use the unit 'snow%' then the values are scaled to the available height difference, thus to values between 0 and 17.

For the days not listed, the program computes a height. It can do that in two modes, namely in <code style="color:darkgreen">equal</code> mode and in <code style="color:darkgreen">linear</code> mode (last line of text in the example). In <code style="color:darkgreen">equal</code> mode, the height of the snow is the same as the day before, unless the day is listed in the <code style="color:darkgreen">snowline</code> statement. In <code style="color:darkgreen">linear</code> mode, the height of the snowline gets linearly interpolated between two heights specified in the statement. In both cases, note that days `wrap around' at the end of the year, to get the snow height of January 1st (if not listed in the statement), the last specified height of the year is used in the calculation.

NML:Getting started

2014-04-12T15:09:54Z

Planetmaker: Adjust python version requirements to 2.6+ and update command line options

{{NMLNavNoSubpages}}

== What is NML? ==
NML is a a python-based compiler, capable to compile NML files (along with their associated language, sound and graphic files) into grf and / or nfo files.

== Installation ==
=== pip ===
If you are familiar with python and pip then you can just use
pip install nml
This will install the required dependancies. Note that you may need administrator privileges for this to work.

=== Windows ===
Windows users can install the [http://bundles.openttdcoop.org/nml/nightlies/LATEST/ windows binary] which contains a binary which bundles all required libraries.

=== Linux ===
Users on other OS need to install them separately, best by means of their packet manager. In order to work, the following items are required:

* '''python'''
** any version from 2.6 through 2.7 will do, but not 3.x
** downloadable from from http://www.python.org/)
** Advise for windows users: apparently you can prevent a lot of problems by installing the 32bit version of python, even if you have a 64bit windows installation. Installing PIL might be troublesome if you do install the 64bit version of python.
* '''python image library'''
** downloadable from https://pypi.python.org/pypi/Pillow/
* '''ply'''
** downloadable from http://www.dabeaz.com/ply/
* '''NML itself'''
** the latest (nightly) build can be downloaded from http://bundles.openttdcoop.org/nml/push/LATEST/

If you don't install these with the packet manager of your choice (or there is none like on windows and you don't use the pre-compiled binary file), you should install these libraries as well as NML itself using <code style="color:darkgreen">python setup.py install</code> from your command prompt.

=== OSX ===
OS X users have two choices: install the dependencies manually as described in the Linux section above, for use with the python version that ships with OS X. Or install everything from macports, including a new python version (using macports eases upgrading). However using macports to install the dependencies for the bundled system python is likely to fail.

=== Installing manually (any system) ===
We assume that you have a python setup (2.6 ... 2.7) where the distutils are available so that setup.py can be executed. You'll additionally need a gcc compiler in your path. On linux it is strongly recommended to use your package manager to install these packages.

==== Install PLY ====
This is easy. Get the library from the link as mentioned above.
Install it from the unpacked PLY directory via
sudo python setup.py install

==== Install the Python Imaging Library (PIL) ====
Get the library from the above mentioned link (the source kit for PIL 1.1.7). From the PIL source directory, test the setup for all available dependencies:
python setup.py build_ext -i
You should get an output like which concludes with a summary of the available dependencies:
PIL 1.1.7 SETUP SUMMARY
--------------------------------------------------------------------
--- TKINTER support available
--- JPEG support available
--- ZLIB (PNG/ZIP) support available
--- FREETYPE2 support available
--- LITTLECMS support available
--------------------------------------------------------------------
If you're missing zlib or jpeg support, install those libraries, too.

If that build shows everything available, test the setup:
python selftest.py
A successful selftest will result in
--------------------------------------------------------------------
PIL 1.1.7 TEST SUMMARY
--------------------------------------------------------------------
Python modules loaded from ./PIL
Binary modules loaded from ./PIL
--------------------------------------------------------------------
--- PIL CORE support ok
--- TKINTER support ok
--- JPEG support ok
--- ZLIB (PNG/ZIP) support ok
--- FREETYPE2 support ok
--- LITTLECMS support ok
--------------------------------------------------------------------
Running selftest:
--- 57 tests passed.
If all is successful, finally install the library:
sudo python setup.py install

==== Install NML ====
Now, that you have installed ply and pil, then you can install NML from the unpacked nml directory:
sudo python setup.py install

== Testing the installation ==
To verify that everything is installed, enter <code style="color:darkgreen">nmlc --version</code> in your command line. This should output the version of NML as well as the version of the installed libraries.

Examples for small NML "projects" are found in the <code style="color:darkgreen">examples</code> and <code style="color:darkgreen">regression</code> folder of NML. Generally it's assumed that the language files are in a separate language folder <code style="color:darkgreen">lang</code>, thus a simple project may look like this:

mynewgrf.nml
graphics.png
funny_sound.wav

lang/english.lng

The compiler itself <code style="color:darkgreen">nmlc</code> is a command line tool and can take a number of parameters, at least the nml filename which it shall process, e.g. <code style="color:darkgreen">nmlc mynewgrf.nml</code> will compile your nml file into the grf-file <code style="color:darkgreen">mynewgrf.grf</code>.

The full syntax is:

Usage: nmlc [options] <filename>
Where <filename> is the nml file to parse

Options:
--version show program's version number and exit
-h, --help show this help message and exit
-d, --debug write the AST to stdout
-s, --stack Dump stack when an error occurs
--grf=<file> write the resulting grf to <file>
--md5=<file> Write an md5sum of the resulting grf to <file>
--nfo=<file> write nfo output to <file>
-M output a rule suitable for make describing the
graphics dependencies of the main grf file (requires
input file or --grf)
--MF=<file> When used with -M, specifies a file to write the
dependencies to
--MT=<file> target of the rule emitted by dependency generation
(requires -M)
-c crop extraneous transparent blue from real sprites
-u save uncompressed data in the grf file
--nml=<file> write optimized nml to <file>
-o <file>, --output=<file>
write output(nfo/grf) to <file>
-t <file>, --custom-tags=<file>
Load custom tags from <file> [default:
custom_tags.txt]
-l <dir>, --lang-dir=<dir>
Load language files from directory <dir> [default:
lang]
--default-lang=<file>
The default language is stored in <file> [default:
english.lng]
--start-sprite=<num> Set the first sprite number to write (do not use
except when you output nfo that you want to include in
other files)
-p <palette>, --palette=<palette>
Force nml to use the palette <pal> [default: ANY].
Valid values are 'DEFAULT', 'LEGACY', 'ANY'
--quiet Disable all warnings. Errors will be printed normally.
-n, --no-cache Disable caching of sprites in .cache[index] files,
which may reduce compilation time.

== Syntax highlighting ==
For a few editors there exist syntax highlighting rules, see the [http://dev.openttdcoop.org/projects/home/documents DevZone documents] for details.
There are rules for
* [http://dev.openttdcoop.org/documents/26 Geany]
* [http://dev.openttdcoop.org/documents/24 Notepad++]
* [http://dev.openttdcoop.org/documents/38 Kate]

NML:Vehicles

2014-04-01T08:34:10Z

Planetmaker: /* Engine life cycle */

{{NMLNavPropVarCB}}
== Vehicle IDs ==
Picking an item ID requires keeping two cases in mind: OpenTTD with the engine pool enabled and OpenTTD with engine pool disabled / TTDPatch. The status of the engine pool may be checked with the global variable [[NML:General#General_variables|dynamic_engines]].

=== Engine pool enabled ===
With the engine pool enabled, each NewGRF has its own ID range, NewGRFs don't influence each other. IDs may freely be chosen between 0 and 65535. If the chosen ID belongs to an existing vehicle, this vehicle is overridden by your vehicle. If another NewGRF is already overriding that vehicle, a new vehicle will be allocated, but all the properties will be copied from the old vehicle. If you define an ID for which no original vehicle exists, a new (blank) vehicle is allocated.

This behaviour can be modified using an [[NML:Overriding_vehicles_in_other_NewGRFs|engine_override]], this allows changing the properties of vehicles defined in other NewGRFs instead of allocating a new vehicle.

=== TTDPatch / Engine pool disabled ===
Each new vehicle has to replace an existing vehicle. If multiple NewGRFs try to replace the same vehicle, the last NewGRF loaded 'wins'. [[VehicleIDs|This page]] contains a list of valid vehicle IDs for each vehicle type, look in the 'NML ID' column. Note that IDs are not bound to a specific sort of vehicle (e.g. monorail wagons) but to a feature (e.g. trains, road vehicles).

In general, you should take the following steps:
* If your NewGRF is intended as a complete replacement for the default vehicles, disable the relevant default vehicles using [[NML:Disable_items|disable_item]].
* Re-use IDs of existing vehicles as much as possible.
* If your NewGRF uses IDs outside of the normal range (for example, because you there are more vehicles than slots available), let your code check if dynamic_engies is enabled. If not, skip the vehicles outside the normal range (using an if-statement) and make sure that the remaining vehicles allow for reasonable gameplay. It is recommended to issue a warning to the user about this. Alternatively, it is also possible to disable your entire NewGRF. If you don't do this check and dynamic_engines is off, OpenTTD may disable your NewGRF with the somewhat cryptic message 'Attempt to use invalid ID', which will likely lead to bug reports about your NewGRF and/or your OpenTTD.

==Properties common to all vehicle types==

{| class="t"
! property
! value range
! available for<br />articulated<br />vehicle
! comment
|-
| <code style="color:green">name</code>
| (string)
| yes
| for example <code style="color:darkgreen">string(STR_NAME_HEREFORD_TRAM)</code>
|-
| <code style="color:green">climates_available</code>
| bitmask(CLIMATE_XXX, CLIMATE_YYY, ...)
| set to <code style="color:green">NO_CLIMATE</code>
|
;CLIMATE_TEMPERATE
;CLIMATE_ARCTIC
;CLIMATE_TROPICAL
;CLIMATE_TOYLAND
;NO_CLIMATE
:Vehicle is availble in no climate (e.g. for articulated parts)
;ALL_CLIMATES
:Vehicle is available irrespective of climate

To make a vehicle available in all climates except toyland you could use: <code style="color:green">ALL_CLIMATES & ~bitmask(CLIMATE_TOYLAND)</code>.
|-
| <code style="color:green">introduction_date</code>
| <code style="color:green">date</code>(yyyy,mm,dd)
| no
| Valid range for yyyy is 0 ... 5000000. In TTDPatch, dates after 2044 will be limited to 2044. Unless the engine is introduced within two years after game-start (always 1920 in TTDPatch), a random number of days between 0 and 511 will be added to this.
|-
| <code style="color:green">model_life</code>
| 0 ... 254 (years) or <code style="color:green">VEHICLE_NEVER_EXPIRES</code>
| no
|
Number of years a model is "supported" by the manufacturer, see [[#Engine life cycle|below]].
|-
| <code style="color:green">retire_early</code>
| -128 ... 127 (years)
| no
|
Retire the vehicle (make it unavailable in the purchase menu) this many years before reliability starts dropping, see [[#Engine life cycle|below]]. May be negative.
|-
| <code style="color:green">vehicle_life</code>
| 0 ... 255 (years)
| no
| Life length of an individual vehicle, before it is considered too old and in need of replacement.
|-
| <code style="color:green">reliability_decay</code>
| 0 ... 255
| no
| Default vehicles use 20. The higher the value the faster reliability decays, the more frequent service is needed. 0 means reliability never decreases if the vehicle is not too old
|-
| <code style="color:green">refittable_cargo_classes</code>
|
bit set of [[NML:Cargos#Cargo classes|cargo classes]]
| yes
| for example: <code style="color:darkgreen">bitmask(CC_BULK, CC_COVERED)</code>
|-
| <code style="color:green">non_refittable_cargo_classes</code>
|
bit set of [[NML:Cargos#Cargo classes|cargo classes]]
| yes
| for example: <code style="color:darkgreen">bitmask(CC_OVERSIZED, CC_SPECIAL)</code>
|-
| <code style="color:green">refittable_cargo_types</code>
| bit mask of entries into the cargo translation table
| yes
| As of NML 0.3, do not use this. Use cargo_[dis]allow_refit (see below) instead.
|-
| <code style="color:green">cargo_allow_refit</code>
| Array of cargo labels from the [[NML:Cargotable|cargotable]]
| Yes
| {{ottdp|1.2|no|ottdrev=r23291}} A list of cargo types to allow refitting to, irrespective of cargo classes. Example: <code style="color:darkgreen">[COAL, IORE]</code>
|-
| <code style="color:green">cargo_disallow_refit</code>
| Array of cargo labels from the [[NML:Cargotable|cargotable]]
| Yes
| {{ottdp|1.2|no|ottdrev=r23291}} A list of cargo types to disallow refitting to, irrespective of cargo classes. Example: <code style="color:darkgreen">[MAIL]</code>
|-
| <code style="color:green">loading_speed</code>
| 0 ... 255 (cargo units)
| yes
| Units of cargo loaded per time unit. Default vehicles use 5 for trains and road vehicles, 10 for ships and 20 for aircraft. This amount of cargo is loaded to or unloaded from the vehicle every 40 ticks for trains, every 20 ticks for road vehicles and aircraft and every 10 ticks for ships.
|-
| <code style="color:green">cost_factor</code>
| 0 ... 255
| Set to 0
| multiplier to the base purchase cost
|-
| <code style="color:green">running_cost_factor</code>
| 0 ... 255
| Set to 0
| multiplier to the base running costs
|-
| <code style="color:green">cargo_age_period</code>
| 0 ... 65535
| yes
|
{{ottd|1.2|r22713}} This property specifies after how many ticks cargo is aged. Default value is 185. 74 ticks is equal to 1 day.
|}

===Refittability===

To determine whether your vehicle can be refitted to a certain cargo, OpenTTD uses the following table

{| class="t"
! Cargo matches refittable_cargo_classes
! Cargo matches non_refittable_cargo_classes
! Cargo in cargo_allow_refit
! Cargo in cargo_disallow_refit
! Result
|-
| Yes
| No
| Doesn't matter
| No
| Refittable
|-
| No
| Doesn't matter
| No
| Doesn't matter
| Not refittable
|-
| Doesn't matter
| Doesn't matter
| Yes
| No
| Refittable
|-
| Doesn't matter
| Doesn't matter
| Doesn't matter
| Yes
| Not refittable
|}

For those that prefer boolean logic, the formula is as follows:

refittable = ((cargo classes in refittable_cargo_classes AND NOT cargo classes in non_refittable_cargo_classes) OR cargo in cargo_allow_refit) AND NOT (cargo in cargo_disallow_refit)

In general, you should use refittable_cargo_classes and non_refittable_cargo_classes to decide to which cargos your vehicle is refittable, and only then use cargo_allow_refit and cargo_disallow_refit to allow/disallow specific cargos.

===Engine life cycle===

The life cycle of a vehicle model consists of three phases, as outlined in the following table. When starting a new game, a random amount between 31 months and 17 years is added to the model life as well.

{| class="t"
! phase
! duration
! reliability
|-
| 1
| 7 to 38 months
| increases from 48-73% to 75-100%
|-
| 2
| <code style="color:darkgreen">model_life</code> - 8 years
| stays constant at peak, 75-100%
|-
| 3
| 10 to 20.5 years
| decreases from peak to 25-50%
|}

If <code style="color:darkgreen">model_life</code> is set to <code style="color:darkgreen">VEHICLE_NEVER_EXPIRES</code>, the engine remains in phase 2 forever.

Normally, the vehicle is removed from the purchase menu at the and of phase 3. However if you set the <code style="color:darkgreen">retire_early</code> property, it will be retired this many years before (or after, if the value is negative) the end of phase 2.

==Sorting vehicles in the purchase list==
This is a special property that is not encoded in an item/property-block like most other properties but it has it's own block instead. The syntax is as follows:

sort(<feature>, [<ID>, <ID>, <ID>...]);

The engines will be sorted in the given order on the position where originally the first element was. Say the original engine sorting is this: A B C D E and you use this code <code style="color:darkgreen">sort(FEAT_TRAINS, [D, B, A]);</code> the final sorting will be this: C D B A E

==Train properties==

{| class="t"
! property
! value range
! available for<br />articulated<br />vehicle
! comment
|-
| <code style="color:green">sprite_id</code>
| <code style="color:green">SPRITE_ID_NEW_TRAIN</code>
| yes
| Set this property to enable new graphics
|-
| <code style="color:green">speed</code>
| 0 ... 65000 (float, speed units)
| no
| Max speed for engines, speed limit for wagons
|-
| <code style="color:green">misc_flags</code>
| bitmask(TRAIN_FLAG_XXX, ...)
| FLIP should not be set, TILT and MU TO the same value as the 1st part
|
;TRAIN_FLAG_TILT
: enable the tilt bonus (20% speed in curves, if all vehicles in consist have it set)
;TRAIN_FLAG_2CC
:Enable use of the 2nd company colour
;TRAIN_FLAG_MU
:act as multiple unit (used for livery selection only)
;TRAIN_FLAG_FLIP
:Allow vehicle to be flipped (reversed) in depot
;TRAIN_FLAG_AUTOREFIT
:Allow autoreffitting. To enable autorefit, furthermore the [[#Vehicle callbacks|refit_cost]]-callback has to allow it, or else (if this callback is not implemented or fails) the <code style="color:green">refit_cost</code>-property (see below) must be set to 0.
;TRAIN_FLAG_NO_BREAKDOWN_SMOKE
:{{nml|0.3}} {{ottdp|1.3|no|ottdrev=r24124}} Disable breakdown smoke effect
|-
| <code style="color:green">refit_cost</code>
| 0 ... 255
| yes
| in 50% units of the purchase price cost base
|-
| <code style="color:green">callback_flags</code>
| bitmask(VEH_CBF_XXX, ...)
| yes
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| <code style="color:green">track_type</code>
| item from railtypetable
| must be the same as front
| Default railtype table: RAIL, MONO, MGLV. If you install a railtypetable yourself you'll always get the railtype you specified. If you want a vehicle to run on electric rail and you don't have a railtypetable, set <code style="color:green">track_type</code> to RAIL and make sure that you set <code style="color:green">engine_class</code> to <code style="color:green">ENGINE_CLASS_ELECTRIC</code>.
|-
| <code style="color:green">ai_special_flag</code>
| [<code style="color:green">AI_FLAG_PASSENGER</code> <nowiki>|</nowiki> <code style="color:green">AI_FLAG_CARGO</code>]
| no
|
;<code style="color:green">AI_FLAG_PASSENGER</code>
:Tell computer players that it's an engine that should only be used for passenger service.
|-
| <code style="color:green">power</code>
| 0 ... 65000 hp (float, power units)
| Set to 0
|
|-
| <code style="color:green">running_cost_base</code>
| RUNNING_COST_XXX
| Set to RUNNING_COST_NONE
|
;RUNNING_COST_STEAM
;RUNNING_COST_DIESEL
;RUNNING_COST_ELECTRIC
;RUNNING_COST_ROADVEH
;RUNNING_COST_NONE
:no running costs
|-
| <code style="color:green">dual_headed</code>
| [0 <nowiki>|</nowiki> 1]
| Set to 0 for all parts of an articulated vehicle
| 1 = dual_headed, otherwise normal engine
|-
| <code style="color:green">default_cargo_type</code>
| An identifier from the [[NML:Cargotable|cargo table]], or DEFAULT_CARGO_FIRST_REFITTABLE
| Yes
| If the vehicle is refittable to at least one cargo, but the chosen default cargo is not available or is set to DEFAULT_CARGO_FIRST_REFITTABLE, then the first refittable cargo is used. The first refittable is chosen according to the order in your [[NML:Cargotable|cargo table]]. If this property is set to a valid cargo but the vehicle cannot refit to any cargo type, then the vehicle will be able to carry only this cargo, but it cannot be refitted (like e.g. the default train wagons).
|-
| <code style="color:green">cargo_capacity</code>
| 0 .. 255
| yes
| By default, passenger capacity is 4x, and mail/goods capacity 2x larger than capacity for other cargoes. The capacity set here is used for the default (i.e. first refittable) cargo. Use the <code style="color:green">cargo_capacity</code> callback to avoid this effect.
|-
| <code style="color:green">weight</code>
| 0 .. 1279 ton (float, mass units)
| Set to 0
|
|-
| <code style="color:green">ai_engine_rank</code>
| 0 ... 255
| no
| TTDPatch only: Higher values make the engine for the TTDPatch AI more attractive
|-
| <code style="color:green">engine_class</code>
| ENGINE_CLASS_XXX
| no
|
Defines which livery colour settings apply to the vehicle. It also sets the corresponding sound effect of the engine, and if visual_effect_and_powered is not set, the visual effect as well.
;ENGINE_CLASS_STEAM
;ENGINE_CLASS_DIESEL
;ENGINE_CLASS_ELECTRIC
;ENGINE_CLASS_MONORAIL
;ENGINE_CLASS_MAGLEV
|-
| <code style="color:green">extra_power_per_wagon</code>
| 0 ... 65000 hp (float, power units)
| Set to 0
| Only wagons with a livery override for this engine will add power
|-
| <code style="color:green">tractive_effort_coefficient</code>
| 0 ... 1 (float)
| Set to 0
| Fraction of the vehicle weight that is available as tractive effort. Tractive effort (in kN) is calculated as (TE coefficient) * 10 * weight (in tons), with 10 being an approximation of the acceleration of gravity (9.81 m/s). A good value for rail tracks is 0.3.
|-
| <code style="color:green">air_drag_coefficient</code>
| 0 ... 1 (float)
| Set to 0
| Coefficient of the relative air drag, in arbitrary units. The default value is approximately (8 / max_speed), with max_speed in km/h, clamped to the range 0.004 .. 0.75.
|-
| <code style="color:green">length</code>
| 1 ... 8
| yes
| Length of the vehicle in arbitrary units. Use a value of 8 (equal to the predefined constant VEHICLE_LENGTH) for a full-length vehicle.
|-
| <code style="color:green">visual_effect_and_powered</code>
| <code style="color:green">visual_effect_and_powered</code> (VISUAL_EFFECT_XXX, offset, <code style="color:green">ENABLE_WAGON_POWER</code> or <code style="color:green">DISABLE_WAGON_POWER</code>)
| yes
|
Set the type of visual effect for the vehicle and its positional offset with respect to the vehicle. An offset of 0 is default, negative values mean more to the front and positive values are backwards. Minimum offset is -8, maximum is 7.

;VISUAL_EFFECT_DEFAULT
:No effect, unless for the default vehicles
;VISUAL_EFFECT_STEAM
:Steam like from steam engine
;VISUAL_EFFECT_DIESEL
:Steam from internal combustion engine
;VISUAL_EFFECT_ELECTRIC
:Electric sparks
;VISUAL_EFFECT_DISABLE
:No effect
|-
| <code style="color:green">extra_weight_per_wagon</code>
| 0 ... 255 ton (float, mass units)
| Set to 0
| Adds extra weight for powered wagons, see <code style="color:green">extra_power_per_wagon</code>
|-
| <span #id="bitmask_vehicle_info"></span><code style="color:green">bitmask_vehicle_info</code>
| 8-bit bitmask
| yes
|
Used for obtaining [[#bitmask consist info|<code style="color:green">bitmask_consist_info</code>]]
|}

==Road vehicle properties==

{| class="t"
! property
! value range
! available for<br />articulated<br />vehicle
! comment
|-
| sprite_id
| SPRITE_ID_NEW_ROADVEH
| yes
| Set this property to enable new graphics
|-
| speed
| 0 ... 514km/h (float, speed units)
| no
|
|-
| misc_flags
| bitmask(ROADVEH_FLAG_XXX, ...)
| partly; tram flag must the same
|
;ROADVEH_FLAG_TRAM
:The vehicle requires tram tracks to run on
;ROADVEH_FLAG_2CC
:Enable 2nd company colour
;ROADVEH_FLAG_AUTOREFIT
:Allow autorefitting. To enable autorefit, furthermore the [[#Vehicle callbacks|refit_cost]]-callback has to allow it, or else (if this callback is not implemented or fails) the <code style="color:green">refit_cost</code>-property (see below) must be set to 0.
;ROADVEH_FLAG_NO_BREAKDOWN_SMOKE
:{{nml|0.3}} {{ottdp|1.3|no|ottdrev=r24124}} Disable breakdown smoke effect
|-
| refit_cost
| 0 ... 255
| yes
| in 25% units of the purchase price cost base
|-
| callback_flags
| bitmask(VEH_CBF_XXX, ...)
| yes
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| running_cost_base
| RUNNING_COST_XXX
| set to RUNNING_COST_NONE
|
;RUNNING_COST_STEAM
;RUNNING_COST_DIESEL
;RUNNING_COST_ELECTRIC
;RUNNING_COST_ROADVEH
;RUNNING_COST_NONE
:no running costs
|-
| power
| 0 ... 2550hp (float, power units)
| Set to 0
|
|-
| weight
| 0 ... 63.75ton (float, mass units)
| Set to 0
|
|-
| tractive_effort_coefficient
| 0 ... 1 (float)
| Set to 0
| Fraction of the vehicle weight that is available as tractive effort. Tractive effort (in kN) is calculated as (TE coefficient) * 10 * weight (in tons), with 10 being an approximation of the acceleration of gravity (9.81 m/s). Default value is 0.3.
|-
| air_drag_coefficient
| 0 ... 1 (float)
| Set to 0
| Coefficient of the relative air drag, in arbitrary units. The default value is approximately (8 / max_speed), with max_speed in km/h, clamped to the range 0.004 .. 0.75.
|-
| <code style="color:green">default_cargo_type</code>
| An identifier from the [[NML:Cargotable|cargo table]], or DEFAULT_CARGO_FIRST_REFITTABLE
| Yes
| If the vehicle is refittable to at least one cargo, but the chosen default cargo is not available or is set to DEFAULT_CARGO_FIRST_REFITTABLE, then the first refittable cargo is used. The first refittable is chosen according to the order in your [[NML:Cargotable|cargo table]]. If this property is set to a valid cargo but the vehicle cannot refit to any cargo type, then the vehicle will be able to carry only this cargo, but it cannot be refitted (like e.g. the default train wagons).
|-
| cargo_capacity
| 0 ... 255
| yes
| By default, passenger capacity is 4x, and mail/goods capacity 2x larger than capacity for other cargoes. The capacity set here is used for the default (i.e. first refittable) cargo. Use the <code style="color:green">cargo_capacity</code> callback to avoid this effect.
|-
| sound_effect
| SOUND_XXX
| no
|
See available [[NML:List of sound effects|sound effects]].
|-
| visual_effect
| visual_effect( VISUAL_EFFECT_XXX, offset)
| yes
|
Set the type of visual effect for the vehicle and its positional offset with respect to the vehicle. An offset of 0 is default, negative values mean more to the front and positive values are backwards. Minimum offset is -8, maximum is 7.

;VISUAL_EFFECT_DEFAULT
:No effect, unless for the default vehicles
;VISUAL_EFFECT_STEAM
:Steam like from steam engine
;VISUAL_EFFECT_DIESEL
:Steam from internal combustion engine
;VISUAL_EFFECT_ELECTRIC
:Electric sparks
;VISUAL_EFFECT_DISABLE
:No effect
|-
| length
| 1 ... 8
| yes
| Length of the vehicle in arbitrary units. Use a value of 8 (equal to the predefined constant VEHICLE_LENGTH) for a full-length vehicle.
|}

==Ship properties==

{| class="t"
! property
! value range
! comment
|-
| sprite_id
| SPRITE_ID_NEW_SHIP
| Set this property to enable new graphics
|-
| speed
| 0 ... 127 km/h (float, speed units)
|
|-
| misc_flags
| bitmask(SHIP_FLAG_XXX)
| Bitmask with to possible flags, set to 0 to disable all.

;SHIP_FLAG_2CC
:Enable use of the 2nd company colour
;SHIP_FLAG_AUTOREFIT
:llow autorefitting. To enable autorefit, furthermore the [[#Vehicle callbacks|refit_cost]]-callback has to allow it, or else (if this callback is not implemented or fails) the <code style="color:green">refit_cost</code>-property (see below) must be set to 0.
;SHIP_FLAG_NO_BREAKDOWN_SMOKE
:{{nml|0.3}} {{ottdp|1.3|no|ottdrev=r24124}} Disable breakdown smoke effect
|-
| refit_cost
| 0 ... 255
| in 1/32 of the default refit cost base
|-
| callback_flags
| bitmask(VEH_CBF_XXX, ...)
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| is_refittable
| [0 <nowiki>|</nowiki> 1]
| 0=false, 1=true. Note: if you do not set this property to 1, then refittable_cargo_classes / non_refittable_cargo_classes have no effect.
|-
| <code style="color:green">default_cargo_type</code>
| An identifier from the [[NML:Cargotable|cargo table]], or DEFAULT_CARGO_FIRST_REFITTABLE
| If the vehicle is refittable to at least one cargo, but the chosen default cargo is not available or is set to DEFAULT_CARGO_FIRST_REFITTABLE, then the first refittable cargo is used. The first refittable is chosen according to the order in your [[NML:Cargotable|cargo table]]. If this property is set to a valid cargo but the vehicle cannot refit to any cargo type, then the vehicle will be able to carry only this cargo, but it cannot be refitted (like e.g. the default train wagons).
|-
| cargo_capacity
| 0 ... 255
| For ships (unlike other vehicle types) the capacity set here is not affected by the cargo type.
|-
| sound_effect
| SOUND_XXX
|
See available [[NML:List of sound effects|sound effects]].
|-
| ocean_speed_fraction
| 0 ... 1 (float)
|
{{ottd|1.2|r22639}} fraction of base speed on ocean tiles (default: 1)
|-
| canal_speed_fraction
| 0 ... 1 (float)
|
{{ottd|1.2|r22639}} fraction of base speed on canal tiles (default: 1)
|-
| visual_effect
| visual_effect(VISUAL_EFFECT_XXX, offset)
| XXX=[DEFAULT <nowiki>|</nowiki> STEAM <nowiki>|</nowiki> DIESEL <nowiki>|</nowiki> ELECTRIC <nowiki>|</nowiki> DISABLE], it is the type of the visual effect you want for this ship. Default means no effect. Offset is the position of the effect. 0 is default, negative values mean more to the front and positive values are backwards. Minimum offset is -8, maximum is 7.
|}

==Aircraft properties==

{| class="t"
! property
! value range
! comment
|-
| sprite_id
| SPRITE_ID_NEW_AIRCRAFT
| Set this property to enable new graphics
|-
| speed
| 0 .. 3280 km/h (float, speed units)
|
|-
| range
| 0 .. 2894
| {{nml|0.3}} {{ottdp|1.2|no|ottdrev=r23504}} Maximum (euclidean) distance the aircraft can cover between two airports. Set to 0 for unlimited range.
|-
| misc_flags
| bitmask(AIRCRAFT_FLAG_2CC, AIRCRAFT_FLAG_AUTOREFIT)
| Bitmask with to possible flags, set to 0 to disable all.

;AIRCRAFT_FLAG_2CC
:Enable 2nd company colour
;AIRCRAFT_FLAG_AUTOREFIT
:Allow autorefitting. To enable autorefit, furthermore the [[#Vehicle callbacks|refit_cost]]-callback has to allow it, or else (if this callback is not implemented or fails) the <code style="color:green">refit_cost</code>-property (see below) must be set to 0.
;AIRCRAFT_FLAG_NO_BREAKDOWN_SMOKE
:{{nml|0.3}} {{ottdp|1.3|no|ottdrev=r24124}} Disable breakdown smoke effect
|-
| refit_cost
| 0 ... 255
| in 1/32 of default refit cost base
|-
| callback_flags
| bitmask(VEH_CBF_XXX, ...)
|
Do not set this, unless you use [[NML:Old style callbacks|old-style callbacks]].
|-
| aircraft_type
| AIRCRAFT_TYPE_XXX
|
;AIRCRAFT_TYPE_HELICOPTER
:Can land on helipad
;AIRCRAFT_TYPE_SMALL
:Can land on all airports with runway
;AIRCRAFT_TYPE_LARGE
:Can land on all airports with runway. But have a high crash chance on small airports
|-
| acceleration
| {{ottd|1.3.1}} 0 ... 255 <br/> {{ottd|<1.3.1}} 0 ... 19
| {{ottd|1.3.1}} Default aircraft use values in the range 18 to 50 (= 6.75 to 18.75 mph/tick = 499.5 to 1387.5 mph/day), which is generally considered quite fast.<br/>
{{ottd|<1.3.1}} In older OpenTTD, aircraft provided by NewGRF accelerate 166% faster than intended.
|-
| passenger_capacity
| 0 ... 65536
| Capacity for the passenger compartment. See also the notes at <code style="color:darkgreen">mail_capacity</code> below.
|-
| mail_capacity
| 0 ... 255
| Capacity for the mail compartment, if refitted to a cargo in the CC_PASSENGERS class. When refitted to other cargoes, this capacity is added to the passenger capacity to determine the base capacity. The actual capacity is set to this base capacity divided by 1 for mail, 2 for goods and 4 for all other cargoes. To override this effect, use the <code style="color:darkgreen">passenger_capacity</code> and <code style="color:darkgreen">mail_capacity</code> callbacks.
|-
| sound_effect
| SOUND_XXX
|
See available [[NML:List of sound effects|sound effects]].
|}

==Vehicle variables==

Below an overview of all vehicle-specific variables. Not that in the purchase list, the vehicle is not built yet and as such many variables are not available. All general variables are available, refer to the table for info on vehicle-specific variables. Trying to access a non-available variable invokes undefined behaviour. Please note that while all variables are available for all vehicles types, some of them only make sense for one or more vehicle types. For example checking current_railtype for a non-rail vehicle doesn't make sense at all.

===Variables without parameter===

{| class="t"
! name
! value range
! available in<br />purchase list?
! comment
|-
| position_in_consist
| 0 ... 255
| No
| The position of the current vehicle-part from the start of the vehicle. The engine will get value 0, the first wagon (or second engine) gets value 1, etc.
|-
| position_in_consist_from_end
| 0 ... 255
| No
| Same as position_in_consist but counted from the end. The last wagon will get value 0.
|-
| num_vehs_in_consist
| 1 ... 256
| No
| The total number of vehicles-parts in this vehicle. For aircraft this will include the shadow and the rotor.
|-
| position_in_vehid_chain
| 0 ... 255
| No
| See position_in_consist, but not of the complete vehicle but only all consecutive parts with the same id.
|-
| position_in_vehid_chain_from_end
| 0 ... 255
| No
| See position_in_consist_from_end, but not of the complete vehicle but only all consecutive parts with the same id.
|-
| num_vehs_in_vehid_chain
| 1 ... 256
| No
| See num_vehs_in_consist, but not of the complete vehicle but only all consecutive parts with the same id.
|-
| position_in_articulated_veh
| 0 ... 255
| No
| {{nml|0.3}} {{ottdp|1.4|no|ottdrev=r26157}} The position of the current articulated vehicle from the start of the vehicle. The first will get value 0, the second one gets value 1, etc.
|-
| position_in_articulated_veh_from_end
| 0 ... 255
| No
| {{nml|0.3}} {{ottdp|1.4|no|ottdrev=r26157}} The position of the current articulated vehicle from the end of the vehicle. The last will get value 0, the second last one gets value 1, etc.
|-
| cargo_classes_in_consist
| Bitmask of CC_XXX
| No
|
[[NML:Cargos#Cargo classes|cargo classes]]
|-
| most_common_refit
|
[[NML:Cargos#Cargo properties|cargo class]]
| No
| cargo class most often refit to
|-
| bitmask_consist_info
| Bitmask 8 bit
| No
|
Binary OR of the values of [[#bitmask vehicle info|bitmask_vehicle_info]] of all vehicles (engines, wagons) in the consist. Only available for rail vehicles.
|-
| company_num
| 0 ... 14
| Yes
| company number of the vehicle owner. TTDPatch only supports up to 8 companies (0 ... 7)
|-
| company_type
| PLAYERTYPE_XX
| Yes
|
;PLAYERTYPE_HUMAN
:human player
;PLAYERTYPE_AI
:AI player
;PLAYERTYPE_HUMAN_IN_AI
:human managing AI company
;PLAYERTYPE_AI_IN_HUMAN
:AI managing human company

OpenTTD only uses PLAYERTYPE_HUMAN and PLAYERTYPE_AI. If you cheat yourself to be part of an AI company OpenTTD will still report PLAYERTYPE_AI for the company with yourself and the AI and it'll report PLAYERTYPE_HUMAN for the now uncontrolled company.
|-
| company_colour1
| COLOUR_XXX
| Yes
|
Refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for possible values.
|-
| company_colour2
| COLOUR_XXX
| Yes
|
Same as company_colour1, if no 2nd company colour is chosen. Refer to the table [[NML:List of default colour translation palettes#Company colour helper functions|here]] for possible values.
|-
| aircraft_height
| 0 ... 255
| No
| Height difference between the aircraft and its shadow. 8 Units are equivalent to one height level on the map.
|-
| airport_type
| AIRPORTTYPE_XX
| No
|
;AIRPORTTYPE_SMALL
;AIRPORTTYPE_LARGE
;AIRPORTTYPE_HELIPORT
;AIRPORTTYPE_OILRIG
|-
| curv_info_prev_cur
| -2 ... 2
| No
| Difference in direction between the previous (towards engine) vehicle and this vehicle. Curvature to the right is positive. 1 unit is 45 degrees.
|-
| curv_info_cur_next
| -2 ... 2
| No
| Difference in direction between this vehicle and the next (towards rear end) vehicle. Curvature to the right is positive. 1 unit is 45 degrees.
|-
| curv_info_prev_next
| -4 ... 4
| No
| Difference in direction between the previous (towards engine) and next (towards rear end) vehicle. Curvature to the right is positive. 1 unit is 45 degrees. Equal to <code style="color:darkgreen">curve_invo_prev_cur + curv_info_cur_next</code>.
|-
| curv_info
| vehicle_curv_info(''prev_cur'', ''cur_next'')''''
| No
|
Returns a magic number that represents the curvature state of the prev-cur-next vehicle triplet. Do not try to make sense of this magic number, use the [[NML:Builtin functions|builtin function]] <code style="color:darkgreen">vehicle_curv_info()</code> instead to make comparisons. <code style="color:darkgreen">curv_info == vehicle_curv_info(a, b)</code> is equivalent to <code style="color:darkgreen">(curv_info_prev_cur == a) && (curv_info_cur_next == b)</code>, however the former can easily be used in a switch-block.
|-
| motion_counter
| 0 ... 15
| Yes, always 0
| Is increased every time the vehicle moves a single step on the map. Useful for animations.
|-
| cargo_type_in_veh
| entry in cargo translation table
| Yes, for the default cargo
| 0xFF if not present in the table
|-
| cargo_unit_weight
| weight per unit in 1/16t
| Yes, for the default cargo
|
|-
| cargo_classes
| Bitmask of [[NML:Cargos#Cargo properties|cargo class]]
| Yes, for the default cargo
| class of the currently transported cargo
|-
| vehicle_is_available
| [0 <nowiki>|</nowiki> 1]
| Yes
| Value is 1 if the vehicle is available on the open market
|-
| vehicle_is_testing
| [0 <nowiki>|</nowiki> 1]
| Yes
| Value is 1 if the vehicle is currently being tested
|-
| vehicle_is_offered
| [0 <nowiki>|</nowiki> 1]
| Yes
| Value is 1 if the vehicle is currently being offered for exclusive preview
|-
| build_year
| 0 ... 5000000
| Yes
| 0-based year when the vehicle was built, current year if the vehicle is not built yet
|-
| direction
| DIRECTION_XX
| No
|
See [[NML:List of direction constants|here]] for an overview of possible values and their meaning.
|-
| cargo_capacity
| 0 ... 65535
| No
| Cargo capacity (number of units) of the vehicle
|-
| cargo_count
| 0 ... 65535
| No
| Number of cargo units of cargo in the vehicle
|-
| cargo_subtype
| 0 ... 255
| Yes, always 0
| Cargo subtype, used to provide more than one refit option for the same cargo type. See also the <code style="color:darkgreen">cargo_subtype_text</code> callback.
|-
| vehicle_is_powered
| [0 <nowiki>|</nowiki> 1]
| No
| Vehicle provides power and is on the correct track type
|-
| vehicle_is_not_powered
| [0 <nowiki>|</nowiki> 1]
| No
| Vehicle is either on a wrong track type or it doesn't provide power at all
|-
| vehicle_is_potentially_powered
| [0 <nowiki>|</nowiki> 1]
| No
| Vehicle provides power, if it is on a suitable track type
|-
| vehicle_is_reversed
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle has reversed an odd number of times
|-
| built_during_preview
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle was built during the exclusive preview stage
|-
| current_railtype
| No
| Entry from railtype translation table or 0xFF
| Don't use this variable unless you've defined a railtype translation table. If the train is running on a railtype that is not listed in your railtype translation table this variable will contain 0xFF. Available since OpenTTD r20164.
|-
| waiting_triggers
|
| No
|
Random triggers waiting to be matched. (see [[NML:Random switch|Random switch]])
|-
| random_bits
| 0 ... 255
| No
|
Random data that can be used to randomize certain descisions. (see [[NML:Random switch|Random switch]])
|-
| grfid
| 0 ... 0xFFFFFFFF
| No
|
GRFID that defined the [[NML:Graphics|graphics]]-block for this vehicle. To compare this with other grfids, use the [[NML:Builtin functions|builtin function]] <code style="color:darkgreen">str2number()</code> to convert the other GRFID to a number as well.
|-
| vehicle_type_id
| 0 ... 65535 or a name defined in item block
| No
| GRF-local ID of the vehicle, equal to the item ID. Note that vehicles from other NewGRFs may have the same ID, so you'll generally have to check the <code style="color:darkgreen">grfid</code> as well.
|-
| vehicle_is_hidden
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle is hidden in a depot or tunnel.
|-
| vehicle_is_stopped
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle is stopped, or if it is braking for a stop (trains only).
|-
| vehicle_is_crashed
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle has crashed.
|-
| vehicle_is_broken
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle is broken down.
|-
| date_of_last_service
| date(year, month, day)
| No
|
|-
| breakdowns_since_last_service
| 0 ... 255
| No
| Number of breakdowns since the last service
|-
| reliability
| 0 ... 100
| No
| Reliability (percentage)
|-
| age_in_days
| 0 ... 65535
| No
| Vehicle age in days.
|-
| max_age_in_days
| 0 ... 65535
| No
| Maximum vehicle age in days.
|-
| current_speed
| (speed units)
| No
| The current speed of the vehicle in m/s
|-
| max_speed
| (speed units)
| No
| The maximum speed of the vehicle in m/s
|-
| current_max_speed
| (speed units)
| No
| {{nml|0.3}} {{ottdp|1.3|no|ottdrev=r24246}} Current maximum speed of the vehicle in m/s. This includes e.g. track or timetable limits. Only valid for front vehicle.
|-
| vehicle_is_in_depot
| [0 <nowiki>|</nowiki> 1]
| No
| Value is 1 if the vehicle is inside a depot
|-
| vehicle_is_unloading
| [0 <nowiki>|</nowiki> 1]
| No
| {{ottdp|1.5|2.5|ottdrev=r26430}} Value is 1 if the vehicle is unloading at a station and has not yet started loading new cargo.
|}

===Variables that require an argument===

{| class="t"
! name
! Argument
! value range
! available in<br />purchase list?
! comment
|-
| count_veh_id
| The vehicle ID to look for.
| 0..255
| No
| The number of vehicles in the current consist that have the given ID.
|-
| other_veh_curv_info
| Offset in the chain from the current vehicle.<ref name="offset">Argument range is -128..127. Positive values are interpreted as towards the end, negative values as towards the front. If the offset is outside the vehicle chain, the result value will be 0.</ref>
| -4..4
| No
| Difference in direction between the other vehicle and this vehicle. Curvature to the right is positive. 1 unit is 45 degrees.
|-
| other_veh_is_hidden
| Offset in the chain from the current vehicle.<ref name="offset"/>
| [0 <nowiki>|</nowiki> 1]
| No
| 1 the other vehicle is hidden in a depot or tunnel, 0 otherwise
|-
| other_veh_x_offset
| Offset in the chain from the current vehicle.<ref name="offset"/>
| -128..127
| No
| Signed difference in X-position (top-right to bottom-left) between the other vehicle and this vehicle.
|-
| other_veh_y_offset
| Offset in the chain from the current vehicle.<ref name="offset"/>
| -128..127
| No
| Signed difference in Y-position (top-left to bottom-right) between the other vehicle and this vehicle.
|-
| other_veh_z_offset
| Offset in the chain from the current vehicle.<ref name="offset"/>
| -128..127
| No
| Signed difference in Z-position (upwards) between the other vehicle and this vehicle.
|}
<references/>

==Vehicle callbacks==
The following table contains a list of available vehicle callbacks. Additionally, it's possible to provide cargo-specific graphics, using the identifier from the [[NML:Cargotable|cargo table]] as callback name. These callbacks will be used if the vehicle is refitted to the corresponding cargo type. If no cargo-specific graphics match the cargo that the vehicle is carrying, the <code style="color:darkgreen">default</code> callback is used instead. Cargo-specific graphics callbacks are never called from the purchase menu, refer to the <code style="color:darkgreen">purchase</code> callback below instead.

Note that the above affects '''graphics only''', other callbacks are unaffected.

{| class="t"
! Name
! Available for
! In purchase menu?
! value range
! comment
|-
| default
| All
| Yes, unless <code style="color:darkgreen">purchase</code> is set separately
| Sprite group
| 'Normal' vehicle graphics, if no cargo-specific graphics apply. See also the section on [[#Sprites in GUI|GUI sprites]].
|-
| purchase
| All
| Yes, only
| Sprite group
| Graphics to show in the buy menu (only the horizontal view is needed, except for dual-headed trains. With the <code>dual_headed</code> property set, special rules for the purchase menu sprite apply: two sprites are drawn (for front and back) as if the vehicle is normally constructed. If you supply one purchase menu sprite, it will be used for both vehicle parts in the purchase menu. Provide a set of 8 sprites, and the 7th resp. 3rd sprite will be drawn; provide a set of 8 blank sprites except the 7th if you want to fully control a single purchase menu sprite for a dual-headed engine. ) See also the section on [[#Sprites in GUI|GUI sprites]].
|-
| rotor
| Aircraft (helicopters)
| No
| Sprite group
| Graphics for the helicopter rotor (4 sprites; 1 stopped and 3 moving)
|-
| random_trigger
| All
| No
| N/A
| See [[NML:Random switch|random switch]] for more information.
|-
| cargo_subtype_text
| All
| No
| String, or CB_RESULT_NO_TEXT
| With this callback, you can display extra text after the cargo in the vehicle information window. This callback is called during refitting, with succesively increased values of the <code style="color:darkgreen">cargo_subtype</code> variable, until the callback returns CB_RESULT_NO_TEXT. All returned strings are then displayed as refit options. The chosen refit option is saved in the <code style="color:darkgreen">cargo_subtype</code> variable, so it can be used later for other things. In the HEQS grf for example, this mechanism is used to let the user choose between different capacities of the same vehicle.
|-
| additional_text
| All
| Yes, only
| String
| Additional text to show in the purchase list.
|-
| colour_mapping
| All
| Yes, unless <code style="color:darkgreen">purchase_colour_mapping</code> is set separately
| Recolour sprite number
|
With this callback, you can use a different recolour sprite instead of the standard 1cc / 2cc company colour remappings. See [[NML:List of default colour translation palettes|here]] for a list of default palettes. See the [[NML:Builtin functions|builtin function]] <code style="color:darkgreen">reserve_sprites()</code> for info on how to allocate your own sprite. For performance, the result is cached and only updated if the <code style="color:darkgreen"> every_32_days</code> callback requires so. Add CB_RESULT_COLOUR_MAPPING_ADD_CC to the result to add the company colour to the sprites, this requires 16 (1cc) or 256 (2cc) sprites in total.
|-
| start_stop
| All
| No
| String or CB_RESULT_NO_TEXT
| Called when starting or stopping a vehicle. Mainly useful to prevent vehicles from leaving the depot unless a certain condition is met. Return CB_RESULT_NO_TEXT to allow or a string (containing an error message) to disallow starting/stopping.
|-
| every_32_days
| All
| No
| bitmask(CB_RESULT_32_DAYS_XXX, ...)
| Called every 32 days. Set CB_RESULT_32_DAYS_TRIGGER in the bitmask to trigger TRIGGER_VEHICLE_32_CALLBACK. Set CB_RESULT_32_DAYS_COLOUR_MAPPING in the bitmask to update the colour mapping by re-running the <code style="color:darkgreen">colour_mapping</code> callback.
|-
| sound_effect
| All
| No
| SOUND_XXX, sound("sound.wav"), import_sound(grfid, number) or CB_RESULT_NO_SOUND
|
Called to play various vehicle sounds. <code style="color:darkgreen">extra_callback_info1</code> contains the sound event, see the [[#Sound events|table]] below. Return SOUND_XXX (see [[NML:List_of_sound_effects|here]]) to return a default sound. <code style="color:darkgreen">sound("soundfile")</code> imports a sound from a .wav file. <code style="color:darkgreen">import_sound(grfid, number)</code> imports a sound from another grf. A failed (or not implemented) callback will cause the default sound to be played. Return CB_RESULT_NO_SOUND to play no sound at all.
|-
| articulated_part
| Trains, Road Vehicles
| Yes (no separate callback)
| Vehicle ID, or CB_RESULT_NO_MORE_ARTICULATED_PARTS
| With this callback, you can add articulated parts (e.g. tenders) to your vehicle. Called repeatedly, until CB_RESULT_NO_MORE_ARTICULATED_PARTS is returned. After each call, the returned vehicleID is added to your vehicle. <code style="color:darkgreen">extra_callback_info1</code> contains 1 during the first call, 2 during the second, etc. Note that callback may be called from the purchase list, using vehicle variables is not possible. Or CB_RESULT_REVERSED_VEHICLE to the returned vehicle ID to display the vehicle backwards.

For NML 0.2 and lower the vehicle ID of the articulated part must be in the range 0 .. 127.
|-
| can_attach_wagon
| Trains
| No
| String or CB_RESULT_ATTACH_XXX
| Called when a wagon is being attached, to allow or disallow attaching. This callback has to be defined at the engine. However, variables in the <code style="color:darkgreen">SELF</code> scope refer to the wagon being attached, the <code style="color:darkgreen">PARENT</code> scope refers to the engine that the wagon is being attached to. Return a string to disallow with the string as error message. Return CB_RESULT_ATTACH_DISALLOW to disallow with standard message ("incompatible railtypes"), CB_RESULT_ATTACH_ALLOW to allow or CB_RESULT_ATTACH_ALLOW_IF_RAILTYPES to allow if the railtypes match (default).
|-
| refit_cost
| {{ottdp|1.2|no|ottdrev=r23089}} All
| Yes
| -8192 .. 8191 as refit cost. Add <code style="color:darkgreen">CB_RESULT_AUTOREFIT</code> if you want to allow autorefit.
| When returning a negative value, encode the cost as (cost & <code style="color:darkgreen">CB_RESULT_REFIT_COST_MASK</code>) before (possibly) adding <code style="color:darkgreen">CB_RESULT_AUTOREFIT</code>. To allow autorefitting, the corresponding bit in the <code style="color:darkgreen">misc_flags</code> must be set as well. Variable <code style="color:darkgreen">extra_callback_info1</code> contains information about the target cargo type in the format 0xccccsstt, with tt being the new cargo type, ss the new cargo subtype (see <code style="color:darkgreen">cargo_subtype_text</code>-callback) and cccc a bitmask of the [[NML:Cargos#Cargo_classes|cargo classes]] of the target cargo type. Note that this callback may also be called when the vehicle does not exist yet, so the available variables are limited.
|}

The following callbacks all have an equivalent property. The property description applies here also, except where otherwise noted.

{| class="t"
! Name
! Available for
! In purchase menu?
! comment
|-
| loading_speed
| All
| No
|
|-
| speed
| All
| Yes, unless <code style="color:darkgreen">purchase_speed</code> is set separately
| Units are not (yet) available
|-
| cost_factor
| All
| Yes, only
|
|-
| running_cost_factor
| All
| Yes, unless <code style="color:darkgreen">purchase_running_cost_factor</code> is set separately
|
|-
| cargo_age_period
| All
| No
|
|-
| cargo_capacity
| All except aircraft
| Yes, unless <code style="color:darkgreen">purchase_cargo_capacity</code> is set separately
|
|-
| passenger_capacity
| Aircraft
| Yes, unless <code style="color:darkgreen">purchase_passenger_capacity</code> is set separately
|
|-
| mail_capacity
| Aircraft
| Yes, unless <code style="color:darkgreen">purchase_mail_capacity</code> is set separately
|
|-
| range
| Aircraft
| Yes, unless <code style="color:darkgreen">purchase_range</code> is set separately
|
|-
| visual_effect_and_powered
| Trains
| No
|
|-
| visual_effect
| Road Vehicles, Ships
| No
|
|-
| power
| Trains, Road Vehicles
| Yes, unless <code style="color:darkgreen">purchase_power</code> is set separately
| Units are not (yet) available
|-
| weight
| Trains, Road Vehicles
| Yes, unless <code style="color:darkgreen">purchase_weight</code> is set separately
| Units are not (yet) available
|-
| length
| Trains, Road vehicles
| No
|
|-
| tractive_effort_coefficient
| Trains, Road Vehicles
| Yes, unless <code style="color:darkgreen">purchase_tractive_effort_coefficient</code> is set separately
| Value range is 0 .. 255 instead of 0 .. 1.
|-
| bitmask_vehicle_info
| Trains
| No
|
|}

===Sprites in GUI===
{{ottdp|1.2|no|ottdrev=r23080}} Since OpenTTD r23080 you can use variable <code style="color:darkgreen">extra_callback_info1</code> to display different sprites in the GUI and on the map. Currently these cases are available:
{| |-
! Lowest byte of extra_callback_info1 !! Meaning
|-
| 0x00 || Vehicle is drawn in a viewport, i.e. on the map.
|-
| 0x01..0x0F || reserved
|-
| 0x10 || Vehicle is drawn in the depot GUI. <ref>OpenTTD also uses this value with the purchase-list chain (cargotype FF) to determine the gridsize in ship and aircraft depots.</ref>
|-
| 0x11 || Vehicle is drawn in the vehicle details GUI. (This includes the refit GUI.)
|-
| 0x12 || Vehicle is drawn in the vehicle list.
|-
| 0x13..0x1F || reserved for other future GUIs.
|-
| 0x20 || Vehicle is drawn in the purchase list. (This includes the autoreplace GUI.)
|-
| 0x21 || Vehicle is drawn in the exclusive preview GUI or in the advertisement news.
|-
| 0x22..0x2F || reserved for other future GUIs with non-purchased vehicles.
|-
| 0x30..0xFF || reserved
|}
<references/>
The other bytes of variable <code style="color:darkgreen">extra_callback_info1</code> are reserved, and must be masked.
The cases 0x20..0x2F are called using the <code style="color:darkgreen">purchase</code>-callback, the other cases are called for the <code style="color:darkgreen">default</code>- or cargo-specific callbacks. Exception is the the special depot-gridsize call, which uses the <code style="color:darkgreen">purchase</code>-callback.

===Sound events===

{| class="t"
! Event
! Description
|-
| SOUND_EVENT_START
| Vehicle leaves station or depot, plane takes off
|-
| SOUND_EVENT_TUNNEL
| Vehicle enters tunnel
|-
| SOUND_EVENT_BREAKDOWN
| Vehicle breaks down (not for planes)
|-
| SOUND_EVENT_RUNNING
| Once per engine tick, but no more than once per vehicle motion
|-
| SOUND_EVENT_TOUCHDOWN
| Aircraft touches down
|-
| SOUND_EVENT_VISUAL_EFFECT
| Visual effect is generated (steam plume, diesel smoke, electric spark)
|-
| SOUND_EVENT_RUNNING_16
| Every 16 engine ticks if in motion
|-
| SOUND_EVENT_STOPPED
| Every 16 engine ticks if stopped
|-
| SOUND_EVENT_LOAD_UNLOAD
| Consist loads or unloads cargo
|}

NML:Switch

2014-02-22T08:52:30Z

Planetmaker: missing spaces

{{NMLNavBlocksyntax}}

switch (<feature>, (SELF|PARENT), <ID>, <expression>) {
(<range>: <return_value>;)*
<return_value>;
}

The four parameters have the following meaning:

* <code style="color:darkgreen"><feature></code>: The feature for which this switch is used (see [[NML:Features|Features]]).
* <code style="color:darkgreen">(SELF|PARENT)</code>: Which variables to use. SELF uses the variables of the item itself, while PARENT uses the variables of a related object. This related object differs per feature, refer to the table below.
* <code style="color:darkgreen"><ID></code>: Name of this switch block. This (unique) name can be used to refer to the block from other switch- or graphics-blocks.
* <code style="color:darkgreen"><expression></code>: The expression that will be evaluated to make a decision. This expression may contain variables. Instead of a single expression this may also be an array of expressions. In that case all of the array elements are evaluated in order and the last one is used to make a decision.

{| class="t"
! Feature
! SELF
! PARENT
! permanent<br />storage
|-
| FEAT_TRAINS
| Engine / wagon / articulated part itself
| Front engine
| no
|-
| FEAT_ROADVEHS
| Road vehicle part
| First road vehicle part
| no
|-
| FEAT_SHIPS
| Ship
| Ship
| no
|-
| FEAT_AIRCRAFT
| Aircraft (a)
| Aircraft
| no
|-
| FEAT_STATIONS
| Station tile
| Town
| no
|-
| FEAT_CANALS
| Canal tile
| N/A
| no
|-
| FEAT_BRIDGES
| Bridge
| Town
| no
|-
| FEAT_HOUSES
| House tile
| Town
| no
|-
| FEAT_GLOBALVARS
| N/A
| N/A
| no
|-
| FEAT_INDUSTRYTILES
| Industry tile
| Industry to which the tile belongs
| no
|-
| FEAT_INDUSTRIES
| Industry
| Town
| yes
|-
| FEAT_CARGOS
| Cargo type
| N/A
| no
|-
| FEAT_SOUNDEFFECTS
| N/A
| N/A
| no
|-
| FEAT_AIRPORTS
| Airport
| N/A
| yes
|-
| FEAT_SIGNALS
| N/A
| N/A
| no
|-
| FEAT_OBJECTS
| Object tile
| Town
| no
|-
| FEAT_RAILTYPES
| Rail tile
| N/A
| no
|-
| FEAT_AIRPORTTILES
| Airport tile
| Airport
| no
|}

(a) Except for mail capacity callbacks, where it refers to the mail compartment. To refer to the aircraft itself, use PARENT scope there.

<code style="color:darkgreen"><range></code> can either be a single number or two numbers separated by two dots. In the first case, the range matches if the result of the computation is equal to the supplied value. If a range (<code style="color:darkgreen">a .. b</code>) is supplied, it matches if the computed result is within that range. If several lines of the switch block match the expression being tested the first applicable result will be returned.

Possible values for <code style="color:darkgreen"><return_value></code> are the following:

* <code style="color:darkgreen"><ID>;</code> chains to the (random-)switch or spritegroup with the given ID.
* <code style="color:darkgreen">return (<expression>|<string>);</code> returns the given expression or string as a result of the callback. A returned expression may contain variables (with the same scope as the switch block itself), parameter accesses and everything else that a normal switch-expression may contain.
* <code style="color:darkgreen">return;</code> returns the computed value directly as a callback result. Note that the maximum value for callback results is 32511 (0x7EFF).
* <code style="color:darkgreen">CB_FAILED;</code> stops processing and returns an explicit failure code.

Some example code is given below. Note that the code does not have an actual meaning, it is merely meant to demonstrate all the various options available.

<pre style="color:blue">
switch (FEAT_TRAINS, PARENT, some_vehicle_switch, (position_in_consist + param[1]) % 4) {
0..2: return string(STRING_FOO_BAR); //return a text message
3: return; //return the computed value
5..300: return 42; //42 is always a good answer
400: other_switch; //chain to some other switch block
401: return num_vehs_in_consist + 1; //return a value with a variable access
CB_FAILED; //return a failure result as default
}
</pre>

You can also use temporary variables and with some features also pemanent variables to store and retrieve some values by means of <code style="color:darkgreen">STORE_TEMP(value, register)</code>, <code style="color:darkgreen">LOAD_TEMP(register)</code> and <code style="color:darkgreen">STORE_PERM(value, register)</code> and <code style="color:darkgreen">LOAD_PERM(register[, grfid])</code> respectively. Using temporary storage is useful when you want to use the result of an expensive calculation in various decisions (switches) within the chain (like for example the number of a certain wagon type within a train). Permanent storage might be useful to control the long-term behaviour of an object. Note that it is only available for industries, airports and towns. For towns, you can optionally specify a grfid to load registers belonging to a different grf. Note that accessing (both reading and writing) permanent town registers thrashes the contents of temporary register 0x100.

{{nml|0.3}} As of NML 0.3 it is possible to specify the default value using <code>default: <value>;</code> as one of the 'ranges'. Specifying multiple default values (either this way or by the classical method) is of course not possible, but omitting a default value is allowed. In that case, if none of the ranges matches, the callback fails.

NML:Town names parts

2014-02-01T22:10:58Z

Planetmaker: some spelling and linke to other part of townname docs

{{NMLNavBlocksyntax}}

A <code style="color:darkgreen">town_names</code> block has one or more <code style="color:darkgreen"><part></code>s. Each part defines a piece of a town name. All pieces together form the name generated by the [[NML:town_names|townname]] block.

An example of a part is:

{
text("name1", 1),
text("name2", 2),
town_names(othernames, 3)
}

The simplest form is just a list of <code style="color:darkgreen">text(...)</code>entries. Each entry contains a possible value of piece, and a probability of picking that name. The <code style="color:darkgreen">town_names(<name>, <probability>)</code>calls a previous <code style="color:darkgreen">town_names</code> block (called 'othernames' in the example), and returns the value generated there. A part should have at least one entry. Up to 255 entries will always work. If a part contains even more entries, NML tries to make it fit by creating sub-blocks. If that fails, you will get an error.

The numbers are the probabilities. In the example, the sum of all values is 6, which means that <code style="color:darkgreen">name1</code> is picked with 1/6 chance, <code style="color:darkgreen">name2</code> has a 2/6 chance, and a name generated from the previous <code style="color:darkgreen">town_names</code> block has a 3/6 chance.

NML:Town names

2014-02-01T22:07:41Z

Planetmaker: Add link to town name parts

{{NMLNavBlocksyntax}}

To define randomly generated town names, the <tt>town_names</tt> block should be used. Such blocks can be used in two ways, as generator of (partial) town names for another block, or as top-level town names block, a starting point of town names in the grf file. You must have at least one starting point, but you can have more than one.

The general syntax of a town names block is:

town_names[(<name>)] {
[styles : <string>]
<part> <part> ....
}

The optional <code style="color:darkgreen"><name></code> defines the name of the block. Such a name is used to refer to this block from another town names block. For top-level town names blocks, it is often left out. Note that in that case, you must also leave out the parentheses.

The optional <code style="color:darkgreen"><string></code> defines how the town names are called in the menu. It may only be defined in a top-names block. To make the name available in all languages, it is probably a good idea to at least define a menu name for the generic language.

The townname <code style="color:darkgreen"><part></code>s define the actual strings and their probability of the [[NML:Town_names_parts|parts]] which townnames consist of.

== Example ==

In this example, town names are randomly constructed from two parts. Note that the top-level block is on the bottom; this is necessary so it can reference the other two blocks. Have a look at the [[NML:Town_names_parts]] section for more info on the syntax used in this example.

town_names(one) {
{
text("Avon", 31),
text("Black", 10),
...
}
}

town_names(two) {
{
text(" Bridge", 1),
text("ton", 1),
...
}
}

town_names {
styles : string(STR_STYLES);
{
town_names(one,3)
}
{
town_names(two,1)
}
}

This will generate:

Avon Bridge
Avonton
Black Bridge
Blackton

NML:Recolour sprites

2013-12-18T13:22:07Z

Planetmaker: change palette naming DOS->default and windows->legacy to match OpenTTD's naming of those

{{NMLNavBlocksyntax}}

Recolour sprites are special sprites that are used to recolour other sprites, for example to apply company colours. It's basically a remapping of the colour table.

<pre style="color:blue">
recolour_sprite {
0xC6: 0x28;
0xC7: 0xF5;
0xC8..0xCD: 0x0A..0x0F;
}
</pre>

The above example will remap colour 0xC6 as 0x28, 0xC7 as 0xF5 and the range 0xC8 to 0xCD to the colours 0x0A..0x0F. This is one of the company colour recolour sprites defined in the baseset. Please note that in NML every recolour sprite will use the Default (DOS) palette. If your actual graphics files use the legacy (windows) palette, nmlc will silently convert the recolour sprite to the legacy (windows) palette before writing it to the output file.

With the following table you can find out the colour indices in the Default (DOS) palette (left).

[[File:TTD_Palettes.png]]