GRFSpecs - User contributions [en-gb]

Callback: Industry location permissibility

2025-05-13T14:13:02Z

Frosch: /* Industry location permissibility (28) */

== Industry location permissibility (28) ==

Called to decide if the industry can be built on a given spot. Since the industry isn't built yet, you can only use a small subset of the data: you can access the data of the nearest town via action 2/type 82 without any problems, but action 2/type 81 will access different variables than it would normally access:

{| |-
!Variable!![[GRFActionsDetailed|Size]]!!Version!!Meaning
|-
|40+x|| ||{{ottdp| | }}||Not accessible
|-
|5F|| ||{{ottdp|1.1|no|ottdrev=19744}}||Random bits the industry starts with after construction. Accessible via RandomAction2 as well.
|-
|60+x|| ||{{ottdp| | }}||Only var. 62 and vars 64..68 can be used
|-
|80||W||{{ottdp| | }}||Coordinates of the selected position
|-
|86||B||{{ottdp| | }}||Number of the selected layout, according to property 0A
|-
|87||B||{{ottdp| | }}||Ground type of the selected spot (see [[VarAction2Canals|canal variable 81]] for details)
|-
|88||B||{{ottdp| | }}||[[TownZones|Town zone]] of the selected spot (see [[VarAction2Houses#Town zone 42|house variable 42]] for details)
|-
|89||B||{{ottdp| | }}||Distance between the closest town and the selected position.
|-
|8A||B||{{ottdp| | }}||Height of the lowest corner of the tile
* {{grfTill|7}} For GRF version 7 and below: Multiple of 8.
* {{grfFrom|8}} For GRF version 8 and above: Multiple of 1.
|-
|8B||W||{{ottdp| | }}||Distance to the closest water tile if property 1A bit 2 is clear (built on land); distance to the closest empty dry land tile if property 1A bit 2 is clear (built on water)
|-
|8D||W||{{ottdp| | }}||Square of the Euclidean distance between the closest town and the selected position
|-
|8F||D||{{ottdp|0.6|2.6|ottdrev=r11985|ttdprev=r1816}}|| 32 random bits
|}
Unless explicitly noted, distances are Manhattan distance, not Euclidean distance, ie. <tt>|x-x0|+|y-y0|</tt> instead of <tt>sqrt((x-x0)^2+(y-y0)^2)</tt>

Variable 8B will always be below 80h if prop 1A bit 2 is clear. If bit 2 is set, 8B will be set to its max of 200h in the pathological case of an all-water map.

{{ottd|1.1|r20942}} During this callback, variable 18 (extra callback info 2) contains the following values for OpenTTD r20942 and later:

{| |-
!Variable 18!!Meaning
|-
|0||TTD is generating a map.
|-
|1||TTD decided to build a new random industry during regular gameplay.
|-
|2||The user tries to build your industry via the new industry window.
|-
|3||The user tries to prospect for your industry via the new industry window.
|}

This callback must return a 15-bit value, which is interpreted as follows:

{| |-
!Value!!Version!!Meaning
|-
|0000-03ff||{{ottdp| | }}||Industry can't be built, display the misc. GRF text D0xx as error message
|-
|0400||{{ottdp| | }}||Industry can be built
|-
|0401||{{ottdp| | }}||Industry can't be built, display the default "site unsuitable" error message.
|-
|0402||{{ottdp| | }}||Industry can't be built, display the "...can only be built in rainforest areas" error message.
|-
|0403||{{ottdp| | }}||Industry can't be built, display the "...can only be built in desert areas" error message.
|-
|0404||{{ottdp|1.2|no|ottdrev=r22657}}||Industry can't be built, display the "...can only be built above the snow-line" error message.
|-
|0405||{{ottdp|1.2|no|ottdrev=r22657}}||Industry can't be built, display the "...can only be built below the snow-line" error message.
|-
|0406||{{ottdp|1.2|no|ottdrev=r22657}}||Industry can't be built, display the "...can't build on open sea" error message.
|-
|0407||{{ottdp|1.2|no|ottdrev=r22657}}||Industry can't be built, display the "...can't build on canal" error message.
|-
|0408||{{ottdp|1.2|no|ottdrev=r22657}}||Industry can't be built, display the "...can't build on river" error message.
|-
|040F||{{ottdp|15|no}}||Industry can't be built. Display error message using text ID from register 0x100 (not limited to D0xx texts). The text stack starts at register 0x101.
|}

{{ottdp|0.6-14|2.6|ttdprev=r1755}} Since TTDPatch r1755, you can use the text reference stack for your error messages, similarly to callback 3A. The only difference is that only 4 registers are copied instead of 6 because error messages support 20 bytes of reference stack only, and two of those bytes may be used by TTD.

{{ottdp|15|no}} The contents of registers 100h..10Fh are copied onto the text reference stack.

[[Category:Callbacks]]

Callback: Additional text in purchase screen

2025-05-13T14:12:42Z

Frosch: /* Additional text in purchase screen (23) */

== Additional text in purchase screen (23) ==

This callback can be used to append text below the vehicle information in the purchase screen. The callback is always used when defined, no bit in the action 0 property needs to be set to activate it.

{|
|-
!Return value!!Version!!Meaning
|-
|0000..03FF|| ||D0xx text to display. {{ttdp|}} Before r1908 only text IDs D000..D0FF were supported.
|-
|0400||{{grfFrom|8}}||Display no text (same as callback failure).
|-
|040F||{{ottdp|15|no}}||Display text using text ID from register 0x100 (not limited to D0xx texts). The text stack starts at register 0x101.
|}

{{ottdp|1.2-14|no|ottdrev=r23045}} Since OpenTTD r23045 the contents of registers 100h..105h are copied onto the text reference stack.

{{ottdp|15|no}} The contents of registers 100h..10Fh are copied onto the text reference stack.

Lines are wrapped automatically, or may be broken explicitly using the newline character 0D. How many lines are available depends on the type of vehicle and its other properties, for instance the presence or absence of a "refittable to" line or powered wagons etc.

If cargo FF (buy menu sprite) is handled explicitly for a vehicle, then the varaction 2 handling [[Callbacks#Additional text in purchase screen (23) |callback 23]] must be in the buy menu varaction 2 chain.

Example for setting additional text for a road vehicle:

// Define string with ID D001 for featur 01. Bit 7 of the language byte must be set to 1, because the string ID is a word.
4 * 32 04 01 83 01 \wxD001 "Hint: This is a " 0D "new line." 00
// The callback
5 * 14 02 01 10 85 0C 00 \wxFFFF 01 \wx8001 \wx23 \wx23 02 00

[[Category:Callbacks]]

Callback: Can wagon be attached

2025-05-13T14:08:28Z

Frosch: /* Can wagon be attached (1D) */

== Can wagon be attached (1D) ==

This callback is called for the train engine (i.e. from the engine's action 3) when attaching a new vehicle to the current train and determines whether it may in fact be attached to the train. The callback is always used when defined, no bit in the action 0 property needs to be set to activate it.

You may use VarAction2s to check variables 40+x and 80+x. For var. action 2 type 81 (vehicle), they refer to variables of the wagon that is to be attached, not the engine it is being attached to, so you can check the wagon's properties like the cargo type to see whether it is appropriate for the given train engine.

{{ottdp| |2.5|ttdprev=alpha 46}} Var. action 2 type 82 (engine) refers to the engine the wagon is being attached to, starting from version TTDPatch 2.0.1 alpha 46. This allows you to for example find out the length of the train it is being attached to. In earlier patch versions, it refers to the engine of the source consist (or the wagon if the wagon is not attached to anything else), which was not really helpful.

So, overall the callback is evaluated this way:
* The Action 3 is used from the regular engine (livery overrides have no influence).
* The cargotype to use in Action 3 is taken from the wagon.
* VarAction2 types 81, 85, 89 refer to the wagon.
* VarAction2 types 82, 85, 8A refer to the engine.

{{grfTill|7}} For GRF version 7 and below the valid return values are:
{| |-
!Return!!Meaning
|-
|00..FC||Disallow attaching and use the D0xx (D000..D0FC) text ID as second line of an error message,
|-
|FD||Disallow attaching with the standard message (incompatible rail types)
|-
|FE||Allow attaching<ref name="ignorerailtype">This mean you would allow attaching for example a monorail wagon to a regular rail vehicle.</ref>
|-
|FF||Allow attaching if the rail types match (default)
|}

{{grfFrom|8}} For GRF version 8 and above the valid return values are:
{| |-
!Return!!Meaning
|-
|00..3FF||Disallow attaching and use the D0xx (D000..D3FF) text ID as second line of an error message,
|-
|400||Allow attaching if the rail types match (default)
|-
|401||Allow attaching<ref name="ignorerailtype"/>
|-
|402||Disallow attaching with the standard message (incompatible rail types)
|-
|40F||{{ottdp|15|no}} Disallow attaching and display error message using text ID from register 0x100 (not limited to D0xx texts).
|}

<references/>

[[Category:Callbacks]]

Callback: Cargo Subtype Display

2025-05-13T14:06:19Z

Frosch: /* Cargo Subtype Display (19) */

== Cargo Subtype Display (19) ==

NOTE: As of OpenTTD 13, this feature is considered deprecated for most uses. Use variants instead.

This callback allows you to display some text after the cargo name when refitting, and in the vehicle capacity display. This is useful to distinguish several subtypes of a certain cargo, e.g. goods could be cars, petroleum, sheet metal etc.

The return value must be the number of a D0xx string set by an action 4 in the same .grf file.  For example, if you set text ID D006 to some text, return 06 in this callback will make it displayed after the cargo name.

Normally, you would use the vehicle refit cycle/sub type variable F2 to distinguish the various subtypes.  During refitting, the callback is called with successively increased values of variable F2, until the callback says to stop.  All the returned variations are then displayed as refitting options, with all options that have the same cargo type and callback result (irrespective of refit cycle) grouped together in the same line.

{{grfTill|7}} For GRF version 7 and below the valid return values are:
{| |-
|00..FE|| Use subtype from text D0xx (D000..D0FE)
|-
|FF|| Stop calling.
|}

{{grfFrom|8}} For GRF version 8 and above the valid return values are:
{| |-
|00..3FF|| Use subtype from text D0xx (D000..D3FF)
|-
|400|| Stop calling.
|-
|40F|| {{ottdp|15|no}} Use subtype with text ID from register 0x100 (not limited to D0xx texts).
|}

[[Category:Callbacks]]

Callback: Industry location permissibility

2025-05-13T14:04:20Z

Frosch: /* Industry location permissibility (28) */

== Industry location permissibility (28) ==

Called to decide if the industry can be built on a given spot. Since the industry isn't built yet, you can only use a small subset of the data: you can access the data of the nearest town via action 2/type 82 without any problems, but action 2/type 81 will access different variables than it would normally access:

{| |-
!Variable!![[GRFActionsDetailed|Size]]!!Version!!Meaning
|-
|40+x|| ||{{ottdp| | }}||Not accessible
|-
|5F|| ||{{ottdp|1.1|no|ottdrev=19744}}||Random bits the industry starts with after construction. Accessible via RandomAction2 as well.
|-
|60+x|| ||{{ottdp| | }}||Only var. 62 and vars 64..68 can be used
|-
|80||W||{{ottdp| | }}||Coordinates of the selected position
|-
|86||B||{{ottdp| | }}||Number of the selected layout, according to property 0A
|-
|87||B||{{ottdp| | }}||Ground type of the selected spot (see [[VarAction2Canals|canal variable 81]] for details)
|-
|88||B||{{ottdp| | }}||[[TownZones|Town zone]] of the selected spot (see [[VarAction2Houses#Town zone 42|house variable 42]] for details)
|-
|89||B||{{ottdp| | }}||Distance between the closest town and the selected position.
|-
|8A||B||{{ottdp| | }}||Height of the lowest corner of the tile
* {{grfTill|7}} For GRF version 7 and below: Multiple of 8.
* {{grfFrom|8}} For GRF version 8 and above: Multiple of 1.
|-
|8B||W||{{ottdp| | }}||Distance to the closest water tile if property 1A bit 2 is clear (built on land); distance to the closest empty dry land tile if property 1A bit 2 is clear (built on water)
|-
|8D||W||{{ottdp| | }}||Square of the Euclidean distance between the closest town and the selected position
|-
|8F||D||{{ottdp|0.6|2.6|ottdrev=r11985|ttdprev=r1816}}|| 32 random bits
|}
Unless explicitly noted, distances are Manhattan distance, not Euclidean distance, ie. <tt>|x-x0|+|y-y0|</tt> instead of <tt>sqrt((x-x0)^2+(y-y0)^2)</tt>

Variable 8B will always be below 80h if prop 1A bit 2 is clear. If bit 2 is set, 8B will be set to its max of 200h in the pathological case of an all-water map.

{{ottd|1.1|r20942}} During this callback, variable 18 (extra callback info 2) contains the following values for OpenTTD r20942 and later:

{| |-
!Variable 18!!Meaning
|-
|0||TTD is generating a map.
|-
|1||TTD decided to build a new random industry during regular gameplay.
|-
|2||The user tries to build your industry via the new industry window.
|-
|3||The user tries to prospect for your industry via the new industry window.
|}

This callback must return a 15-bit value, which is interpreted as follows:

{| |-
!Value!!Version!!Meaning
|-
|0000-03ff||{{ottdp| | }}||Industry can't be built, display the misc. GRF text Dxxx as error message
|-
|0400||{{ottdp| | }}||Industry can be built
|-
|0401||{{ottdp| | }}||Industry can't be built, display the default "site unsuitable" error message.
|-
|0402||{{ottdp| | }}||Industry can't be built, display the "...can only be built in rainforest areas" error message.
|-
|0403||{{ottdp| | }}||Industry can't be built, display the "...can only be built in desert areas" error message.
|-
|0404||{{ottdp|1.2|no|ottdrev=r22657}}||Industry can't be built, display the "...can only be built above the snow-line" error message.
|-
|0405||{{ottdp|1.2|no|ottdrev=r22657}}||Industry can't be built, display the "...can only be built below the snow-line" error message.
|-
|0406||{{ottdp|1.2|no|ottdrev=r22657}}||Industry can't be built, display the "...can't build on open sea" error message.
|-
|0407||{{ottdp|1.2|no|ottdrev=r22657}}||Industry can't be built, display the "...can't build on canal" error message.
|-
|0408||{{ottdp|1.2|no|ottdrev=r22657}}||Industry can't be built, display the "...can't build on river" error message.
|-
|040F||{{ottdp|15|no}}||Industry can't be built. Display error message using text ID from register 0x100 (not limited to D0xx texts). The text stack starts at register 0x101.
|}

{{ottdp|0.6-14|2.6|ttdprev=r1755}} Since TTDPatch r1755, you can use the text reference stack for your error messages, similarly to callback 3A. The only difference is that only 4 registers are copied instead of 6 because error messages support 20 bytes of reference stack only, and two of those bytes may be used by TTD.

{{ottdp|15|no}} The contents of registers 100h..10Fh are copied onto the text reference stack.

[[Category:Callbacks]]

Callback: Engine name

2025-05-13T13:59:07Z

Frosch: /* Engine name (161) */

== Engine name (161) ==

This callback allows you to dynamically determine the name shown for an engine type.

{|
|-
!Return value!!Version!!Meaning
|-
|0000..03FF|| ||D0xx text to display.
|-
|0400||{{grfFrom|8}}||Display regular name from Action4 (same as callback failure).
|-
|040F||{{ottdp|15|no}}||Display text using text ID from register 0x100 (not limited to D0xx texts). The text stack starts at register 0x101.
|}

The contents of registers {{ottdp|14|no}} 100h..105h {{ottdp|15|no}} 100h..10Fh are copied onto the text reference stack and can be used with string codes 80/81 to show texts from the D8xx range as well, extending the available unique strings.

The callback is run in purchase list scope, i.e. for cargotype FF. No variables of an actual vehicle are available.

During this callback, variable 10 (extra callback info 1) contains information about the context where the name is shown.

{| |-
! Bits 0 - 7 of [[GlobalVariables#Extra_callback_info_.2810_.2F_-.29_and_.2818_.2F_-.29|variable 10]]<ref>Values correspond to the values used for [[Action2/Vehicles#Drawing_different_sprites_on_map_in_various_GUIs|sprite drawing]].</ref>!! Meaning
|-
| 00 || No specific context is avaible.
|-
| 01..10 || reserved
|-
| 11 || Name is shown in the vehicle details GUI. (This includes the refit GUI.)
|-
| 12..1F || reserved for other future GUIs.
|-
| 20 || Vehicle is drawn in the purchase list. (This includes the "Available vehicles" panel of autoreplace GUI.) Bits '''8 - 15''' contain the indentation level in the list, e.g. when using vehicle variants.
|-
| 21 || Vehicle is drawn in the exclusive preview GUI or in the advertisement news.
|-
| 22 || Vehicle is drawn in the "Vehicles in use" panel of autoreplace GUI.
|-
| 23..2F || reserved for other future GUIs with non-purchased vehicles.
|-
| 30..FF || reserved
|}

<references/>

This callback is available from {{ottdp|14|no|ottdrev=g05ed9f56fd}} OpenTTD 14 and above.
[[Category:Callbacks]]

Callback: Layout name

2025-05-13T13:55:46Z

Frosch: /* Airport layout name (156) */

== Airport layout name (156) ==

This callback allows you to show a name for an airport layout.

{|
|-
!Return value!!Version!!Meaning
|-
|0000..03FF|| ||D0xx text to display.
|-
|0400||{{grfFrom|8}}||Display no text (same as callback failure).
|-
|040F||{{ottdp|15|no}}||Display text using text ID from register 0x100 (not limited to D0xx texts).
|}

This callback is always called when available, you do not need to set a bit in any action0 property to enable it. Available for OpenTTD since r20273.
[[Category:Callbacks]]

Callback: Extra information about layout in the build gui

2025-05-13T13:55:10Z

Frosch: /* Extra information about airport layout in the build gui (155) */

== Extra information about airport layout in the build gui (155) ==

This callback allows you to display some extra text in the build airport gui.

{|
|-
!Return value!!Version!!Meaning
|-
|0000..03FF|| ||D0xx text to display.
|-
|0400||{{grfFrom|8}}||Display no text (same as callback failure).
|-
|040F||{{ottdp|15|no}}||Display text using text ID from register 0x100 (not limited to D0xx texts).
|}

This callback is always called when available, you do not need to set a bit in any action0 property to enable it. Available for OpenTTD since r20272
[[Category:Callbacks]]

Callback: Customized building name

2025-05-13T13:54:15Z

Frosch: /* House customized building name (14D) */

== House customized building name (14D) ==

This callback is activated from the Tile Description Query tool, when enquiring a house. Bit 0 of variable 10 will be set to 1 if the house is complete, otherwise it will be 0.

{|
|-
!Return value!!Version!!Meaning
|-
|0000..03FF|| ||D0xx text to display.
|-
|0400||{{grfFrom|8}}||Display usual text from property 12 (same as callback failure).
|-
|040F||{{ottdp|15|no}}||Display text using text ID from register 0x100 (not limited to D0xx texts).
|}

Since this callback is not performed frequently, you do not need to specify a mask.  It will always be performed, and the name will only change when successful.

Available for OpenTTD since r15172, and for TTDPatch since TTDPatch 2.6r2249
[[Category:Callbacks]]

Callback: Show additional text in industry window

2025-05-13T13:52:34Z

Frosch: /* Show additional text in industry window (3A) */

== Show additional text in industry window (3A) ==

This callback allows you to display extra information in the industry window about the state of your industry.

{|
|-
!Return value!!Version!!Meaning
|-
|0000..03FF|| ||D0xx text to display.
|-
|0400||{{grfFrom|8}}||Display no text (same as callback failure).
|-
|040F||{{ottdp|15|no}}||Display text using text ID from register 0x100 (not limited to D0xx texts). The text stack starts at register 0x101.
|}

The text must begin with a colouring special character and should not be longer than one line. For example, you can use this callback to display the current production limit of a secondary industry.

{{ottd|0.6|r11987}} Note that since r11987, OpenTTD allows resizing the window when this callback is enabled.  It allows to specify a text containing more than one line.

{{ottdp|0.6-14|2.6|ttdprev=r1370}} Since TTDPatch 2.6 r1370, the contents of registers 100h..105h are copied onto the text reference stack. This allows you to display dynamically calculated values in the text by using the according StringCodes. Please note, though, that the text handler will see it as an array of bytes, not as an array of DWORDs, so you will have to pack two words into a register when you use codes that read words from the stack. In the case of \7D (which gets a byte), you may have to pack more into a register, but it's probably easier to use \7C instead.

{{ttdp|}} Please also note that you can use \80 to display textIDs calculated on the fly, but DCxx textIDs won't work correctly. When you need to choose from your own texts dynamically, you must use D0xx IDs, and add 400h to them. (That is, use D400 to refer to D000, D401 for D001 etc.)

{{ottdp|15|no}} The contents of registers 100h..10Fh are copied onto the text reference stack.

This callback is available from {{ttdp|2.5}} TTDPatch 2.0.1 a72 and above
[[Category:Callbacks]]

Callback: Show additional text in fund/building window

2025-05-13T13:48:14Z

Frosch: /* Show additional text in fund/building window (38/15C) */

== Show additional text in fund/building window (38/15C) ==

This callback allows you to display extra information in the industry fund and object building windows.

{|
|-
!Return value!!Version!!Meaning
|-
|0000..03FF|| ||D0xx text to display.
|-
|0400||{{grfFrom|8}}||Display no text (same as callback failure).
|-
|040F||{{ottdp|15|no}}||Display text using text ID from register 0x100 (not limited to D0xx texts). The text stack starts at register 0x101.
|}
The text must begin with a colouring special character and should not be longer than three lines (automatic line breaks are provided, but you can use char 0D for a manual line break). Since the industry isn't built yet, you can't access any industry variables during this callback. Same holds for objects.

Callback 38 is available from TTDPatch 2.0.1 a72 and above.

{{ottdp|1.1-14|2.6|ottdrev=r20086|ttdprev=r2354}} The contents of registers 100h..105h are copied onto the text reference stack.

{{ottdp|15|no}} The contents of registers 100h..10Fh are copied onto the text reference stack.

[[Category:Callbacks]]

Callback: Cargo sub-type display for industries

2025-05-13T13:41:58Z

Frosch: /* Cargo sub-type display for industries (37) */

== Cargo sub-type display for industries (37) ==

This callback allows you to display some text after the cargo name in the industry fund window and in industry windows.

{{grfTill|7}} For GRF version 7 and below the valid return values are:
{| |-
|00..FE|| Display D0xx (D000..D0FE) text.
|-
|FF|| Display no text.
|-
|100..1FE|| Display D0xx (D100..D1FE) text.
|-
|200..2FE|| Display D0xx (D200..D2FE) text.
|-
|300..3FE|| Display D0xx (D300..D3FE) text.
|}

{{grfFrom|8}} For GRF version 8 and above the valid return values are:
{| |-
|00..3FF|| Display D0xx (D000..D3FF) text. Display waiting amount if production CB is used.
|-
|400|| Display no text. Display waiting amount if production CB is used.
|-
|401|| {{ottdp|1.7|no|ottdrev=r27751}} Display no waiting amount and no text.
|-
|40E|| {{ottdp|15|no}} Display text without waiting amount using text ID from register 0x100 (not limited to D0xx texts). The text stack starts at register 0x101.
|-
|40F|| {{ottdp|15|no}} Display text and potentially waiting amount using text ID from register 0x100 (not limited to D0xx texts). The text stack starts at register 0x101.
|-
|800..BFF|| {{ottdp|1.7|no|ottdrev=r27751}} Display D0xx (D000..D3FF) text without waiting amount.
|}

During the callback, variable 18 specifies which cargo sub-type is queried.
The meaning of variable 18 changes with industry property 1A flag 18.

'''Bits 0..7''' of var. 18 can have the following values:
* If property 1A flag 18 is clear.
{| |-
!Number!!Meaning
|-
|00||Return subtext for first accepted cargo type
|-
|01||Return subtext for second accepted cargo type
|-
|02||Return subtext for third accepted cargo type
|-
|03||Return subtext for first produced cargo type
|-
|04||Return subtext for second produced cargo type
|}
* {{ottdp|1.9|no|ottdrev=e66cec8f}} If property 1A flag 18 is set.
{| |-
!Number!!Meaning
|-
|00||Return subtext for an accepted cargo type. Use bits 16..23 to distinguish them.
|-
|01||Return subtext for a produced cargo type. Use bits 16..23 to distinguish them.
|}

'''Bits 8..15''' of var. 18 can have the following values:
{| |-
!Number!!Meaning
|-
|00||The text is to be displayed in the industry fund window. The industry isn't built yet, so you can't access the industry variables
|-
|01||The text is to be displayed in the window of the industry. You can use the industry variables here.
|-
|02||The text is to be displayed in the industry directory window. You can use the industry variables here.
|-
|other values||Reserved for future use
|}

'''Bit 16..23''' of var. 18 contain the cargo type from the CTT (only if property 1A flag 18 is set).

Other bits of var. 18 are reserved for future use.

{{ottdp|1.0 - 14|no|ottdrev=r17802}} Since OpenTTD r17802, the contents of registers 100h..105h are copied onto the text reference stack.

{{ottdp|15|no}} The contents of registers 100h..10Fh are copied onto the text reference stack.

[[Category:Callbacks]]

Callback: Vehicle Start/stop check

2025-05-13T13:36:41Z

Frosch: /* Vehicle Start/stop check (31) */

== Vehicle Start/stop check (31) ==

This callback is called whenever a player (or the AI) tries to start or stop a vehicle. This is mainly useful for preventing vehicles
from leaving the depot unless a given condition is met. To check whether a vehicle is being started or stopped, check
bit 1 of variable B2. If set, the vehicle is currently stopped and if clear, the vehicle is moving (or at least, not stopped manually).

{{grfTill|7}} For GRF version 7 and below the valid return values are:
{| |-
|00..FE|| Display error message using D0xx (D000..D0FE) text as second line.
|-
|FF|| Start/stop action shall succeed.
|-
|100..1FE|| Display error message using D0xx (D100..D1FE) text as second line.
|-
|200..2FE|| Display error message using D0xx (D200..D2FE) text as second line.
|-
|300..3FE|| Display error message using D0xx (D300..D3FE) text as second line.
|}

{{grfFrom|8}} For GRF version 8 and above the valid return values are:
{| |-
|00..3FF|| Display error message using D0xx (D000..D3FF) text as second line.
|-
|400|| Start/stop action shall succeed.
|-
|40F|| {{ottdp|15|no}} Display error message using text ID from register 0x100. (not limited to D0xx texts)
|}

The callback is always used when defined, no bit in the action 0 property needs to be set to activate it.

[[Category:Callbacks]]

RandomAction2

2025-05-13T13:26:02Z

Frosch: /* set-ids */

==Introduction==

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

== Format ==

The data looks as follows:

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

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

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

{| |-
!'''Element'''!![[GRFActionsDetailed|'''Size''']]!!'''Description'''
|-
|<Sprite-number>||dec||A sequential sprite number
|-
|<length>||dec||The total number of bytes used in this action.
|-
|02||B||Defines action 02
|-
|<feature>||B||For what type of vehicle/station/... should this definition be used?
|-
|<set-id>||B||The ID of this action 2 (used like a cargo ID)
|-
|80, 83, 84||B||Type of random action, see below.
|-
|<count>||B||(when present) Location of controlling vehicle.
|-
|<random-triggers>||B||When to re-randomize
|-
|<randbit>||B||What random bit to use for this action 2
|-
|<nrand>||B||Number of set-ids to choose from, must be a power of 2
|-
|<set-ids>||W||Action 2 set-ids to choose from.
|}

== Description ==

=== Sprite-number ===

This is just the number you are at.

=== Length ===

Count the number of bytes in this action.

===Feature===

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

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

=== set-ID ===

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

=== 80/83/84 ===

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

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

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

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

=== count ===

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

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

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

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

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

=== random-triggers ===

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

Trigger bits are feature-specific, see below.

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

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

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

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

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

=== randbit ===

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

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

=== nrand ===

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

=== set-ids ===

The set-ids to randomly choose from.
{|
|-
!Set-id!!Version!!Meaning
|-
|0000..00FF|| ||Chain to the preceding Action2 with given group id.
|-
|7FFF||{{ottdp|15|no}}||Return "callback failed"/"sprite resolving failed".
|-
|8000..FEFF|| ||Return callback result with value 0000..7EFF.
|-
|FF00..FFFF||{{grf|≤7}}||Return callback result with value 00..FF.
|-
|8000..FFFF||{{grf|≥8}}||Return callback result with value 0000..7FFF.
|}

== Triggers ==

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

=== Vehicles ===

Vehicles have 8 random bits, increased to 16 since {{ottdp|14.0|no}}, and the following triggers:

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

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

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

=== Stations ===

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

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

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

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

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

=== Town building triggers ===

Town buildings have 8 random bits.

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

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

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

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

=== Industry tile triggers ===

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

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

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

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

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

=== Canals ===

Canals / Rivers have 8 random bits.

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

=== Objects ===

Objects have 8 random bits per tile of the object.

There are no triggers for objects however.

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

=== Railtypes ===

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

There are no triggers.

=== Roadtypes ===

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

There are no triggers.

=== Tramtypes ===

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

There are no triggers.

=== Road stops ===

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

{| |-
!Bit!!Value!!Version!!Trigger
|-
|0||01||{{ottdp|14}}||new cargo waiting
|-
|1||02||{{ottdp|14}}||no more cargo
|-
|2||04||{{ottdp|14}}||road vehicle arrives (starts unloading/loading)
|-
|3||08||{{ottdp|14}}||road vehicle leaves (done unloading & loading)
|-
|4||10||{{ottdp|14}}||road vehicle loads or unloads cargo
|}

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

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

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

=== Other features ===

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

==Example==

VariationalAction2

2025-05-13T13:15:41Z

Frosch: /* sets and ranges */

==Introduction==

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

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

== Format ==

The data looks as follows:

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

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

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

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

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

== Description ==

=== Sprite-number ===

This is just the number you are at.

=== Length ===

Count the number of bytes in this action.

=== Feature ===

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

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

=== Set-ID ===

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

=== Type ===

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

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

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

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

=== Variable ===

Variational Action 2 allows accessing these variables:

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

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

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

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

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

=== varadjust ===

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

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

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

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

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

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

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

=== nvar ===

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

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

=== sets and ranges ===

For each of the ranges to check, you give the set-id as a '''WORD''' value:
{|
|-
!Set-id!!Version!!Meaning
|-
|0000..00FF|| ||Chain to the preceding Action2 with given group id.
|-
|7FFE||{{ottdp|15|no}}||Return the result of an [[VarAction2Advanced|advanced]] calculation (or, if no calculation is performed, the adjusted variable value itself) as callback result, with bit 15 set. (same behaviour as the "nvar=0" case, but only for results in the range)
|-
|7FFF||{{ottdp|15|no}}||Return "callback failed"/"sprite resolving failed".
|-
|8000..FEFF|| ||Return callback result with value 0000..7EFF.
|-
|FF00..FFFF||{{grf|≤7}}||Return callback result with value 00..FF.
|-
|8000..FFFF||{{grf|≥8}}||Return callback result with value 0000..7FFF.
|}
The first range that matches will be used.

If there is an error during evaluating the variables (e.g. variable not available), the first range is picked.
The error case can be isolated by using an empty/invalid range, e.g. from 1 to 0.

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

=== default ===

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

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

</pre>

Action3

2025-05-13T12:55:36Z

Frosch: houses and other in purchase list

== Introduction ==

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

== Format ==

The format of the data is feature-dependent.

The data is:

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

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

== Description ==

=== Sprite-number ===

This is just the number you are at.

=== Length ===

Count the number of bytes in this action.

=== Feature ===

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

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

=== n-id ===

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

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

=== ids ===

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

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

Since OpenTTD 14.0, each ID is an extended byte for all features.

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

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

=== num-cid ===

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

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

=== cargo-type ===

{|
|-
! Feature !! cids
|-
| 00..03 vehicles ||
* 00..FE: cargo-type (index in [[Action0/Global Settings#Cargo translation table 09|cargo translation table]]; cargobit if no table present)
* FF: purchase list <ref>For dual-headed trains (prop 13) special rules for the purchase menu sprite apply: two sprites are drawn (for front and back) as if the vehicle is normally constructed. If you supply one purchase menu sprite, it will be used for both vehicle parts in the purchase menu. Provide a set of 8 sprites, and the 7th resp. 3rd sprite will
be drawn; provide a set of 8 blank sprites except the 7th if you want to fully control a single purchase menu sprite for a dual-headed engine.</ref>
* default: used if none of the listed cids apply
|-
| 04 stations ||
* 00..FD: cargo-type (index in [[Action0/Global Settings#Cargo translation table 09|cargo translation table]]; cargobit if no table present) waiting at the station. The waiting amount of this cargo is used in [[Action2/Stations|Action2]] to decide the spriteset.
* FE: used if none of the listed cids apply. [[Action2/Stations|Action2]] will assume "zero waiting cargo".
* FF: purchase list
* default: used if none of the listed cids apply. [[Action2/Stations|Action2]] will use "sum of all waiting cargos".
|-
| 05 canals || default only
|-
| 07 houses ||
* FF: {{ottdp|15|no}} purchase list (callbacks when not constructed yet; and house picker GUI)
* default: used if none of the listed cids apply
|-
| 09 industry tiles ||
* FF: {{ottdp|15|no}} purchase list (callbacks when not constructed yet)
* default: used if none of the listed cids apply
|-
| 0A industries ||
* FF: {{ottdp|15|no}} purchase list (callbacks when not constructed yet)
* default: used if none of the listed cids apply
|-
| 0B cargos || default only
|-
| 0C sound effects || default only
|-
| 0D airports ||
* FF: {{ottdp|15|no}} purchase list (callbacks when not constructed yet)
* default: used if none of the listed cids apply
|-
| 0E signals || default only
|-
| 0F objects ||
* FF: purchase list
* default: used if none of the listed cids apply
|-
| 10 rail types || special cids, see [[Action3/Railtypes#cargo-type|here]]
|-
| 11 airport tiles ||
* FF: {{ottdp|15|no}} purchase list (callbacks when not constructed yet)
* default: used if none of the listed cids apply
|-
| 12 road types || special cids, see [[Action3/Tramtypes#cargo-type|here]]
|-
| 13 tram types || special cids, see [[Action3/Roadtypes#cargo-type|here]]
|-
| 14 road stops ||
* 00..FD: cargo-type (index in [[Action0/Global Settings#Cargo translation table 09|cargo translation table]]; cargobit if no table present) waiting at the road stop.
* FE: used if none of the listed cids apply.
* FF: purchase list
* default: used if none of the listed cids apply.
|-
| 15 badges || special cids:
* 00..14: feature
* default: used if specific feature is not assigned.
|-
|}

<references/>

=== default set-ID ===

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

== Example ==

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

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

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

Action0/Industry Tiles

2025-04-26T14:29:49Z

Frosch: ottd 15 additions

==Introduction==

Industry tiles work similarly to town buildings, except that they are not stand-alone; they are always part of an industry.

Defining industry tiles follows the same schema as houses do: to start using an ID, you first need to define it by setting property 8 for it. If you try to reference an ID (either via action0 or via action3) that isn't defined, your request is ignored, but not reported as an error, either. This means that if you want to conditionally define an ID, all you need to do is skipping the action0 that sets property8, and everything else gets skipped automatically.

Industry tile IDs are unique within each grf file. The per-GRF ID is specified as a byte, which means no GRF can define more than 256 tile IDs. You should use your industry tile IDs sparingly. [[VariationalAction2/Industry_Tiles#Relative_position_.2843.29| Variational action 2 variable 43]] for industry tiles can help you limiting tile consumption to 2 or 3 per industry. Avoid using tile FFh, so the tileID can be turned into an extended byte (in Action 3) in the distant future without breaking your NewGRF.

{{ttdp|}} In total, TTDPatch can have up to a total of 256 new industry tile IDs (i.e. old tile types don't count).

{{ottd|}} OpenTTD can have 512 IDs for all active grf files, but that includes non-overridden original tiles.

== Properties ==

{| |-
!Property !![[GRFActionsDetailed|Size]] !!Version !! Description
|-
|08||B||{{ottdp|0.6|2.5|ttdprev=alpha 43}}||Substitute building type
|-
|09||B||{{ottdp|0.6|2.5|ttdprev=alpha 43}}||Industry tile override
|-
|0A,0B,0C||W||{{ottdp|0.6|2.5}}||Tile acceptance
|-
|0D||B||{{ottdp|0.6|2.5|ttdprev=alpha 49}}||Land shape flags
|-
|0E||B||{{ottdp|0.6|2.5|ttdprev=alpha 54}}||Callback flags
|-
|0F||W||{{ottdp|0.6|2.5|ttdprev=alpha 54}}||Animation information
|-
|10||B||{{ottdp|0.6|2.5|ttdprev=alpha 54}}||Animation speed.
|-
|11||B||{{ottdp|0.6|2.5|ttdprev=alpha 54}}||Triggers for callback 25
|-
|12||B||{{ottdp|0.6|2.5|ttdprev=beta 2}}||Special flags
|-
|13||V||{{ottdp|1.9|no|ottdrev=e66cec8f}}||Tile acceptance list
|-
|14||W n*W||{{ottdp|15}}||List of badges
|}

== Description ==

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

This tile type will be used instead of your new one if your definition isn't available for any reason. Valid values are [http://marcin.ttdpatch.net/sv1codec/TTD-locations.html#Class8 00h-AEh]. Assigning this property copies the properties of the old type just like it does with houses.

If this tile's action 3 appears before this property is set, the action 3 will have no effect.

=== Industry tile override (09) ===

Works like the house override property for houses.

=== Tile acceptance (0A, 0B, 0C) ===

These three words define what cargoes the tile accepts, and how much of them. The low byte defines the type of the cargo according to the current climate, while the high byte defines the degree of acceptance in 1/8 units. If you don't need all three cargo types, just zero out the high byte of the extra properties.

{{grfFrom|7}} From GRF version 7 and above, the meaning of the low byte changes: instead of a climate-dependent cargo slot number, you have to give a climate-independent cargo ID. If your GRF has a cargo translation table, then this ID is the index in that table; otherwise, it's the cargo bit. Acceptance of cargoes not currently present will automatically be disabled.

{{ottdp|1.9|no|ottdrev=e66cec8f}} These properties only support three cargos. Use property 13 instead to list more cargo types.

=== Land shape flags (0D) ===

This property defines which slopes the tile can be built on.

{| |-
!Bit!!Value!!Version!!Meaning
|-
|0||1||{{ottdp|0.6|2.5}}||NW edge cannot be lowered
|-
|1||2||{{ottdp|0.6|2.5}}||NE edge cannot be lowered
|-
|2||4||{{ottdp|0.6|2.5}}||SW edge cannot be lowered
|-
|3||8||{{ottdp|0.6|2.5}}||SE edge cannot be lowered
|-
|4||10||{{ottdp|0.6|2.5}}||Can only be built on flat land
|-
|5||20||{{ottdp|0.6|2.5|ttdprev=alpha 58}}||The tile is allowed on both land and water
|}

Industry tiles are never built on steep slopes unless [[Callbacks#Custom shape check (2F) |callback 2F]] is enabled, but bits 0..4 are ignored in that case.

Bit 5 can be used to allow tiles of land industries built on water or vice versa. It effectively disables the land/water check code for the tile. If you need to customize the behavior further, you can use [[Callbacks#Custom shape check (2F) |callback 2F]] to decide what kind of water/land is allowed.

;'''PLEASE NOTE''': Be careful when setting this property. If you fail to set it correctly, your industry may end up building on a hillside, which is probably not what you want. The easiest way is to set bit 4 for middle tiles, bit 0 for the tiles along the SE edge, bit 1 for those along the SW edge and so on.

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

{| |-
!Bit!!value!!version!!meaning
|-
|0||1||{{ottdp| | }}||use [[Callbacks#Next animation frame (1A/26/141/153/158) |callback 26]] to decide the next animation frame
|-
|1||2||{{ottdp| | }}||use [[Callbacks#Length of animation frame (20/27/142/154/15A) |callback 27]] to decide animation speed
|-
|2||4||{{ottdp| |2.5|ttdprev=alpha 55 vcs 3}}||use [[Callbacks#Decide cargo acceptance (2B) |callback 2B]] to decide amount of acceptance
|-
|3||8||{{ottdp| |2.5|ttdprev=alpha 55 vcs 3}}||use [[Callbacks#Get accepted cargo types (2A/2C) |callback 2C]] to decide accepted types
|-
|4||10||{{ottdp| | }}||use [[Callbacks#Custom shape check (2F) |callback 2F]] to check if a slope is suitable
|-
|5||20||{{ottdp| | }}||use [[Callbacks#Decide drawing default foundations (30/14E/150) |callback 30]] to decide if default foundations need to be drawn
|-
|6||40||{{ottdp| |2.5|ttdprev=beta 3}}||use [[Callbacks#Disable autosloping (3C/14F/15D) |callback 3C]] to allow or deny autosloping below the tile
|}

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

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

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

=== Animation speed (10) ===

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

=== Triggers for [[Callbacks#Animation control (1B/25/140/152/159) |callback 25]] (11) ===

Call [[Callbacks#Animation control (1B/25/140/152/159) |callback 25]] when:

{| |-
!Property bit, var 18 byte 0!!Property value!!Version!!Meaning||Happens on||Var 18 byte 1
|-
|0||1||{{ottdp|0.6|2.5}}||the construction state changes <ref>During normal gameplay called 4 times per tile. During map generation called 1 time. {{ttdp|}} For the first call to happen, you also have to set [[Action0/Industry_Tiles#Animation_information_.280F.29|property 0F]] to some other value than 0xFFFF.</ref>||single tile||{{ottdp|15|no}} First call <ref>Var 18 bit 8 is set, if the callback is called the first time for a new industry. In-game the construction stage will be zero, at map generation and in scenario editor, it will be 3. Other bits of var 18 are reserved, and must be masked.</ref>
|-
|1||2||{{ottdp|0.6|2.5}}||the tile is processed in the periodic processing loop||single tile||
|-
|2||4||{{ottdp|0.6|2.5}}||the industry of the tile is processed in the periodic processing loop (synchronized animation)||all tiles||
|-
|3||8||{{ottdp|0.6|2.5}}||the industry of the tile receives input cargo from a station||all tiles||
|-
|4||10||{{ottdp|0.6|2.5|ttdprev=beta 2}}||the industry distributes its output cargo to one of the stations nearby||all tiles||
|}
<references />

Currently no trigger provides additional information in var 18 bytes 1 to 3.

=== Special flags (12) ===

{| |-
!Bit!!Value!!Meaning
|-
|0||1||[[Callbacks#Next animation frame (1A/26/141/153/158) |Callback 26]] needs random bits
|-
|1||2||{{ottdp|1.9|no|ottdrev=e66cec8f}} In addition to the cargotypes set by property 0A..0C and 13, the tile accepts all cargotypes which the industry accepts.
* This considers industry properties 11 and 26 and callback 14B.
* This does not consider industry callback 3D.
* This property adds 8/8 acceptance for the matching cargotypes. You can list negative acceptances (-8/8) in property 13 to exclude specific cargos.
* Tile callback 2C overrides all acceptances including those added by this flag.
|}

=== Tile acceptance list (13) ===
{{ottdp|1.9|no|ottdrev=e66cec8f}}

Format:
<numinput> (<cargotype> <acceptance>)*

{| |-
!Size!!Variable!!Meaning
|-
|B||numinput||Number of (<cargotype> <acceptance>) pairs to follow,
|-
|B||cargotype||Cargotype (from CTT) to accept.
|-
|B||acceptance||Acceptance in 1/8 units. May be negative to negate property 12 bit 1.
|}

This property defines up to 16 cargotypes, which are accepted by the industry tile.
Use this property instead of property 0A..0C.

==Example==

Action0/Stations

2025-04-26T14:27:35Z

Frosch: ottd 15 additions

==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/B*||{{ottdp|0.6|2.5|ttdprev=alpha 20}}/{{ottdp|14.0}}||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/B*||{{ottdp|0.6|2.5|ttdprev=alpha 22}}/{{ottdp|14.0}}||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
|-
|1A||V||{{ottdp|1.2|no|ottdrev=r22518}}||Advanced sprite layout with register modifiers
|-
|1B|| || ||Reserved
|-
|1C||W||{{ottdp|14}}||Station name
|-
|1D||W||{{ottdp|14}}||Station class name
|-
|1E||V||{{ottdp|15}}||Station sprite layout flags
|-
|1F||W n*W||{{ottdp|15}}||List of badges
|}

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.

{{ottdp|15}} Station classes which start with the byte FF are considered waypoint classes, and will appear in the waypoint construction window instead of the station construction window.

When a waypoint station is built, it will not accept cargo nor will any cargo appear from nearby industries or towns.  Trains will not stop at waypoint 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.

Since {{ottdp|14.0}} this property is now an extended byte.

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

Since {{ottdp|15}}, all even values up to FE are supported if the sprite layout is defined via property 09/0A.

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.

Since {{ottdp|14.0}} this property is now an extended byte.

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

{{ottdp|15}} Note: This property only allows setting the flags of the first 8 sprite layouts. Use Property 1E instead to set flags when more sprite layouts are used via prop. 0E or [[Callbacks#Custom_station_layout_.2824.29|callback 24]].

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

{{ottd|15.0}} Since 15.0, a default cargo translation table corresponding to the climate is used if one is not provided.

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

{{ottdp|15}} Note: This property only allows setting the flags of the first 8 sprite layouts. Use Property 1E instead to set flags when more sprite layouts are used via prop. 0E or [[Callbacks#Custom_station_layout_.2824.29|callback 24]].

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

{| |-
!Property bit, var18 byte 0!!Property value!!Version!!Meaning!!Happens on!!Var 18 byte 1
|-
|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||Cargo type <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||Cargo type <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||
|-
|7||80||{{ottdp|15|no}}||Tile is processed in the periodic processing loop||single tile||
|-
|8||100||{{ottdp|15|no}}||Train reserves platform (using PBS)||platform where the train reserved||
|}

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

=== 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 [https://wiki.openttd.org/en/Archive/Development/Advanced%20Sprite%20Layout#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> 
1B x1 y1 x2 y2 x3 y3 x4 y4 
1B 01 01 02 02 03 03 03 03 // 8px 16px 24px 24px

This property is currently only available for JGR's Patch Pack (v0.26.0 and later) and the developmental "New Map Features" (NMF) fork of OpenTTD.

=== Station name (1C) ===

=== Station class name (1D) ===

=== Station sprite layout flags (1E) ===

{{ottdp|15}} Since OpenTTD supports more than 8 sprite layouts to be used, props. 11, 14 and 15 are not sufficient to set the flags for all usable sprite layouts. This property is variable length and allows these flags to be set for each tile beyond the original limit of 8.

The data is specified as flags for all sprite layouts in this way:

<pre><num> <flags1> <flags2> ... <flagsn></pre>

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

The flag values are as follows:

{| |-
|Bit||Value||Meaning
|-
|0||01||Tile should contain catenary pylons.
|-
|1||02||Tile should NOT contain catenary wires.
|-
|2||04||Tile is blocked to vehicles.
|}

These should be combined as needed.

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

Callback: Animation control

2025-04-26T14:24:20Z

Frosch: ottd 15 additions

== Animation control (1B/1C/25/140/148/152/159) ==

These callbacks are called, when an animation trigger happens.

{| |-
!Callback!!Feature!!Mask property!!Trigger!!Variable 10!!Variable 18
|-
|1B||Houses
|[[Action0/Houses#House_callback_flags_.2814.2C1D.29|Property 14 bit 2]]
|[[Action0/Houses#Periodic_refresh_multiplier_.2816.29|Periodic, see property 16]] <ref>For multi-tile houses [[Action0/Houses#Extra_Flags_.2819.29|property 19 bit 2]] controls, whether the trigger is synchronised across all house tiles. See details there.</ref>
|{{ottdp| |2.5|ttdprev=beta 2}} Random bits <ref>Lower 16 bits are random per tile. Upper 16 bits are the same for all tiles, if [[Action0/Houses#Extra_Flags_.2819.29|property 19 bit 2]] is set.</ref>
|Reserved for future use
|-
|1C||Houses
|[[Action0/Houses#House_callback_flags_.2814.2C1D.29|Property 14 bit 3]]
|[[VariationalAction2/Houses#Construction_stage_and_pseudo-random_values_.2840.29|Construction stage]] changes <ref>During normal gameplay called 4 times per tile. During map generation called 1 time. {{ttdp|}} For the first call to happen, you also have to set [[Action0/Houses#Building_flags_.2809.29|property 9 bit 5]].</ref>
|{{ottdp|15|no}} Random bits
|{{ottdp|15|no}} First call <ref>Var 18 bit 0 is set, if the callback is called the first time for a new house. In-game the construction stage will be zero, at map generation and in scenario editor, it will be 3. Other bits of var 18 are reserved, and must be masked.</ref>
|-
|25||Industry tiles
|[[Action0/Industry_Tiles#Triggers_for_callback_25_.2811.29|Property 11]]
|All triggers, see variable 18
|{{ottdp| |2.5|ttdprev=beta 2}} Random bits <ref name="randombits">Lower 16 bits are random per tile. Upper 16 bits are the same for all tiles, if the trigger applies to multiple tiles.</ref>
|Trigger and more, see [[Action0/Industry_Tiles#Triggers_for_callback_25_.2811.29|property 11]]
|-
|140||Stations, road stops
|[[Action0/Stations#Animation_triggers_.2818.29|Station property 18]], [[Action0/Road_Stops#Animation_triggers_.2810.29|road stop property 10]]
|All triggers, see variable 18
|{{ottdp| |2.5|ttdprev=beta 2}} Random bits <ref name="randombits" />
|Trigger and more, see [[Action0/Stations#Animation_triggers_.2818.29|station property 18]]
|-
|148||Houses
|[[Action0/Houses#Cargo_acceptance_watch_list_.2820.29|Property 1E]]
|Watched cargo accepted <ref>Due to implementation details, up to 250 game ticks can pass between the actual acceptance and triggering this callback.</ref>
|Reserved for future use
|See [[Action0/Houses#Cargo_acceptance_watch_list_.2820.29|property 1E]]
|-
|154||Airport tiles
|[[Action0/Airport_Tiles#Animation_triggers_via_callback_152_.2811.29|Property 11]]
|All triggers, see variable 18
|Random bits <ref name="randombits15">{{ottdp|15|no}} Lower 16 bits are random per tile. Upper 16 bits are the same for all tiles, if the trigger applies to multiple tiles.</ref>
|Trigger and more, see [[Action0/Airport_Tiles#Animation_triggers_via_callback_152_.2811.29|property 11]]
|-
|159||Objects
|[[Action0/Objects#Animation_triggers_.2813.29|Property 13]]
|All triggers, see variable 18
|Random bits <ref name="randombits15" />
|Trigger and more, see [[Action0/Objects#Animation_triggers_.2813.29|property 13]]
|}
<references />

The return value has the format SSFF:
* FF: One of the following values:
: {| |-
!Value!!Meaning
|-
|00 - FC||Jump to this animation frame.
|-
|FD||leave the animation in its current state (do nothing)
|-
|FE||start animation with its current frame
|-
|FF||stop animation in its current frame
|}
* SS: Sound effect: If non-zero, the sound effect number to play at the tile.

Note: Every time the animation frame is changed the map tile will be refreshed, even if the selected graphics stay the same. Therefore using the animation frame as a timer should be avoided, and animation triggers should be preferred instead.

[[Category:Callbacks]]

Callback: Animation control

2025-04-25T10:31:41Z

Frosch: /* Animation control (1B/1C/25/140/148/152/159) */

== Animation control (1B/1C/25/140/148/152/159) ==

These callbacks are called, when an animation trigger happens.

{| |-
!Callback!!Feature!!Mask property!!Trigger!!Variable 10!!Variable 18
|-
|1B||Houses
|[[Action0/Houses#House_callback_flags_.2814.2C1D.29|Property 14 bit 2]]
|[[Action0/Houses#Periodic_refresh_multiplier_.2816.29|Periodic, see property 16]] <ref>For multi-tile houses [[Action0/Houses#Extra_Flags_.2819.29|property 19 bit 2]] controls, whether the trigger is synchronised across all house tiles. See details there.</ref>
|{{ottdp| |2.5|ttdprev=beta 2}} Random bits <ref>Lower 16 bits are random per tile. Upper 16 bits are the same for all tiles, if [[Action0/Houses#Extra_Flags_.2819.29|property 19 bit 2]] is set.</ref>
|Reserved for future use
|-
|1C||Houses
|[[Action0/Houses#House_callback_flags_.2814.2C1D.29|Property 14 bit 3]]
|[[VariationalAction2/Houses#Construction_stage_and_pseudo-random_values_.2840.29|Construction stage]] changes <ref>During normal gameplay called 4 times per tile. During map generation called 1 time. {{ttdp|}} For the first call to happen, you also have to set [[Action0/Houses#Building_flags_.2809.29|property 9 bit 5]].</ref>
|Reserved for future use
|Reserved for future use
|-
|25||Industry tiles
|[[Action0/Industry_Tiles#Triggers_for_callback_25_.2811.29|Property 11]]
|All triggers, see variable 18
|{{ottdp| |2.5|ttdprev=beta 2}} Random bits <ref name="randombits">Lower 16 bits are random per tile. Upper 16 bits are the same for all tiles, if the trigger applies to multiple tiles.</ref>
|Trigger and more, see [[Action0/Industry_Tiles#Triggers_for_callback_25_.2811.29|property 11]]
|-
|140||Stations, road stops
|[[Action0/Stations#Animation_triggers_.2818.29|Station property 18]], [[Action0/Road_Stops#Animation_triggers_.2810.29|road stop property 10]]
|All triggers, see variable 18
|{{ottdp| |2.5|ttdprev=beta 2}} Random bits <ref name="randombits" />
|Trigger and more, see [[Action0/Stations#Animation_triggers_.2818.29|station property 18]]
|-
|148||Houses
|[[Action0/Houses#Cargo_acceptance_watch_list_.2820.29|Property 1E]]
|Watched cargo accepted <ref>Due to implementation details, up to 250 game ticks can pass between the actual acceptance and triggering this callback.</ref>
|Reserved for future use
|See [[Action0/Houses#Cargo_acceptance_watch_list_.2820.29|property 1E]]
|-
|154||Airport tiles
|[[Action0/Airport_Tiles#Animation_triggers_via_callback_152_.2811.29|Property 11]]
|All triggers, see variable 18
|Random bits <ref name="randombits15">{{ottdp|15|no}} Lower 16 bits are random per tile. Upper 16 bits are the same for all tiles, if the trigger applies to multiple tiles.</ref>
|Trigger and more, see [[Action0/Airport_Tiles#Animation_triggers_via_callback_152_.2811.29|property 11]]
|-
|159||Objects
|[[Action0/Objects#Animation_triggers_.2813.29|Property 13]]
|All triggers, see variable 18
|Random bits <ref name="randombits15" />
|Trigger and more, see [[Action0/Objects#Animation_triggers_.2813.29|property 13]]
|}
<references />

The return value has the format SSFF:
* FF: One of the following values:
: {| |-
!Value!!Meaning
|-
|00 - FC||Jump to this animation frame.
|-
|FD||leave the animation in its current state (do nothing)
|-
|FE||start animation with its current frame
|-
|FF||stop animation in its current frame
|}
* SS: Sound effect: If non-zero, the sound effect number to play at the tile.

Note: Every time the animation frame is changed the map tile will be refreshed, even if the selected graphics stay the same. Therefore using the animation frame as a timer should be avoided, and animation triggers should be preferred instead.

[[Category:Callbacks]]

Action0/Objects

2025-04-24T18:45:09Z

Frosch: /* Animation triggers (13) */

==Introduction==
Defining properties of new objects.

Unlike vehicles or new stations, most new objects have no real equivalent in TTD.

The IDs are therefore free to be chosen and will in fact be allocated automatically by the patch. In action 0, you only specify IDs relative to the set, i.e. the ID of the first object type is 00, the second object type is 01 and so on.

OpenTTD supports 64000 object types per game, and 255 object IDs per grf file.

{{ottdp|14.0|no}} 64000 object IDs per grf file are supported since OpenTTD 14.0.

The property you '''must''' set for each object ID is 08 (in addition to defining an action 3 for it). Also, all object IDs must get their classes in the right order, starting from ID 00 onwards.

== Properties ==
{|
!Number!![[GRFActionsDetailed|Size]]!!Version!!Description
|-
|08||D||{{ottdp|1.1|2.6|ottdrev=r20670|ttdprev=r2340}}||Class label, see below
|-
|09||W||{{ottdp|1.1|2.6|ottdrev=r20670|ttdprev=r2340}}||Text ID for class
|-
|0A||W||{{ottdp|1.1|2.6|ottdrev=r20670|ttdprev=r2340}}||Text ID for this object
|-
|0B||B||{{ottdp|1.1|2.6|ottdrev=r20670|ttdprev=r2340}}||[[Action0General#Climate availability|Climate availability]]
|-
|0C||B||{{ottdp|1.1|2.6|ottdrev=r20670|ttdprev=r2340}}||Byte representing size, see below
|-
|0D||B||{{ottdp|1.1|2.6|ottdrev=r20670|ttdprev=r2340}}||Object build cost factor (sets object removal cost factor as well)
|-
|0E||D||{{ottdp|1.1|2.6|ottdrev=r20670|ttdprev=r2340}}||Introduction date, see below
|-
|0F||D||{{ottdp|1.1|2.6|ottdrev=r20670|ttdprev=r2340}}||End of life date, see below
|-
|10||W||{{ottdp|1.1|2.6|ottdrev=r20670|ttdprev=r2340}}||Object flags, see below
|-
|11||W||{{ottdp|1.1|2.6|ottdrev=r20670|ttdprev=r2340}}||Animation information
|-
|12||B||{{ottdp|1.1|2.6|ottdrev=r20670|ttdprev=r2340}}||Animation speed
|-
|13||W||{{ottdp|1.1|2.6|ottdrev=r20670|ttdprev=r2340}}||Animation triggers
|-
|14||B||{{ottdp|1.1|2.6|ottdrev=r20670|ttdprev=r2340}}||Object removal cost factor (set after object build cost factor)
|-
|15||W||{{ottdp|1.1|2.6|ottdrev=r20670|ttdprev=r2340}}||Callback flags, see below
|-
|16||B||{{ottdp|1.1|2.6|ottdrev=r20670|ttdprev=r2340}}||Height of the building
|-
|17||B||{{ottdp|1.1|2.6|ottdrev=r20670|ttdprev=r2340}}||Number of object views
|-
|18||B||{{ottdp|1.4|no|ottdrev=r25879}}||Measure for number of objects placed upon map creation
|-
|19||W n*W||{{ottdp|15}}||List of badges
|}

Check [http://pics.lakie.net/newObject-ActionStructure.png Lakie's Graphical Representation of the newObject Specifications]

== Descriptions ==

=== Object class (08) ===

Class labels are unique identifiers composed of the letters A-Z and/or the numbers 0-9,  analoguous to [[Action0Stations#Station class (08)|station class labels]].

Their main use is to combine objects into classes and make them available by the top dropdown list in the object construction window.

Unlike for stations, there is no default class for objects. Set authors have to specify their [[ObjectLabels|own labels]], although it is strongly recommended to follow a general scheme to try to avoid confusion.

Class IDs must be set before any other property.

=== Object class text ID (09) ===

The text ID for this class (word value). This textid should be either a TTD textid or a D4xx textid (set via D0xx in action4).

When specifying an object, you don't need to set a class name again if you already did for another one with the same class.

=== Object text ID (0A) ===

The text ID for the object for query and selection (word value). Same requirements as for property09.

=== Object size (0C) ===

The object size up to 15x15 tiles.

This byte value is divided into two nibbles. The first defines the size in y direction and the second defines the size in x (i.e., stored as YX).

Note that any value lower than 0x11 will be rejected.

=== Build Cost (0D) ===

The build cost multiplier. This is multiplied by the number of tiles for evaluation of construction and removal costs of an object.

=== Introduction date (0E) ===

Introduction date of an object, in days since the year 0. This takes account of leap years; divisible by 4, but not 100 unless 400. A start date of 1920-01-01 is obtained with a value of 701265 (51 B3 0A 00). In TTDPatch anything before 1920 is considered to be always available, and it should allow for objects to work past 2044, the date is also the very first date you can build the object.

=== End of life date (0F) ===

Last year an object can be build, in days since the year 0. Same requirements as above. Also note that it must be a minimum of a year (365 days) after the introduction date or TTDPatch will ignore it.

=== Object flags (10) ===

The following flags control object behaviour and are cached for built objects, so changing these flags will have no effect on already constructed objects.

{|
!Bit!!Value!!Version!!Meaning
|-
|0||1||{{ottdp|1.1|2.6|ottdrev=r20670|ttdprev=r2340}}||Only Available in the scenario editor<ref name="incompatible">Note that bits 0 and 7 are incompatible and setting both will make an object completely unavailable.</ref>
|-
|1||2||{{ottdp|1.1|2.6|ottdrev=r20670|ttdprev=r2340}}||Irremovable<ref>Object cannot be removed through normal dynamite, control must be held and the removal cost will be multiplied by 25 (this is the usual behaviour for most class A objects in TTDPatch).</ref>
|-
|2||4||{{ottdp|1.1|2.6|ottdrev=r20670|ttdprev=r2340}}||Anything Can Remove (owned land behaviour)
|-
|3||8||{{ottdp|1.1|2.6|ottdrev=r20670|ttdprev=r2340}}||Allow construction of the object on water
|-
|4||16||{{ottdp|1.1|2.6|ottdrev=r20670|ttdprev=r2340}}||Removal cost is actually income (owned land behaviour)
|-
|5||32||{{ottdp|1.1|2.6|ottdrev=r20670|ttdprev=r2340}}||Do not display foundations if on a slope
|-
|6||64||{{ottdp|1.1|2.6|ottdrev=r20670|ttdprev=r2340}}||Object has animation<ref>Setting this flag will allow the object's animation counter to be increased, must be set if you plan to make use of animations. Like stations you must enable animation on a per tile basis by means of the "built tile" trigger and callback 159.</ref>
|-
|7||128||{{ottdp|1.1|2.6|ottdrev=r20670|ttdprev=r2340}}||Only available during game play<ref name="incompatible" />
|-
|8||256||{{ottdp|1.1|2.6|ottdrev=r20670|ttdprev=r2340}}||Allows 2cc mapping for objects instead of the default 1cc
|-
|9||512||{{ottdp|1.1|2.6|ttdprev=r2331}}||Disallows construction on land (also has bit 3 behaviour)
|-
|10||1024||{{ottdp|1.1|2.6|ttdprev=r2331}}||Draws the water under the object<ref>Only applies when built on top of a water tile, also replaces the ground tile of the object completely. (Does not work when object built on sloped water tiles).</ref>
|-
|11||2048||{{ottdp|1.1|no|ottdrev=r21455}}||Allow bridge over the object taking the building height into account
|-
|12||4096||{{ottdp|1.1|2.6|ottdrev=r21455|ttdprev=r2360}}||Random bits in the "next animation frame" callback
|-
|13||8192||{{ottdp|1.4|no|ottdrev=r25878}}||Scale amount of objects placed on map generation not by map area, but roughly by the length of the coastline
|}

<references />

=== Animation information (11) ===

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 object (this is the default value).

Since you can't have properties for individual object tiles, this property applies for every tile of the object. 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 159]] 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 158]] for that.

=== Animation speed (12) ===

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

=== Animation triggers (13) ===

This is a bit mask of events that should trigger [[Callbacks#Animation control (1B/25/140/152/159)|callback 159]], allowing to change the animation state

{|
!Property bit, var18 byte 0!!Property value!!Meaning!!Happens on!!Var 18 byte 1
|-
|0||1||Object is built||all tiles||
|-
|1||2||Periodic tile loop||single tile||
|-
|2||4||Synchronised periodic tile loop||all tiles||
|}
Currently no trigger provides additional information in var 18 byte 1.

The synchronised periodic tile loop is called directly after the (unsynchronised) periodic tile loop of the northern tile.

=== Object removal cost factor (14) ===

Cost factor for the removal of an object. This must be set after property 0D (object build cost factor) as that overwrites this value.

=== Callback flags (15) ===

For objects, the following [[callbacks]] can be defined by setting the corresponding bit in property 15:

{|
!Bit!!Value!!Variable 0C value!!Callback
|-
|0||1||157||Custom slope check
|-
|1||2||158||Decide next animation frame
|-
|2||4||15A||Decide animation speed
|-
|3||8||15B||Decide colour of building
|-
|4||16||15C||Show additional text in the build object window
|-
|5||32||15D||Allow/disallow autosloping
|}

=== Building height (16) ===

Set the height of the building in heightlevels (8 pixels). For example if the structure is 16 pixels high you set this property to 2.

{{ottdp|1.1|no|ottdrev=r21455}} In OpenTTD this property is used to determine the height of the build object window; the height for the object preview is set to 32 + "value of property 16" * 8. The property is also uses to determine how high a bridge must be if it is allowed by the bit in property 10.

=== Number of views (17) ===

Objects may have "views", i.e. different graphical representations, e.g. used to show rotated views of an object. Number of views may be 1, 2, or 4. Default value is 1.

For non-square objects, x and y sizes are swapped for odd views. I.e., giving an object size of 1*2 (x = 1, y = 2), it will be displayed as 1*2 for num = <nowiki>[</nowiki>0,2] (x-direction) but as 2*1 for num = <nowiki>[</nowiki>1,3] (y-direction).

Use object varaction2 var48 to access particular views of an object.
==Examples==

Action0/Airport Tiles

2025-04-24T18:44:23Z

Frosch: /* Animation triggers via callback 152 (11) */

== Introduction ==

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

== Properties ==

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

== Descriptions ==

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

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

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

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

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

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

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

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

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

=== Animation speed (10) ===

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

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

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

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

<references/>

== Example ==

Action0/Stations

2025-04-24T18:42:44Z

Frosch: /* Animation triggers (18) */

==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/B*||{{ottdp|0.6|2.5|ttdprev=alpha 20}}/{{ottdp|14.0}}||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/B*||{{ottdp|0.6|2.5|ttdprev=alpha 22}}/{{ottdp|14.0}}||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
|-
|1A||V||{{ottdp|1.2|no|ottdrev=r22518}}||Advanced sprite layout with register modifiers
|-
|1B|| || ||Reserved
|-
|1C||W||{{ottdp|14}}||Station name
|-
|1D||W||{{ottdp|14}}||Station class name
|-
|1E||V||{{ottdp|15}}||Station sprite layout flags
|-
|1F||W n*W||{{ottdp|15}}||List of badges
|}

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.

{{ottdp|15}} Station classes which start with the byte FF are considered waypoint classes, and will appear in the waypoint construction window instead of the station construction window.

When a waypoint station is built, it will not accept cargo nor will any cargo appear from nearby industries or towns.  Trains will not stop at waypoint 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.

Since {{ottdp|14.0}} this property is now an extended byte.

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

Since {{ottdp|15}}, all even values up to FE are supported if the sprite layout is defined via property 09/0A.

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.

Since {{ottdp|14.0}} this property is now an extended byte.

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

{{ottdp|15}} Note: This property only allows setting the flags of the first 8 sprite layouts. Use Property 1E instead to set flags when more sprite layouts are used via prop. 0E or [[Callbacks#Custom_station_layout_.2824.29|callback 24]].

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

{{ottd|15.0}} Since 15.0, a default cargo translation table corresponding to the climate is used if one is not provided.

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

{{ottdp|15}} Note: This property only allows setting the flags of the first 8 sprite layouts. Use Property 1E instead to set flags when more sprite layouts are used via prop. 0E or [[Callbacks#Custom_station_layout_.2824.29|callback 24]].

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

{| |-
!Property bit, var18 byte 0!!Property value!!Version!!Meaning!!Happens on!!Var 18 byte 1
|-
|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||Cargo type <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||Cargo type <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/>

=== 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 [https://wiki.openttd.org/en/Archive/Development/Advanced%20Sprite%20Layout#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> 
1B x1 y1 x2 y2 x3 y3 x4 y4 
1B 01 01 02 02 03 03 03 03 // 8px 16px 24px 24px

This property is currently only available for JGR's Patch Pack (v0.26.0 and later) and the developmental "New Map Features" (NMF) fork of OpenTTD.

=== Station name (1C) ===

=== Station class name (1D) ===

=== Station sprite layout flags (1E) ===

{{ottdp|15}} Since OpenTTD supports more than 8 sprite layouts to be used, props. 11, 14 and 15 are not sufficient to set the flags for all usable sprite layouts. This property is variable length and allows these flags to be set for each tile beyond the original limit of 8.

The data is specified as flags for all sprite layouts in this way:

<pre><num> <flags1> <flags2> ... <flagsn></pre>

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

The flag values are as follows:

{| |-
|Bit||Value||Meaning
|-
|0||01||Tile should contain catenary pylons.
|-
|1||02||Tile should NOT contain catenary wires.
|-
|2||04||Tile is blocked to vehicles.
|}

These should be combined as needed.

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

Action0/Industry Tiles

2025-04-24T18:41:19Z

Frosch: /* Triggers for callback 25 (11) */

==Introduction==

Industry tiles work similarly to town buildings, except that they are not stand-alone; they are always part of an industry.

Defining industry tiles follows the same schema as houses do: to start using an ID, you first need to define it by setting property 8 for it. If you try to reference an ID (either via action0 or via action3) that isn't defined, your request is ignored, but not reported as an error, either. This means that if you want to conditionally define an ID, all you need to do is skipping the action0 that sets property8, and everything else gets skipped automatically.

Industry tile IDs are unique within each grf file. The per-GRF ID is specified as a byte, which means no GRF can define more than 256 tile IDs. You should use your industry tile IDs sparingly. [[VariationalAction2/Industry_Tiles#Relative_position_.2843.29| Variational action 2 variable 43]] for industry tiles can help you limiting tile consumption to 2 or 3 per industry. Avoid using tile FFh, so the tileID can be turned into an extended byte (in Action 3) in the distant future without breaking your NewGRF.

{{ttdp|}} In total, TTDPatch can have up to a total of 256 new industry tile IDs (i.e. old tile types don't count).

{{ottd|}} OpenTTD can have 512 IDs for all active grf files, but that includes non-overridden original tiles.

== Properties ==

{| |-
!Property !![[GRFActionsDetailed|Size]] !!Version !! Description
|-
|08||B||{{ottdp|0.6|2.5|ttdprev=alpha 43}}||Substitute building type
|-
|09||B||{{ottdp|0.6|2.5|ttdprev=alpha 43}}||Industry tile override
|-
|0A,0B,0C||W||{{ottdp|0.6|2.5}}||Tile acceptance
|-
|0D||B||{{ottdp|0.6|2.5|ttdprev=alpha 49}}||Land shape flags
|-
|0E||B||{{ottdp|0.6|2.5|ttdprev=alpha 54}}||Callback flags
|-
|0F||W||{{ottdp|0.6|2.5|ttdprev=alpha 54}}||Animation information
|-
|10||B||{{ottdp|0.6|2.5|ttdprev=alpha 54}}||Animation speed.
|-
|11||B||{{ottdp|0.6|2.5|ttdprev=alpha 54}}||Triggers for callback 25
|-
|12||B||{{ottdp|0.6|2.5|ttdprev=beta 2}}||Special flags
|-
|13||V||{{ottdp|1.9|no|ottdrev=e66cec8f}}||Tile acceptance list
|-
|14||W n*W||{{ottdp|15}}||List of badges
|}

== Description ==

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

This tile type will be used instead of your new one if your definition isn't available for any reason. Valid values are [http://marcin.ttdpatch.net/sv1codec/TTD-locations.html#Class8 00h-AEh]. Assigning this property copies the properties of the old type just like it does with houses.

If this tile's action 3 appears before this property is set, the action 3 will have no effect.

=== Industry tile override (09) ===

Works like the house override property for houses.

=== Tile acceptance (0A, 0B, 0C) ===

These three words define what cargoes the tile accepts, and how much of them. The low byte defines the type of the cargo according to the current climate, while the high byte defines the degree of acceptance in 1/8 units. If you don't need all three cargo types, just zero out the high byte of the extra properties.

{{grfFrom|7}} From GRF version 7 and above, the meaning of the low byte changes: instead of a climate-dependent cargo slot number, you have to give a climate-independent cargo ID. If your GRF has a cargo translation table, then this ID is the index in that table; otherwise, it's the cargo bit. Acceptance of cargoes not currently present will automatically be disabled.

{{ottdp|1.9|no|ottdrev=e66cec8f}} These properties only support three cargos. Use property 13 instead to list more cargo types.

=== Land shape flags (0D) ===

This property defines which slopes the tile can be built on.

{| |-
!Bit!!Value!!Version!!Meaning
|-
|0||1||{{ottdp|0.6|2.5}}||NW edge cannot be lowered
|-
|1||2||{{ottdp|0.6|2.5}}||NE edge cannot be lowered
|-
|2||4||{{ottdp|0.6|2.5}}||SW edge cannot be lowered
|-
|3||8||{{ottdp|0.6|2.5}}||SE edge cannot be lowered
|-
|4||10||{{ottdp|0.6|2.5}}||Can only be built on flat land
|-
|5||20||{{ottdp|0.6|2.5|ttdprev=alpha 58}}||The tile is allowed on both land and water
|}

Industry tiles are never built on steep slopes unless [[Callbacks#Custom shape check (2F) |callback 2F]] is enabled, but bits 0..4 are ignored in that case.

Bit 5 can be used to allow tiles of land industries built on water or vice versa. It effectively disables the land/water check code for the tile. If you need to customize the behavior further, you can use [[Callbacks#Custom shape check (2F) |callback 2F]] to decide what kind of water/land is allowed.

;'''PLEASE NOTE''': Be careful when setting this property. If you fail to set it correctly, your industry may end up building on a hillside, which is probably not what you want. The easiest way is to set bit 4 for middle tiles, bit 0 for the tiles along the SE edge, bit 1 for those along the SW edge and so on.

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

{| |-
!Bit!!value!!version!!meaning
|-
|0||1||{{ottdp| | }}||use [[Callbacks#Next animation frame (1A/26/141/153/158) |callback 26]] to decide the next animation frame
|-
|1||2||{{ottdp| | }}||use [[Callbacks#Length of animation frame (20/27/142/154/15A) |callback 27]] to decide animation speed
|-
|2||4||{{ottdp| |2.5|ttdprev=alpha 55 vcs 3}}||use [[Callbacks#Decide cargo acceptance (2B) |callback 2B]] to decide amount of acceptance
|-
|3||8||{{ottdp| |2.5|ttdprev=alpha 55 vcs 3}}||use [[Callbacks#Get accepted cargo types (2A/2C) |callback 2C]] to decide accepted types
|-
|4||10||{{ottdp| | }}||use [[Callbacks#Custom shape check (2F) |callback 2F]] to check if a slope is suitable
|-
|5||20||{{ottdp| | }}||use [[Callbacks#Decide drawing default foundations (30/14E/150) |callback 30]] to decide if default foundations need to be drawn
|-
|6||40||{{ottdp| |2.5|ttdprev=beta 3}}||use [[Callbacks#Disable autosloping (3C/14F/15D) |callback 3C]] to allow or deny autosloping below the tile
|}

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

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

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

=== Animation speed (10) ===

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

=== Triggers for [[Callbacks#Animation control (1B/25/140/152/159) |callback 25]] (11) ===

Call [[Callbacks#Animation control (1B/25/140/152/159) |callback 25]] when:

{| |-
!Property bit, var 18 byte 0!!Property value!!Version!!Meaning||Happens on||Var 18 byte 1
|-
|0||1||{{ottdp|0.6|2.5}}||the construction state changes <ref>During normal gameplay called 4 times per tile. During map generation called 1 time. {{ttdp|}} For the first call to happen, you also have to set [[Action0/Industry_Tiles#Animation_information_.280F.29|property 0F]] to some other value than 0xFFFF.</ref>||single tile||
|-
|1||2||{{ottdp|0.6|2.5}}||the tile is processed in the periodic processing loop||single tile||
|-
|2||4||{{ottdp|0.6|2.5}}||the industry of the tile is processed in the periodic processing loop (synchronized animation)||all tiles||
|-
|3||8||{{ottdp|0.6|2.5}}||the industry of the tile receives input cargo from a station||all tiles||
|-
|4||10||{{ottdp|0.6|2.5|ttdprev=beta 2}}||the industry distributes its output cargo to one of the stations nearby||all tiles||
|}
<references />

Currently no trigger provides additional information in var 18 bytes 1 to 3.

=== Special flags (12) ===

{| |-
!Bit!!Value!!Meaning
|-
|0||1||[[Callbacks#Next animation frame (1A/26/141/153/158) |Callback 26]] needs random bits
|-
|1||2||{{ottdp|1.9|no|ottdrev=e66cec8f}} In addition to the cargotypes set by property 0A..0C and 13, the tile accepts all cargotypes which the industry accepts.
* This considers industry properties 11 and 26 and callback 14B.
* This does not consider industry callback 3D.
* This property adds 8/8 acceptance for the matching cargotypes. You can list negative acceptances (-8/8) in property 13 to exclude specific cargos.
* Tile callback 2C overrides all acceptances including those added by this flag.
|}

=== Tile acceptance list (13) ===
{{ottdp|1.9|no|ottdrev=e66cec8f}}

Format:
<numinput> (<cargotype> <acceptance>)*

{| |-
!Size!!Variable!!Meaning
|-
|B||numinput||Number of (<cargotype> <acceptance>) pairs to follow,
|-
|B||cargotype||Cargotype (from CTT) to accept.
|-
|B||acceptance||Acceptance in 1/8 units. May be negative to negate property 12 bit 1.
|}

This property defines up to 16 cargotypes, which are accepted by the industry tile.
Use this property instead of property 0A..0C.

==Example==

Callback: Animation control

2025-04-24T18:39:00Z

Frosch: /* Animation control (1B/1C/25/140/148/152/159) */

== Animation control (1B/1C/25/140/148/152/159) ==

These callbacks are called, when an animation trigger happens.

{| |-
!Callback!!Feature!!Mask property!!Trigger!!Variable 10!!Variable 18
|-
|1B||Houses
|[[Action0/Houses#House_callback_flags_.2814.2C1D.29|Property 14 bit 2]]
|[[Action0/Houses#Periodic_refresh_multiplier_.2816.29|Periodic, see property 16]] <ref>For multi-tile houses [[Action0/Houses#Extra_Flags_.2819.29|property 19 bit 2]] controls, whether the trigger is synchronised across all house tiles. See details there.</ref>
|{{ottdp| |2.5|ttdprev=beta 2}} Random bits <ref>Lower 16 bits are random per tile. Upper 16 bits are the same for all tiles, if [[Action0/Houses#Extra_Flags_.2819.29|property 19 bit 2]] is set.</ref>
|Reserved for future use
|-
|1C||Houses
|[[Action0/Houses#House_callback_flags_.2814.2C1D.29|Property 14 bit 3]]
|[[VariationalAction2/Houses#Construction_stage_and_pseudo-random_values_.2840.29|Construction stage]] changes <ref>During normal gameplay called 4 times per tile. During map generation called 1 time. {{ttdp|}} For the first call to happen, you also have to set [[Action0/Houses#Building_flags_.2809.29|property 9 bit 5]].</ref>
|Reserved for future use
|Reserved for future use
|-
|25||Industry tiles
|[[Action0/Industry_Tiles#Triggers_for_callback_25_.2811.29|Property 11]]
|All triggers, see variable 18
|{{ottdp| |2.5|ttdprev=beta 2}} Random bits <ref name="randombits">Lower 16 bits are random per tile. Upper 16 bits are the same for all tiles, if the trigger applies to multiple tiles.</ref>
|Trigger and more, see [[Action0/Industry_Tiles#Triggers_for_callback_25_.2811.29|property 11]]
|-
|140||Stations, road stops
|[[Action0/Stations#Animation_triggers_.2818.29|Station property 18]], [[Action0/Road_Stops#Animation_triggers_.2810.29|road stop property 10]]
|All triggers, see variable 18
|{{ottdp| |2.5|ttdprev=beta 2}} Random bits <ref name="randombits" />
|Trigger and more, see [[Action0/Stations#Animation_triggers_.2818.29|station property 18]]
|-
|148||Houses
|[[Action0/Houses#Cargo_acceptance_watch_list_.2820.29|Property 1E]]
|Watched cargo accepted <ref>Due to implementation details, up to 250 game ticks can pass between the actual acceptance and triggering this callback.</ref>
|Reserved for future use
|See [[Action0/Houses#Cargo_acceptance_watch_list_.2820.29|property 1E]]
|-
|154||Airport tiles
|[[Action0/Airport_Tiles#Animation_triggers_via_callback_152_.2811.29|Property 11]]
|All triggers, see variable 18
|Random bits
|Trigger and more, see [[Action0/Airport_Tiles#Animation_triggers_via_callback_152_.2811.29|property 11]]
|-
|159||Objects
|[[Action0/Objects#Animation_triggers_.2813.29|Property 13]]
|All triggers, see variable 18
|Random bits
|Trigger and more, see [[Action0/Objects#Animation_triggers_.2813.29|property 13]]
|}
<references />

The return value has the format SSFF:
* FF: One of the following values:
: {| |-
!Value!!Meaning
|-
|00 - FC||Jump to this animation frame.
|-
|FD||leave the animation in its current state (do nothing)
|-
|FE||start animation with its current frame
|-
|FF||stop animation in its current frame
|}
* SS: Sound effect: If non-zero, the sound effect number to play at the tile.

Note: Every time the animation frame is changed the map tile will be refreshed, even if the selected graphics stay the same. Therefore using the animation frame as a timer should be avoided, and animation triggers should be preferred instead.

[[Category:Callbacks]]

Action0/Industry Tiles

2025-04-23T16:22:39Z

Frosch: wording

==Introduction==

Industry tiles work similarly to town buildings, except that they are not stand-alone; they are always part of an industry.

Defining industry tiles follows the same schema as houses do: to start using an ID, you first need to define it by setting property 8 for it. If you try to reference an ID (either via action0 or via action3) that isn't defined, your request is ignored, but not reported as an error, either. This means that if you want to conditionally define an ID, all you need to do is skipping the action0 that sets property8, and everything else gets skipped automatically.

Industry tile IDs are unique within each grf file. The per-GRF ID is specified as a byte, which means no GRF can define more than 256 tile IDs. You should use your industry tile IDs sparingly. [[VariationalAction2/Industry_Tiles#Relative_position_.2843.29| Variational action 2 variable 43]] for industry tiles can help you limiting tile consumption to 2 or 3 per industry. Avoid using tile FFh, so the tileID can be turned into an extended byte (in Action 3) in the distant future without breaking your NewGRF.

{{ttdp|}} In total, TTDPatch can have up to a total of 256 new industry tile IDs (i.e. old tile types don't count).

{{ottd|}} OpenTTD can have 512 IDs for all active grf files, but that includes non-overridden original tiles.

== Properties ==

{| |-
!Property !![[GRFActionsDetailed|Size]] !!Version !! Description
|-
|08||B||{{ottdp|0.6|2.5|ttdprev=alpha 43}}||Substitute building type
|-
|09||B||{{ottdp|0.6|2.5|ttdprev=alpha 43}}||Industry tile override
|-
|0A,0B,0C||W||{{ottdp|0.6|2.5}}||Tile acceptance
|-
|0D||B||{{ottdp|0.6|2.5|ttdprev=alpha 49}}||Land shape flags
|-
|0E||B||{{ottdp|0.6|2.5|ttdprev=alpha 54}}||Callback flags
|-
|0F||W||{{ottdp|0.6|2.5|ttdprev=alpha 54}}||Animation information
|-
|10||B||{{ottdp|0.6|2.5|ttdprev=alpha 54}}||Animation speed.
|-
|11||B||{{ottdp|0.6|2.5|ttdprev=alpha 54}}||Triggers for callback 25
|-
|12||B||{{ottdp|0.6|2.5|ttdprev=beta 2}}||Special flags
|-
|13||V||{{ottdp|1.9|no|ottdrev=e66cec8f}}||Tile acceptance list
|-
|14||W n*W||{{ottdp|15}}||List of badges
|}

== Description ==

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

This tile type will be used instead of your new one if your definition isn't available for any reason. Valid values are [http://marcin.ttdpatch.net/sv1codec/TTD-locations.html#Class8 00h-AEh]. Assigning this property copies the properties of the old type just like it does with houses.

If this tile's action 3 appears before this property is set, the action 3 will have no effect.

=== Industry tile override (09) ===

Works like the house override property for houses.

=== Tile acceptance (0A, 0B, 0C) ===

These three words define what cargoes the tile accepts, and how much of them. The low byte defines the type of the cargo according to the current climate, while the high byte defines the degree of acceptance in 1/8 units. If you don't need all three cargo types, just zero out the high byte of the extra properties.

{{grfFrom|7}} From GRF version 7 and above, the meaning of the low byte changes: instead of a climate-dependent cargo slot number, you have to give a climate-independent cargo ID. If your GRF has a cargo translation table, then this ID is the index in that table; otherwise, it's the cargo bit. Acceptance of cargoes not currently present will automatically be disabled.

{{ottdp|1.9|no|ottdrev=e66cec8f}} These properties only support three cargos. Use property 13 instead to list more cargo types.

=== Land shape flags (0D) ===

This property defines which slopes the tile can be built on.

{| |-
!Bit!!Value!!Version!!Meaning
|-
|0||1||{{ottdp|0.6|2.5}}||NW edge cannot be lowered
|-
|1||2||{{ottdp|0.6|2.5}}||NE edge cannot be lowered
|-
|2||4||{{ottdp|0.6|2.5}}||SW edge cannot be lowered
|-
|3||8||{{ottdp|0.6|2.5}}||SE edge cannot be lowered
|-
|4||10||{{ottdp|0.6|2.5}}||Can only be built on flat land
|-
|5||20||{{ottdp|0.6|2.5|ttdprev=alpha 58}}||The tile is allowed on both land and water
|}

Industry tiles are never built on steep slopes unless [[Callbacks#Custom shape check (2F) |callback 2F]] is enabled, but bits 0..4 are ignored in that case.

Bit 5 can be used to allow tiles of land industries built on water or vice versa. It effectively disables the land/water check code for the tile. If you need to customize the behavior further, you can use [[Callbacks#Custom shape check (2F) |callback 2F]] to decide what kind of water/land is allowed.

;'''PLEASE NOTE''': Be careful when setting this property. If you fail to set it correctly, your industry may end up building on a hillside, which is probably not what you want. The easiest way is to set bit 4 for middle tiles, bit 0 for the tiles along the SE edge, bit 1 for those along the SW edge and so on.

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

{| |-
!Bit!!value!!version!!meaning
|-
|0||1||{{ottdp| | }}||use [[Callbacks#Next animation frame (1A/26/141/153/158) |callback 26]] to decide the next animation frame
|-
|1||2||{{ottdp| | }}||use [[Callbacks#Length of animation frame (20/27/142/154/15A) |callback 27]] to decide animation speed
|-
|2||4||{{ottdp| |2.5|ttdprev=alpha 55 vcs 3}}||use [[Callbacks#Decide cargo acceptance (2B) |callback 2B]] to decide amount of acceptance
|-
|3||8||{{ottdp| |2.5|ttdprev=alpha 55 vcs 3}}||use [[Callbacks#Get accepted cargo types (2A/2C) |callback 2C]] to decide accepted types
|-
|4||10||{{ottdp| | }}||use [[Callbacks#Custom shape check (2F) |callback 2F]] to check if a slope is suitable
|-
|5||20||{{ottdp| | }}||use [[Callbacks#Decide drawing default foundations (30/14E/150) |callback 30]] to decide if default foundations need to be drawn
|-
|6||40||{{ottdp| |2.5|ttdprev=beta 3}}||use [[Callbacks#Disable autosloping (3C/14F/15D) |callback 3C]] to allow or deny autosloping below the tile
|}

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

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

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

=== Animation speed (10) ===

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

=== Triggers for [[Callbacks#Animation control (1B/25/140/152/159) |callback 25]] (11) ===

Call [[Callbacks#Animation control (1B/25/140/152/159) |callback 25]] when:

{| |-
!Bit!!Value!!Version!!Meaning||Happens on||Var 18
|-
|0||1||{{ottdp|0.6|2.5}}||the construction state changes <ref>During normal gameplay called 4 times per tile. During map generation called 1 time. For the first call to happen, you also have to set [[Action0/Industry_Tiles#Animation_information_.280F.29|property 0F]] to some other value than 0xFFFF.</ref>||single tile||
|-
|1||2||{{ottdp|0.6|2.5}}||the tile is processed in the periodic processing loop||single tile||
|-
|2||4||{{ottdp|0.6|2.5}}||the industry of the tile is processed in the periodic processing loop (synchronized animation)||all tiles||
|-
|3||8||{{ottdp|0.6|2.5}}||the industry of the tile receives input cargo from a station||all tiles||
|-
|4||10||{{ottdp|0.6|2.5|ttdprev=beta 2}}||the industry distributes its output cargo to one of the stations nearby||all tiles||
|}
<references />

Currently no trigger provides additional information in var 18.

=== Special flags (12) ===

{| |-
!Bit!!Value!!Meaning
|-
|0||1||[[Callbacks#Next animation frame (1A/26/141/153/158) |Callback 26]] needs random bits
|-
|1||2||{{ottdp|1.9|no|ottdrev=e66cec8f}} In addition to the cargotypes set by property 0A..0C and 13, the tile accepts all cargotypes which the industry accepts.
* This considers industry properties 11 and 26 and callback 14B.
* This does not consider industry callback 3D.
* This property adds 8/8 acceptance for the matching cargotypes. You can list negative acceptances (-8/8) in property 13 to exclude specific cargos.
* Tile callback 2C overrides all acceptances including those added by this flag.
|}

=== Tile acceptance list (13) ===
{{ottdp|1.9|no|ottdrev=e66cec8f}}

Format:
<numinput> (<cargotype> <acceptance>)*

{| |-
!Size!!Variable!!Meaning
|-
|B||numinput||Number of (<cargotype> <acceptance>) pairs to follow,
|-
|B||cargotype||Cargotype (from CTT) to accept.
|-
|B||acceptance||Acceptance in 1/8 units. May be negative to negate property 12 bit 1.
|}

This property defines up to 16 cargotypes, which are accepted by the industry tile.
Use this property instead of property 0A..0C.

==Example==

Action0/Airport Tiles

2025-04-23T16:22:20Z

Frosch: wording

== Introduction ==

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

== Properties ==

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

== Descriptions ==

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

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

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

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

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

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

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

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

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

=== Animation speed (10) ===

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

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

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

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

<references/>

== Example ==

Action0/Airport Tiles

2025-04-23T16:21:41Z

Frosch: add trigger area

== Introduction ==

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

== Properties ==

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

== Descriptions ==

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

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

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

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

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

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

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

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

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

=== Animation speed (10) ===

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

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

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

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

<references/>

== Example ==

Action0/Industry Tiles

2025-04-23T16:18:49Z

Frosch: add trigger area

==Introduction==

Industry tiles work similarly to town buildings, except that they are not stand-alone; they are always part of an industry.

Defining industry tiles follows the same schema as houses do: to start using an ID, you first need to define it by setting property 8 for it. If you try to reference an ID (either via action0 or via action3) that isn't defined, your request is ignored, but not reported as an error, either. This means that if you want to conditionally define an ID, all you need to do is skipping the action0 that sets property8, and everything else gets skipped automatically.

Industry tile IDs are unique within each grf file. The per-GRF ID is specified as a byte, which means no GRF can define more than 256 tile IDs. You should use your industry tile IDs sparingly. [[VariationalAction2/Industry_Tiles#Relative_position_.2843.29| Variational action 2 variable 43]] for industry tiles can help you limiting tile consumption to 2 or 3 per industry. Avoid using tile FFh, so the tileID can be turned into an extended byte (in Action 3) in the distant future without breaking your NewGRF.

{{ttdp|}} In total, TTDPatch can have up to a total of 256 new industry tile IDs (i.e. old tile types don't count).

{{ottd|}} OpenTTD can have 512 IDs for all active grf files, but that includes non-overridden original tiles.

== Properties ==

{| |-
!Property !![[GRFActionsDetailed|Size]] !!Version !! Description
|-
|08||B||{{ottdp|0.6|2.5|ttdprev=alpha 43}}||Substitute building type
|-
|09||B||{{ottdp|0.6|2.5|ttdprev=alpha 43}}||Industry tile override
|-
|0A,0B,0C||W||{{ottdp|0.6|2.5}}||Tile acceptance
|-
|0D||B||{{ottdp|0.6|2.5|ttdprev=alpha 49}}||Land shape flags
|-
|0E||B||{{ottdp|0.6|2.5|ttdprev=alpha 54}}||Callback flags
|-
|0F||W||{{ottdp|0.6|2.5|ttdprev=alpha 54}}||Animation information
|-
|10||B||{{ottdp|0.6|2.5|ttdprev=alpha 54}}||Animation speed.
|-
|11||B||{{ottdp|0.6|2.5|ttdprev=alpha 54}}||Triggers for callback 25
|-
|12||B||{{ottdp|0.6|2.5|ttdprev=beta 2}}||Special flags
|-
|13||V||{{ottdp|1.9|no|ottdrev=e66cec8f}}||Tile acceptance list
|-
|14||W n*W||{{ottdp|15}}||List of badges
|}

== Description ==

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

This tile type will be used instead of your new one if your definition isn't available for any reason. Valid values are [http://marcin.ttdpatch.net/sv1codec/TTD-locations.html#Class8 00h-AEh]. Assigning this property copies the properties of the old type just like it does with houses.

If this tile's action 3 appears before this property is set, the action 3 will have no effect.

=== Industry tile override (09) ===

Works like the house override property for houses.

=== Tile acceptance (0A, 0B, 0C) ===

These three words define what cargoes the tile accepts, and how much of them. The low byte defines the type of the cargo according to the current climate, while the high byte defines the degree of acceptance in 1/8 units. If you don't need all three cargo types, just zero out the high byte of the extra properties.

{{grfFrom|7}} From GRF version 7 and above, the meaning of the low byte changes: instead of a climate-dependent cargo slot number, you have to give a climate-independent cargo ID. If your GRF has a cargo translation table, then this ID is the index in that table; otherwise, it's the cargo bit. Acceptance of cargoes not currently present will automatically be disabled.

{{ottdp|1.9|no|ottdrev=e66cec8f}} These properties only support three cargos. Use property 13 instead to list more cargo types.

=== Land shape flags (0D) ===

This property defines which slopes the tile can be built on.

{| |-
!Bit!!Value!!Version!!Meaning
|-
|0||1||{{ottdp|0.6|2.5}}||NW edge cannot be lowered
|-
|1||2||{{ottdp|0.6|2.5}}||NE edge cannot be lowered
|-
|2||4||{{ottdp|0.6|2.5}}||SW edge cannot be lowered
|-
|3||8||{{ottdp|0.6|2.5}}||SE edge cannot be lowered
|-
|4||10||{{ottdp|0.6|2.5}}||Can only be built on flat land
|-
|5||20||{{ottdp|0.6|2.5|ttdprev=alpha 58}}||The tile is allowed on both land and water
|}

Industry tiles are never built on steep slopes unless [[Callbacks#Custom shape check (2F) |callback 2F]] is enabled, but bits 0..4 are ignored in that case.

Bit 5 can be used to allow tiles of land industries built on water or vice versa. It effectively disables the land/water check code for the tile. If you need to customize the behavior further, you can use [[Callbacks#Custom shape check (2F) |callback 2F]] to decide what kind of water/land is allowed.

;'''PLEASE NOTE''': Be careful when setting this property. If you fail to set it correctly, your industry may end up building on a hillside, which is probably not what you want. The easiest way is to set bit 4 for middle tiles, bit 0 for the tiles along the SE edge, bit 1 for those along the SW edge and so on.

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

{| |-
!Bit!!value!!version!!meaning
|-
|0||1||{{ottdp| | }}||use [[Callbacks#Next animation frame (1A/26/141/153/158) |callback 26]] to decide the next animation frame
|-
|1||2||{{ottdp| | }}||use [[Callbacks#Length of animation frame (20/27/142/154/15A) |callback 27]] to decide animation speed
|-
|2||4||{{ottdp| |2.5|ttdprev=alpha 55 vcs 3}}||use [[Callbacks#Decide cargo acceptance (2B) |callback 2B]] to decide amount of acceptance
|-
|3||8||{{ottdp| |2.5|ttdprev=alpha 55 vcs 3}}||use [[Callbacks#Get accepted cargo types (2A/2C) |callback 2C]] to decide accepted types
|-
|4||10||{{ottdp| | }}||use [[Callbacks#Custom shape check (2F) |callback 2F]] to check if a slope is suitable
|-
|5||20||{{ottdp| | }}||use [[Callbacks#Decide drawing default foundations (30/14E/150) |callback 30]] to decide if default foundations need to be drawn
|-
|6||40||{{ottdp| |2.5|ttdprev=beta 3}}||use [[Callbacks#Disable autosloping (3C/14F/15D) |callback 3C]] to allow or deny autosloping below the tile
|}

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

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

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

=== Animation speed (10) ===

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

=== Triggers for [[Callbacks#Animation control (1B/25/140/152/159) |callback 25]] (11) ===

Call [[Callbacks#Animation control (1B/25/140/152/159) |callback 25]] when:

{| |-
!Bit!!Value!!Version!!Meaning||Trigger area||Var 18
|-
|0||1||{{ottdp|0.6|2.5}}||the construction state changes <ref>During normal gameplay called 4 times per tile. During map generation called 1 time. For the first call to happen, you also have to set [[Action0/Industry_Tiles#Animation_information_.280F.29|property 0F]] to some other value than 0xFFFF.</ref>||single tile||
|-
|1||2||{{ottdp|0.6|2.5}}||the tile is processed in the periodic processing loop||single tile||
|-
|2||4||{{ottdp|0.6|2.5}}||the industry of the tile is processed in the periodic processing loop (synchronized animation)||all tiles||
|-
|3||8||{{ottdp|0.6|2.5}}||the industry of the tile receives input cargo from a station||all tiles||
|-
|4||10||{{ottdp|0.6|2.5|ttdprev=beta 2}}||the industry distributes its output cargo to one of the stations nearby||all tiles||
|}
<references />

Currently no trigger provides additional information in var 18.

=== Special flags (12) ===

{| |-
!Bit!!Value!!Meaning
|-
|0||1||[[Callbacks#Next animation frame (1A/26/141/153/158) |Callback 26]] needs random bits
|-
|1||2||{{ottdp|1.9|no|ottdrev=e66cec8f}} In addition to the cargotypes set by property 0A..0C and 13, the tile accepts all cargotypes which the industry accepts.
* This considers industry properties 11 and 26 and callback 14B.
* This does not consider industry callback 3D.
* This property adds 8/8 acceptance for the matching cargotypes. You can list negative acceptances (-8/8) in property 13 to exclude specific cargos.
* Tile callback 2C overrides all acceptances including those added by this flag.
|}

=== Tile acceptance list (13) ===
{{ottdp|1.9|no|ottdrev=e66cec8f}}

Format:
<numinput> (<cargotype> <acceptance>)*

{| |-
!Size!!Variable!!Meaning
|-
|B||numinput||Number of (<cargotype> <acceptance>) pairs to follow,
|-
|B||cargotype||Cargotype (from CTT) to accept.
|-
|B||acceptance||Acceptance in 1/8 units. May be negative to negate property 12 bit 1.
|}

This property defines up to 16 cargotypes, which are accepted by the industry tile.
Use this property instead of property 0A..0C.

==Example==

Action0/Industry Tiles

2025-04-23T16:14:37Z

Frosch: /* Triggers for callback 25 (11) */

==Introduction==

Industry tiles work similarly to town buildings, except that they are not stand-alone; they are always part of an industry.

Defining industry tiles follows the same schema as houses do: to start using an ID, you first need to define it by setting property 8 for it. If you try to reference an ID (either via action0 or via action3) that isn't defined, your request is ignored, but not reported as an error, either. This means that if you want to conditionally define an ID, all you need to do is skipping the action0 that sets property8, and everything else gets skipped automatically.

Industry tile IDs are unique within each grf file. The per-GRF ID is specified as a byte, which means no GRF can define more than 256 tile IDs. You should use your industry tile IDs sparingly. [[VariationalAction2/Industry_Tiles#Relative_position_.2843.29| Variational action 2 variable 43]] for industry tiles can help you limiting tile consumption to 2 or 3 per industry. Avoid using tile FFh, so the tileID can be turned into an extended byte (in Action 3) in the distant future without breaking your NewGRF.

{{ttdp|}} In total, TTDPatch can have up to a total of 256 new industry tile IDs (i.e. old tile types don't count).

{{ottd|}} OpenTTD can have 512 IDs for all active grf files, but that includes non-overridden original tiles.

== Properties ==

{| |-
!Property !![[GRFActionsDetailed|Size]] !!Version !! Description
|-
|08||B||{{ottdp|0.6|2.5|ttdprev=alpha 43}}||Substitute building type
|-
|09||B||{{ottdp|0.6|2.5|ttdprev=alpha 43}}||Industry tile override
|-
|0A,0B,0C||W||{{ottdp|0.6|2.5}}||Tile acceptance
|-
|0D||B||{{ottdp|0.6|2.5|ttdprev=alpha 49}}||Land shape flags
|-
|0E||B||{{ottdp|0.6|2.5|ttdprev=alpha 54}}||Callback flags
|-
|0F||W||{{ottdp|0.6|2.5|ttdprev=alpha 54}}||Animation information
|-
|10||B||{{ottdp|0.6|2.5|ttdprev=alpha 54}}||Animation speed.
|-
|11||B||{{ottdp|0.6|2.5|ttdprev=alpha 54}}||Triggers for callback 25
|-
|12||B||{{ottdp|0.6|2.5|ttdprev=beta 2}}||Special flags
|-
|13||V||{{ottdp|1.9|no|ottdrev=e66cec8f}}||Tile acceptance list
|-
|14||W n*W||{{ottdp|15}}||List of badges
|}

== Description ==

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

This tile type will be used instead of your new one if your definition isn't available for any reason. Valid values are [http://marcin.ttdpatch.net/sv1codec/TTD-locations.html#Class8 00h-AEh]. Assigning this property copies the properties of the old type just like it does with houses.

If this tile's action 3 appears before this property is set, the action 3 will have no effect.

=== Industry tile override (09) ===

Works like the house override property for houses.

=== Tile acceptance (0A, 0B, 0C) ===

These three words define what cargoes the tile accepts, and how much of them. The low byte defines the type of the cargo according to the current climate, while the high byte defines the degree of acceptance in 1/8 units. If you don't need all three cargo types, just zero out the high byte of the extra properties.

{{grfFrom|7}} From GRF version 7 and above, the meaning of the low byte changes: instead of a climate-dependent cargo slot number, you have to give a climate-independent cargo ID. If your GRF has a cargo translation table, then this ID is the index in that table; otherwise, it's the cargo bit. Acceptance of cargoes not currently present will automatically be disabled.

{{ottdp|1.9|no|ottdrev=e66cec8f}} These properties only support three cargos. Use property 13 instead to list more cargo types.

=== Land shape flags (0D) ===

This property defines which slopes the tile can be built on.

{| |-
!Bit!!Value!!Version!!Meaning
|-
|0||1||{{ottdp|0.6|2.5}}||NW edge cannot be lowered
|-
|1||2||{{ottdp|0.6|2.5}}||NE edge cannot be lowered
|-
|2||4||{{ottdp|0.6|2.5}}||SW edge cannot be lowered
|-
|3||8||{{ottdp|0.6|2.5}}||SE edge cannot be lowered
|-
|4||10||{{ottdp|0.6|2.5}}||Can only be built on flat land
|-
|5||20||{{ottdp|0.6|2.5|ttdprev=alpha 58}}||The tile is allowed on both land and water
|}

Industry tiles are never built on steep slopes unless [[Callbacks#Custom shape check (2F) |callback 2F]] is enabled, but bits 0..4 are ignored in that case.

Bit 5 can be used to allow tiles of land industries built on water or vice versa. It effectively disables the land/water check code for the tile. If you need to customize the behavior further, you can use [[Callbacks#Custom shape check (2F) |callback 2F]] to decide what kind of water/land is allowed.

;'''PLEASE NOTE''': Be careful when setting this property. If you fail to set it correctly, your industry may end up building on a hillside, which is probably not what you want. The easiest way is to set bit 4 for middle tiles, bit 0 for the tiles along the SE edge, bit 1 for those along the SW edge and so on.

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

{| |-
!Bit!!value!!version!!meaning
|-
|0||1||{{ottdp| | }}||use [[Callbacks#Next animation frame (1A/26/141/153/158) |callback 26]] to decide the next animation frame
|-
|1||2||{{ottdp| | }}||use [[Callbacks#Length of animation frame (20/27/142/154/15A) |callback 27]] to decide animation speed
|-
|2||4||{{ottdp| |2.5|ttdprev=alpha 55 vcs 3}}||use [[Callbacks#Decide cargo acceptance (2B) |callback 2B]] to decide amount of acceptance
|-
|3||8||{{ottdp| |2.5|ttdprev=alpha 55 vcs 3}}||use [[Callbacks#Get accepted cargo types (2A/2C) |callback 2C]] to decide accepted types
|-
|4||10||{{ottdp| | }}||use [[Callbacks#Custom shape check (2F) |callback 2F]] to check if a slope is suitable
|-
|5||20||{{ottdp| | }}||use [[Callbacks#Decide drawing default foundations (30/14E/150) |callback 30]] to decide if default foundations need to be drawn
|-
|6||40||{{ottdp| |2.5|ttdprev=beta 3}}||use [[Callbacks#Disable autosloping (3C/14F/15D) |callback 3C]] to allow or deny autosloping below the tile
|}

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

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

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

=== Animation speed (10) ===

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

=== Triggers for [[Callbacks#Animation control (1B/25/140/152/159) |callback 25]] (11) ===

Call [[Callbacks#Animation control (1B/25/140/152/159) |callback 25]] when:

{| |-
!Bit!!Value!!Version!!Meaning||Trigger area||Var 18
|-
|0||1||{{ottdp|0.6|2.5}}||all ||the construction state changes <ref>During normal gameplay called 4 times per tile. During map generation called 1 time. For the first call to happen, you also have to set [[Action0/Industry_Tiles#Animation_information_.280F.29|property 0F]] to some other value than 0xFFFF.</ref>||
|-
|1||2||{{ottdp|0.6|2.5}}||the tile is processed in the periodic processing loop||
|-
|2||4||{{ottdp|0.6|2.5}}||the industry of the tile is processed in the periodic processing loop (synchronized animation)||
|-
|3||8||{{ottdp|0.6|2.5}}||the industry of the tile receives input cargo from a station||
|-
|4||10||{{ottdp|0.6|2.5|ttdprev=beta 2}}||the industry distributes its output cargo to one of the stations nearby||
|}
<references />

Currently no trigger provides additional information in var 18.

=== Special flags (12) ===

{| |-
!Bit!!Value!!Meaning
|-
|0||1||[[Callbacks#Next animation frame (1A/26/141/153/158) |Callback 26]] needs random bits
|-
|1||2||{{ottdp|1.9|no|ottdrev=e66cec8f}} In addition to the cargotypes set by property 0A..0C and 13, the tile accepts all cargotypes which the industry accepts.
* This considers industry properties 11 and 26 and callback 14B.
* This does not consider industry callback 3D.
* This property adds 8/8 acceptance for the matching cargotypes. You can list negative acceptances (-8/8) in property 13 to exclude specific cargos.
* Tile callback 2C overrides all acceptances including those added by this flag.
|}

=== Tile acceptance list (13) ===
{{ottdp|1.9|no|ottdrev=e66cec8f}}

Format:
<numinput> (<cargotype> <acceptance>)*

{| |-
!Size!!Variable!!Meaning
|-
|B||numinput||Number of (<cargotype> <acceptance>) pairs to follow,
|-
|B||cargotype||Cargotype (from CTT) to accept.
|-
|B||acceptance||Acceptance in 1/8 units. May be negative to negate property 12 bit 1.
|}

This property defines up to 16 cargotypes, which are accepted by the industry tile.
Use this property instead of property 0A..0C.

==Example==

Callback: Animation control

2025-04-23T16:04:11Z

Frosch: house construction stage trigger

== Animation control (1B/1C/25/140/148/152/159) ==

These callbacks are called, when an animation trigger happens.

{| |-
!Callback!!Feature!!Mask property!!Trigger!!Variable 10!!Variable 18
|-
|1B||Houses
|[[Action0/Houses#House_callback_flags_.2814.2C1D.29|Property 14 bit 2]]
|[[Action0/Houses#Periodic_refresh_multiplier_.2816.29|Periodic, see property 16]] <ref>For multi-tile houses [[Action0/Houses#Extra_Flags_.2819.29|property 19 bit 2]] controls, whether the trigger is synchronised across all house tiles. See details there.</ref>
|{{ottdp| |2.5|ttdprev=beta 2}} Random bits <ref>Lower 16 bits are random per tile. Upper 16 bits are the same for all tiles, if [[Action0/Houses#Extra_Flags_.2819.29|property 19 bit 2]] is set.</ref>
|Reserved for future use
|-
|1C||Houses
|[[Action0/Houses#House_callback_flags_.2814.2C1D.29|Property 14 bit 3]]
|[[VariationalAction2/Houses#Construction_stage_and_pseudo-random_values_.2840.29|Construction stage]] changes <ref>During normal gameplay called 4 times per tile. During map generation called 1 time. For the first call to happen, you also have to set [[Action0/Houses#Building_flags_.2809.29|property 9 bit 5]].</ref>
|Reserved for future use
|Reserved for future use
|-
|25||Industry tiles
|[[Action0/Industry_Tiles#Triggers_for_callback_25_.2811.29|Property 11]]
|All triggers, see variable 18
|{{ottdp| |2.5|ttdprev=beta 2}} Random bits <ref name="randombits">Lower 16 bits are random per tile. Upper 16 bits are the same for all tiles, if the trigger applies to multiple tiles.</ref>
|See [[Action0/Industry_Tiles#Triggers_for_callback_25_.2811.29|property 11]]
|-
|140||Stations, road stops
|[[Action0/Stations#Animation_triggers_.2818.29|Station property 18]], [[Action0/Road_Stops#Animation_triggers_.2810.29|road stop property 10]]
|All triggers, see variable 18
|{{ottdp| |2.5|ttdprev=beta 2}} Random bits <ref name="randombits" />
|See [[Action0/Stations#Animation_triggers_.2818.29|station property 18]]
|-
|148||Houses
|[[Action0/Houses#Cargo_acceptance_watch_list_.2820.29|Property 1E]]
|Watched cargo accepted <ref>Due to implementation details, up to 250 game ticks can pass between the actual acceptance and triggering this callback.</ref>
|Reserved for future use
|See [[Action0/Houses#Cargo_acceptance_watch_list_.2820.29|property 1E]]
|-
|154||Airport tiles
|[[Action0/Airport_Tiles#Animation_triggers_via_callback_152_.2811.29|Property 11]]
|All triggers, see variable 18
|Random bits
|See [[Action0/Airport_Tiles#Animation_triggers_via_callback_152_.2811.29|property 11]]
|-
|159||Objects
|[[Action0/Objects#Animation_triggers_.2813.29|Property 13]]
|All triggers, see variable 18
|Random bits
|See [[Action0/Objects#Animation_triggers_.2813.29|property 13]]
|}
<references />

The return value has the format SSFF:
* FF: One of the following values:
: {| |-
!Value!!Meaning
|-
|00 - FC||Jump to this animation frame.
|-
|FD||leave the animation in its current state (do nothing)
|-
|FE||start animation with its current frame
|-
|FF||stop animation in its current frame
|}
* SS: Sound effect: If non-zero, the sound effect number to play at the tile.

Note: Every time the animation frame is changed the map tile will be refreshed, even if the selected graphics stay the same. Therefore using the animation frame as a timer should be avoided, and animation triggers should be preferred instead.

[[Category:Callbacks]]

Callbacks

2025-04-23T15:49:58Z

Frosch: dead links

==Introduction==

A callback is a special action 2 that the patch "calls" in order to modify various features, an example being the visual effect of train vehicles.  See the [[ttwiki:CallbacksTut|callback tutorial]] on how to use them.

In the final action 2 of a chain of VarAction2s, the second byte of the matching entry has to have bit 7 set to identify it as a callback result.

For example, 04 00 is not a callback result (but it may be the ID of another chained action 2), whereas 04 80 is a callback result with a value of 4. In total a callback has 15 bit result values, where the upper 7 bits are stored in the second byte. For example, 54 C2 is a callback result with a value of 4254=16980, where again the second byte has bit 7 set, changing the 42 into C2.

{{grfTill|7}} For GRF version 7 and below not all 15 bit values are available as return values, only values between 00 and 7EFF.
For compatibility with earlier patch versions, FF in the high byte is taken to mean the same thing as 80, so 04 FF also has a callback result of 4. Note that if your grf file needs to be compatible with versions before TTDPatch 2.0.1 alpha 40, you must set the high byte to FF, and so can use only 8 bit results.

{{grfFrom|8}} For GRF version 8 and above this compatibility layer has been removed. Callbacks can return all 15 bit values between 00 and 7FFF.

To check for a specific callback, use an [[VariationalAction2]] or [[VarAction2Advanced]] to check for variable 0C.
* Variable 0C contains the callback number.
* Variable 0C is a word, thus the VarAction2 must use type 85.
* Results can be specified directly using 8xxx values (see above), or with 8xxx value in subsequent (Basic/Variational/Random)Action2 which are referenced as usual with their set-id.
* The default case of the VarAction2 must point to the regular graphics chain, so that unknown/future callbacks results in a "callback failure" result.

Example:
<Sprite-number> * <Length> 02 <feature> <set-id> 85 0C 00 \wxFFFF
<nvar> (<set-id/result> \wx <callback> \wx <callback>){n}
<set-id of graphics chain>

The format for VarAction2 is explained in detail on the [[VariationalAction2]] page.

== List of callbacks ==

The following callbacks are defined by the patch.  The number of the callback is what will be stored in variable 0C so that you can return the right results if you have several callbacks.  All callbacks are explained in more detail below.

'''PLEASE NOTE:''' Since TTDPatch 2.5 beta 5, the size of variable 0C has changed, and now there are word-sized callback numbers as well. To maintain backwards compatibility, only callbacks 10..3F can be checked using a byte-sized check. Callbacks 140 and above, on the other hand, must be checked using a word or dword sized check, to make sure they are identified uniquely.

{| |-
!Number!!Feature(s)!!Meaning
|-
|10||Vehicles||[[Callback: Visual effect and wagon power|Visual effect and wagon power]]
|-
|11||Vehicles||[[Callback: Wagon length|Wagon length]]
|-
|12||Vehicles||[[Callback: Load amount|Load amount]]
|-
|13||Stations/Roadstops||[[Callback: Station availability|Station availability]]
|-
|14||Stations||[[Callback: Station sprite layout|Select sprite layout]]
|-
|15||Vehicles||[[Callback: Refitted capacity callback|Refitted capacity callback]]
|-
|16||Trains||[[Callback: Articulated engine|Build articulated engines]]
|-
|17||Houses||[[Callback: House construction check|House construction check]]
|-
|18||Several <ref name="generic">Generic callbacks are called for the feature, not any specific vehicle ID. Read the [[Action3#n-id|Action 3]] entry on how to define these.</ref>||[[Callback: AI construction/purchase selection|AI construction/purchase selection]]
|-
|19||Vehicles||[[Callback: Cargo Subtype Display|Cargo sub-type display]]
|-
|1A||Houses||Next animation frame
|-
|1B||Houses||Animation control
|-
|1C||Houses||Construction stage changes
|-
|1D||Trains||Can wagon be attached
|-
|1E||Houses||Decide colour of building
|-
|1F||Houses||Cargo acceptance
|-
|20||Houses||Length of animation frame
|-
|21||Houses||Trigger building destruction
|-
|22||Industries||Availability
|-
|23||Vehicles||Additional text in purchase screen
|-
|24||Stations||Custom station layout
|-
|25||Industry tiles||Animation control
|-
|26||Industry tiles||Next animation frame
|-
|27||Industry tiles||Length of animation frame
|-
|28||Industries||Industry location permissibility
|-
|29||Industries||Random production change
|-
|2A||Houses||Get accepted cargo types
|-
|2B||Industry tiles||Decide cargo acceptance
|-
|2C||Industry tiles||Get accepted cargo types
|-
|2D||Vehicles||Select colour mapping for vehicle
|-
|2E||Houses||Custom cargo production
|-
|2F||Industry tiles||Custom shape check
|-
|30||Industry tiles||Decide drawing default foundations
|-
|31||Vehicles||Start/stop check
|-
|32||Vehicles||32-day callback
|-
|33||Several||Sound effect callback
|-
|34||Vehicles <ref name="generic"/>||Autoreplace vehicle selection
|-
|35||Industries||Monthly random production change
|-
|36||Vehicles||Change vehicle Properties
|-
|37||Industries||Cargo sub-type display
|-
|38||Industries||Show additional text in fund window
|-
|39||Cargoes||Custom profit calculation
|-
|3A||Industries||Show additional text in industry window
|-
|3B||Industries||Control special effects
|-
|3C||Industry tiles||Disable autosloping
|-
|3D||Industries||Opt out of accepting cargo
|-
|40..13F|| ||--Reserved--
|-
|140||Stations/Roadstops||Animation control
|-
|141||Stations/Roadstops||Next animation frame
|-
|142||Stations/Roadstops||Length of animation frame
|-
|143||Houses||Protect building conditionally
|-
|144||Sounds <ref name="generic"/>||{{ottdp|1.2|2.6|ottdrev=r23144|ttdprev=r821}} Ambient sound effects
|-
|145||Cargoes||Custom station rating calculation
|-
|146||New Signals <ref name="generic"/>||New signals sprite drawing
|-
|147||Canals||Add sprite offset
|-
|148||Houses||Watched cargo accepted
|-
|149||Stations||Land slope check
|-
|14A||Industries||Decide industry color
|-
|14B||Industries||Decide input cargo types
|-
|14C||Industries||Decide output cargo types
|-
|14D||Houses||Customized building name
|-
|14E||Houses||Decide drawing default foundations
|-
|14F||Houses||Disable autosloping
|-
|150||Airport tiles||{{ottdp|1.1|no|ottdrev=r19197}} Decide drawing default foundations
|-
|152||Airport tiles||{{ottdp|1.1|no|ottdrev=r19197}} Animation control
|-
|153||Airport tiles||{{ottdp|1.1|no|ottdrev=r19197}} Next Animation frame
|-
|154||Airport tiles||{{ottdp|1.1|no|ottdrev=r19197}} Length of animation frame
|-
|155||Airports||{{ottdp|1.1|no|ottdrev=r20373}} Extra information about airport layout in the build gui
|-
|156||Airports||{{ottdp|1.1|no|ottdrev=r20373}} Airport layout name
|-
|157||Objects||Land slope check
|-
|158||Objects||Next animation frame
|-
|159||Objects||Animation control
|-
|15A||Objects||Length of animation frame
|-
|15B||Objects||Decide colour of building
|-
|15C||Objects||Show additional text in building window
|-
|15D||Objects||Disable autosloping
|-
|15E||Vehicles||{{ottdp|1.2|no|ottdrev=r23124}} Refit cost factor
|-
|15F||Industries||{{ottdp|1.3|no|ottdrev=r24186}} Set initial production level on construction
|-
|160||Vehicles||{{ottdp|1.5|no|ottdrev=r26747}} Advanced effect creation
|-
|161||Vehicles||{{ottdp|14|no|ottdrev=g05ed9f56fd}} Engine name
|-
|162||Vehicles||{{ottdp|14|no|ottdrev=gddd609ce9b}} Probability of reversing rail vehicle on build
|-
|163||Vehicles||{{ottdp|15|no|ottdrev=gd2496b6ec4}} Custom refit
|}
<references/>

{{:Callback: Visual effect and wagon power}}
{{:Callback: Wagon length}}
{{:Callback: Load amount}}
{{:Callback: Station availability}}
{{:Callback: Station sprite layout}}
{{:Callback: Refitted capacity callback}}
{{:Callback: Articulated engine}}
{{:Callback: House construction check}}
{{:Callback: AI construction/purchase selection}}
{{:Callback: Cargo Subtype Display}}
{{:Callback: Next animation frame}}
{{:Callback: Animation control}}
{{:Callback: Can wagon be attached}}
{{:Callback: Building colour}}
{{:Callback: Cargo acceptance}}
{{:Callback: Length of animation frame}}
{{:Callback: Trigger building destruction}}
{{:Callback: Industry availability}}
{{:Callback: Additional text in purchase screen}}
{{:Callback: Custom station layout}}
{{:Callback: Industry location permissibility}}
{{:Callback: Random production change}}
{{:Callback: Get accepted cargo types}}
{{:Callback: Decide cargo acceptance}}
{{:Callback: Select colour mapping for vehicle}}
{{:Callback: Custom cargo production}}
{{:Callback: Custom shape check}}
{{:Callback: Decide drawing default foundations}}
{{:Callback: Vehicle Start/stop check}}
{{:Callback: 32-day callback}}
{{:Callback: Sound effect}}
{{:Callback: Autoreplace vehicle selection}}
{{:Callback: Monthly random production change}}
{{:Callback: Change vehicle properties}}
{{:Callback: Cargo sub-type display for industries}}
{{:Callback: Show additional text in fund/building window}}
{{:Callback: Custom profit calculation for cargoes}}
{{:Callback: Show additional text in industry window}}
{{:Callback: Control special industry effects}}
{{:Callback: Disable autosloping}}
{{:Callback: Opt out of accepting cargo}}
{{:Callback: Protect building conditionally}}
{{:Callback: Ambient sound effects}}
{{:Callback: Custom station rating calculation}}
{{:Callback: New signals sprite drawing callback}}
{{:Callback: Add sprite offset callback}}
{{:Callback: Station slope check}}
{{:Callback: Decide industry colour}}
{{:Callback: Decide input and output cargo types}}
{{:Callback: Customized building name}}
{{:Callback: Extra information about layout in the build gui}}
{{:Callback: Layout name}}
{{:Callback: Object slope check}}
{{:Callback: Decide object colour}}
{{:Callback: Refit cost factor}}
{{:Callback: Set initial production level on construction}}
{{:Callback: Advanced effect creation}}
{{:Callback: Engine name}}
{{:Callback: Build probability}}
{{:Callback: Custom refit}}

Callback: Animation control

2025-04-23T15:45:39Z

Frosch: reshuffle paragraphs into table

== Animation control (1B/1C/25/140/148/152/159) ==

These callbacks are called, when an animation trigger happens.

{| |-
!Callback!!Feature!!Mask property!!Trigger!!Variable 10!!Variable 18
|-
|1B||Houses
|[[Action0/Houses#House_callback_flags_.2814.2C1D.29|Property 14 bit 2]]
|[[Action0/Houses#Periodic_refresh_multiplier_.2816.29|Periodic, see property 16]] <ref>For multi-tile houses [[Action0/Houses#Extra_Flags_.2819.29|property 19 bit 2]] controls, whether the trigger is synchronised across all house tiles. See details there.</ref>
|{{ottdp| |2.5|ttdprev=beta 2}} Random bits <ref>Lower 16 bits are random per tile. Upper 16 bits are the same for all tiles, if [[Action0/Houses#Extra_Flags_.2819.29|property 19 bit 2]] is set.</ref>
|Reserved for future use
|-
|1C||Houses
|[[Action0/Houses#House_callback_flags_.2814.2C1D.29|Property 14 bit 3]]
|[[VariationalAction2/Houses#Construction_stage_and_pseudo-random_values_.2840.29|Construction stage]] changes <ref>Called during normal gameplay (3 times per tile), not during map generation.</ref>
|Reserved for future use
|Reserved for future use
|-
|25||Industry tiles
|[[Action0/Industry_Tiles#Triggers_for_callback_25_.2811.29|Property 11]]
|All triggers, see variable 18
|{{ottdp| |2.5|ttdprev=beta 2}} Random bits <ref name="randombits">Lower 16 bits are random per tile. Upper 16 bits are the same for all tiles, if the trigger applies to multiple tiles.</ref>
|See [[Action0/Industry_Tiles#Triggers_for_callback_25_.2811.29|property 11]]
|-
|140||Stations, road stops
|[[Action0/Stations#Animation_triggers_.2818.29|Station property 18]], [[Action0/Road_Stops#Animation_triggers_.2810.29|road stop property 10]]
|All triggers, see variable 18
|{{ottdp| |2.5|ttdprev=beta 2}} Random bits <ref name="randombits" />
|See [[Action0/Stations#Animation_triggers_.2818.29|station property 18]]
|-
|148||Houses
|[[Action0/Houses#Cargo_acceptance_watch_list_.2820.29|Property 1E]]
|Watched cargo accepted <ref>Due to implementation details, up to 250 game ticks can pass between the actual acceptance and triggering this callback.</ref>
|Reserved for future use
|See [[Action0/Houses#Cargo_acceptance_watch_list_.2820.29|property 1E]]
|-
|154||Airport tiles
|[[Action0/Airport_Tiles#Animation_triggers_via_callback_152_.2811.29|Property 11]]
|All triggers, see variable 18
|Random bits
|See [[Action0/Airport_Tiles#Animation_triggers_via_callback_152_.2811.29|property 11]]
|-
|159||Objects
|[[Action0/Objects#Animation_triggers_.2813.29|Property 13]]
|All triggers, see variable 18
|Random bits
|See [[Action0/Objects#Animation_triggers_.2813.29|property 13]]
|}
<references />

The return value has the format SSFF:
* FF: One of the following values:
: {| |-
!Value!!Meaning
|-
|00 - FC||Jump to this animation frame.
|-
|FD||leave the animation in its current state (do nothing)
|-
|FE||start animation with its current frame
|-
|FF||stop animation in its current frame
|}
* SS: Sound effect: If non-zero, the sound effect number to play at the tile.

Note: Every time the animation frame is changed the map tile will be refreshed, even if the selected graphics stay the same. Therefore using the animation frame as a timer should be avoided, and animation triggers should be preferred instead.

[[Category:Callbacks]]

Action0/Houses

2025-04-23T15:24:28Z

Frosch: /* Cargo acceptance watch list (20) */

== Introduction ==

For town buildings (or simply houses), the offset defines the first house ID for this action 0. House IDs, like station IDs, are unique within each grf file, and in total each game can only have 255 IDs in TTDPatch and 512 IDs in OpenTTD for all active grf files.

{{ottdp|15}} Since OpenTTD 15, the limits are increased to 4096 IDs, both per-grf and in total.

To start using a house ID, you must first define it by setting its property 08 (see below). If you try to modify a house ID whose property 08 isn't set, your request is ignored, but not reported as an error, either.

== Properties ==

{| |-
!Number!![[GRFActionsDetailed|Size]]!!Version!!Description
|-
|08||B||{{ottdp|0.6|2.5|ttdprev=alpha 34}}||Substitute building type
|-
|09||B||{{ottdp|0.6|2.5|ttdprev=alpha 34}}||Building flags
|-
|0A||W||{{ottdp|0.6|2.5|ttdprev=alpha 34}}||Availability years
|-
|0B||B||{{ottdp|0.6|2.5|ttdprev=alpha 34}}||Population
|-
|0C||B||{{ottdp|0.6|2.5|ttdprev=alpha 34}}||Mail generation multiplier
|-
|0D||B||{{ottdp|0.6|2.5|ttdprev=alpha 34}}||Passenger acceptance
|-
|0E||B||{{ottdp|0.6|2.5|ttdprev=alpha 34}}||Mail acceptance
|-
|0F||B||{{ottdp|0.6|2.5|ttdprev=alpha 34}}||Goods, food or fizzy drinks acceptance
|-
|10||W||{{ottdp|0.6|2.5|ttdprev=alpha 34}}||LA rating decrease on removal (should be set to the same value for every tile for multi-tile buildings)
|-
|11||B||{{ottdp|0.6|2.5|ttdprev=alpha 34}}||Removal cost multiplier (should be set to the same value for every tile for multi-tile buildings)
|-
|12||W||{{ottdp|0.6|2.5|ttdprev=alpha 34}}||Building name ID
|-
|13||W||{{ottdp|0.6|2.5|ttdprev=alpha 34}}||Building availability mask
|-
|14||B||{{ottdp|0.6|2.5|ttdprev=alpha 34}}||House callback flags
|-
|15||B||{{ottdp|0.6|2.5|ttdprev=alpha 34}}||House override byte
|-
|16||B||{{ottdp|0.6|2.5|ttdprev=alpha 34}}||Periodic refresh multiplier
|-
|17||4*B||{{ottdp|0.6|2.5|ttdprev=alpha 35}}||Four random colours to use
|-
|18||B||{{ottdp|0.6|2.5|ttdprev=alpha 35}}||Relative probability of appearing
|-
|19||B||{{ottdp|0.6|2.5|ttdprev=alpha 38}}||Extra flags
|-
|1A||B||{{ottdp|0.6|2.5|ttdprev=alpha 39}}||Animation frames
|-
|1B||B||{{ottdp|0.6|2.5|ttdprev=alpha 39}}||Animation speed
|-
|1C||B||{{ottdp|0.6|2.5|ttdprev=alpha 43}}||Class of the building type
|-
|1D||B||{{ottdp|0.6|2.5|ttdprev=alpha 55 vcs 2}}||Callback flags 2
|-
|1E||D||{{ottdp|0.6|2.5|ttdprev=alpha 55 vcs 2}}||Accepted cargo types
|-
|1F||B||{{ottdp|0.6|2.6|ttdprev=r1554}}||Minimum life span in years
|-
|20||V||{{ottdp|1.2|2.6|ottdrev=r23072|ttdprev=r1677}}||Cargo acceptance watch list
|-
|21||W||{{ottdp|0.7|no|ottdrev=r13437}}||Long year (zero based) of minimum appearance
|-
|22||W||{{ottdp|0.7|no|ottdrev=r13437}}||Long year (zero based) of maximum appearance
|-
|23||V||{{ottdp|1.9|no|ottdrev=48b334cf}}||Tile acceptance list
|-
|24||W n*W||{{ottdp|15}}||List of badges
|}

When a town decides to expand, each active house type (both old and new ones) has a uniform probability to appear, so the more new houses you define, the fewer old TTD buildings will appear.

== Descriptions ==

=== Substitute building type (08) ===

This building type will be used instead of your new one if your definition isn't available for any reason (the grf file is not found, for example).

Don't set a substitute building type that is larger than your new one (for example, don't set 14 (stadium) for an 1x1 building) because this may corrupt savegames. Setting this property automatically copies every property of the substitute building to your new building, so you don't have to change properties that are the same as the substitute.

House flags 40 and 80 are exceptions; these flags are never set automatically. Only the first property 08 setting copies properties; if you later change it, properties will stay.

There's a special use of this property beginning from alpha 72: if you set it to FFh, you can disable an old house type. In this case, the ID used must be the number of old house type you want to disable. Disabling only prevents building the type in towns; houses already present on the map will stay unchanged. The type can still be overridden, and overriding affects houses present on the map.

If this house's action 3 appears before this property is set, the action 3 will have no effect.

=== Building flags (09) ===

{| |-
!Bit!!Value!!Meaning
|-
|0||1||This is a 1x1 building
|-
|1||2||This building can be built only on flat land (if clear, foundations are automatically displayed on sloped land)
|-
|2||4||This is a 2x1 building<ref name="large">If your building isn't 1x1, set flags for the north tile, then define the next 1 or 3 tiles tiles (by setting their property 8). The only bit that can be set in the flags of additional tiles is bit 5 (animation). There should be no property 8 setting between the first tile and the additional tiles.</ref>
|-
|3||8||This is a 1x2 building<ref name="large" />
|-
|4||10||This is a 2x2 building<ref name="large" /><ref>For 2x2 buildings, the first additional tile is the east one, the second is the west part and the third is the south part. You probably want to set the substitute for additional tiles to a TTD additional tile whose flags are already zero. 2x2 buildings are always built on flat land no matter how bit 1 is set.</ref>
|-
|5||20||Animation flag, set in tiles 04 and 05 (large office block). New buildings have a different animation scheme than large office blocks, but animation is still enabled with this bit.<ref>The animation flag works on a per-tile basis, so you should enable it for additional tiles of multi-tile buildings as well if you want all tiles to be animated.</ref>
|-
|6||40||This building is a church<ref name="only1">Only one church and one stadium can exist in a town. The town won't build buildings with the according flag set until the old church/stadium is removed. (This can be done by either the town or a player)</ref>
|-
|7||80||This building is a stadium<ref name="only1" />
|}

<references />

=== Availability years (0A) ===

The low byte is the minimum year, the high is the maximum. The building can only be built between these two years (inclusive). 1920 is added to both bytes before using the values.

{{ottdp|no| }}
Since the year counting stops in TTDPatch in 2070 even with [[ttwiki:EternalGame|EternalGame]] on, start years above 150 mean "never", and end years above 150 mean "forever". In OpenTTD there is no limit for the maximum year (resp. it is 5000000).

'''WARNING:''' Don't set the start year below 1930 (0Ah) unless you know what you're doing!

{{ttdp|}} If TTDPatch finds a building that is available before 1930, it will not build old building types until that year, so you have to provide at least one custom building type that is available before 1930 for every [[TownZones|town zone]], or TTD may deadlock while trying to create a random game or expand a town.

{{ottd|}} The availability of all active houses with the lowest availability year is set to start from year 0, so that always at least one house is available irrespective of starting year. Thus, if you de-activate default houses or set an introduction date prior to the default houses introduction year 1930, you should have at least for each [[TownZones|town zone]] a house with the same earliest availability year or you might end up with a situation where no house can be placed in a [[TownZones|town zone]].

=== Population (0B) and Mail generation multiplier (0C) ===
[[Image:House_production.png|frame|right|Actual house production roughly depends on squared value of the population / mail generation multiplier.]]

The population of the town will be increased by the amount set in prop. 0B if this building is built. Additional house parts should have a population of zero. The higher this value is, the more passengers this building generates.

The higher the mail generation multiplier is, the more mail the building generates. For multi-tile buildings, mail generation is done in per-tile basis, so you can specify different values for every tile, although distributing the generation equally between tiles is suggested.

This is how exactly passengers are generated: In each periodic processing (i.e. every 256 ticks), a random value 0<=X<=255 is generated for each house tile. If X isn't smaller than the population of the tile, no passengers are generated. Otherwise, X/8+1 passengers are generated (rounded down). If there is a recession going on, the number of generated passengers is halved, but this division gets rounded up instead of down. Mail generation happens in a similar manner, but with a new random value, and checking against the mail generation multiplier instead of the population.

You can further customize how the cargo is generated with the [[Callbacks#Custom_cargo_production_.282E.29 |callback 2E]]. 

=== Passenger (0D), Mail (0E) and Good/Food/Fizzy drinks (0F) acceptance ===

The acceptance is given in units of 1/8th and must not be larger than 8 eighths.

For property 0F, positive values indicate that the building accepts goods, and negative values (i.e. FF = 1/8th, FE = 2/8ths etc.) indicate acceptance of food or fizzy drinks, depending on the climate.

All the above three values can be set independently for tiles of multi-tile buildings, since every tile is processed individually when determining what a station accepts.

The type of accepted cargo can be modified using [[Action0Houses#Accepted_cargo_types|property 1E]].

{{ottdp|no| }} Note that in TTDPatch the officefood switch may modify acceptance in the sub-arctic and subtropical climates.

=== Building name ID (12) ===

The ID of the text that should be displayed in the land query window. The name can also be set by [[Action4|action 4]] (see there). Should be set to the same value for every tile for multi-tile buildings.

=== Building availability mask (13) ===

{| |-
!Bit!!Value!!Meaning
|-
|0..4||1,2,4,8,10||which [[VariationalAction2/Houses#Town zone (42)|town zone(s)]] the building can be built in
|-
|11||800||can appear in sub-arctic climate above the snow line
|-
|12||1000||can appear in temperate climate
|-
|13||2000||can appear in sub-arctic climate below the snow line
|-
|14||4000||can appear in subtropical climate
|-
|15||8000||can appear in toyland climate
|}

This property should be set to zero for additional building tiles.

=== House callback flags (14,1D) ===

For houses, the following [[callbacks]] can be defined by setting the corresponding bit in property 14:

{| |-
!Bit!!Value!!Variable 0C value!!Version!!Callback
|-
|0||1||17||{{ottdp| | }}||decide whether the house can be built on a given tile
|-
|1||2||1A||{{ottdp| | }}||decide the following frame of the animations
|-
|2||4||1B||{{ottdp| | }}||periodically start/stop the animation
|-
|3||8||1C||{{ottdp| | }}||change animation when construction state changes
|-
|4||10||1E||{{ottdp| | }}||decide the color of the building
|-
|5||20||1F||{{ottdp| | }}||decide the cargos amounts accepted
|-
|6||40||20||{{ottdp| | }}||decide the length of the current animation frame
|-
|7||80||21||{{ottdp| | }}||trigger destruction of building
|}

Property 1D was introduced after all bits of property 14 were filled. Its usage is the same, only the meaning of bits is different:

{| |-
!Bit!!Value!!Variable 0C value!!Version!!Callback
|-
|0||1||2A||{{ottdp| | }}||decide the cargo types accepted
|-
|1||2||2E||{{ottdp| | }}||custom cargo production
|-
|2||4||143||{{ottdp| | }}||conditional protection
|-
|3||8||14E||{{ottdp|1.0|2.6|ottdrev=r17558|ttdprev=2249}}||decide if default foundations need to be drawn
|-
|4||10||14F||{{ottdp|1.0|2.6|ottdrev=r17558|ttdprev=2249}}||allow or deny autosloping below the tile
|}

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 variational Action2 for callbacks.

Callback flags are ignored for additional building tiles.

=== House override byte (15) ===

Setting this property makes this building appear instead of the given old TTD building type. Setting the property is ignored if the given old house type is already overridden. You can set this property more than once to override more old building types.

No new house of the overridden types will be built in towns.

This property works in a per-tile basis, so you override tiles of old multi-tile buildings individually, although the old type will still be built if you don't override its north tile.

=== Periodic refresh multiplier (16) ===

This is used for random triggers, and sets how often the tile is re-randomized. When set to X, the tile will be re-randomized on every (X+1)-th periodic processing. (In other words, every (X+1)*256 game ticks.) If you want all tiles to be re-randomized, you must set this (but not necessarily to the same value) for each tile.

If callback 1B is enabled in property 14, it is also called after re-randomizing random bits.

{{ottdp|1.1|2.5|ttdprev=2.5 beta 9}} In TTDPatch versions before TTDPatch 2.6 r1639 and TTDPatch 2.5 beta 9 (including beta 9), this variable could have any value between 0 and 255. After these versions, the upper limit has been lowered to 63. To maintain compatibility, values above 63 will be interpreted as 63.

=== Random colours (17) ===

This specifies four colors used for random painting (see [[Action2HousesIndustryTiles]]). Each byte of the dword defines a color, the values are the same as in Action2, except that numbering starts from zero instead of 775. If not set, this defaults to 04 08 0c 06 (red, blue, orange and green, the colors of the modern office building). Can be set to different values for tiles of multi-tile buildings.

=== Probability (18) ===

This sets the relative probability of this house being built. Old TTD house types have a probability of 16, and this is the default for new types as well.

Increase (or better multiply) this value to make your building appear relatively more often, or decrease (divide) it to make it rarer. If you set this to zero, the house type never appears. The minimal useful value 1 means it's sixteen times less probable to build this type than a normal type, while the maximum setting of 255 means it's almost sixteen times more probable.

The probability is relative since the absolute probability depends on the count and probability of other houses as well: the more types are available (and the higher their probabilities are), the less the chance is that your type will be chosen.

=== Extra Flags (19) ===

{| |-
!Bit!!Value!!Version!!Meaning
|-
|0||1||{{ottdp|0.6|2.5}}||This building appears during the generation of a town, but not later, i.e. will appear in random games, but new ones won't be built during the game. Useful for buildings that are intended to be historical.
|-
|1||2||{{ottdp|0.6|2.5}}||This building is protected, i.e. towns and AI players won't remove it. Human players can still remove it, so you may need to set a high remove cost/rating to make them think twice.
|-
|2||4||{{ottdp|0.6|2.5}}||Synchronized [[Callbacks#Animation_control_.281B.2F25.2F140.2F152.2F159.29| callback 1B]]. (for multi-tile buildings)<ref>If synchronized callbacks are enabled, callback 1B will be called when the periodic processing reaches the main tile of the building, and not when it reaches the current tile. This is useful if your animation must run synchronously on every tile of the building. If this bit is set, callback 1B is called according to the main tile's property 16, not the current one, to make sure every tile stays in sync. This bit can also be set for a subset of the tiles of a house, and will only affect those tiles then.</ref>
|-
|3||8||{{ottdp|0.6|2.5|ttdprev=beta 2}}||[[Callbacks#Next animation frame (1A/26/141/153/158) |Callback 1A]] needs random bits
|}

<references />

=== Animation Frames (1A) ===

The bottom seven bits define how many frames the animation consists of, minus one. (I.e. 0 means 1 frame, 1 means 2 frames etc.) The highest bit has another purpose (see below), so the biggest supported value is 7F (128 frames).

The highest bit is set if the animation is looping, i.e. it should start again from the first frame after showing the last frame. Non-looping animations stop after the last frame, leaving it on the screen. Both kinds of animations start automatically when the building is created. It's recommended to use callback 1B with non-looping animations, so they are played multiple times.

{{ottdp|0.6|2.5|ottdrev=r12347|ttdprev=r1639}} In TTDPatch versions before TTDPatch 2.6 r1639 and TTDPatch 2.5 beta 9 (including beta 9) and OpenTTD before r12347, the frame number was limited to 32. If you intend to maintain compatibility with those versions, you should not use animations longer than 32 frames.

=== Animation Speed (1B) ===

This is the amount of time between switching frames.

The default value is 2, which means the switch occurs every 108 milliseconds. Increasing this value by one doubles the wait, i.e. 3 will cause 216 ms delay, while 4 will pause 432 ms, and so on. Values below 2 have the same effect as 2, so the default is the fastest possible setting. The maximum is 16, which means 1769 seconds (approx. half an hour) delay. Settings above this value may cause strange behaviour.

=== Building Class (1C) ===

Types that were given the same class byte are considered to be in the same class. If you don't explicitly set this value, the type is considered to have no class (it won't be considered to be class 0). The scope of a class is the current GRF file, so two types are never in the same class if they were defined by different GRF files. Currently, this property affects variable 44 only.

This property is a per-tile one, you can set it for additional tiles as well. It's a better idea, however, to set it for the main tile only, since var. 44 counts tiles, not buildings, and you may count multi-tile multiple times otherwise.

=== Accepted cargo types (1E) ===

There may be cases when you want your house to accept something other than the default types (passenger, mail, goods and food). This property allows you to do that. If this property is set to FFFFFFFFh (the default), the meaning of properties 0D, 0E and 0F aren't changed, that is, they are the passenger, mail and goods/food acceptances, accordingly. If this property isn't FFFFFFFFh, the first three bytes must be climate-dependent cargo slot numbers (the fourth byte is ignored). In this case property 0D is the amount of acceptance of the first cargo type given, 0E is the same for the second type and 0F is the same for the third type.

From GRF version 7 and above, the meaning of this property changes: instead of climate-dependent cargo slot numbers, you have to give climate-independent cargo IDs. If your GRF has a cargo translation table, then this ID is the index in that table; otherwise, it's the cargo slot number. Acceptance of cargoes not currently present will automatically be disabled.

{{ottd|15.0}} Since 15.0, a default cargo translation table corresponding to the climate is used if one is not provided.

=== Minimum life span in years (1F) ===

Towns are prevented from destroying the house if it hasn't yet reached the age given here. The default is 0, which means towns are free to remove the house any time they like. Please note that this setting doesn't prevent AI players from removing the house; only towns are affected. If you need to protect your building from AI players as well, you can set the "protected" flag (property 19 bit 1), or use [[Callbacks#Protect building conditionally (143) |callback 143]] and use your custom code to decide who (and when) is allowed to remove the building.

For this to operate consequently on multi-tile buildings, you must set the same minimum lifespan for all tiles of the building.

=== Cargo acceptance watch list (20) ===

This property is a list of cargo types, types whose acceptance should be watched. The first byte is the length of the list, the remaining bytes identify cargo types. {{grfFrom|7}} If your GRF is version 7 or above, and has a cargo translation table, the bytes are indexes in the table; otherwise, they are cargo slot numbers.

When a cargo from this list is accepted by the current tile (i.e. the tile is in the acceptance area of a station), [[Callbacks#Watched cargo accepted (148) |callback 148]] is called on ''all'' tiles of the building:
* The callback will be called for each tile of a multi-tile building whenever a tile with property 20 accepts cargo. This means if more than one tile has cargoes specified in property 20, the callback can be called multiple times on the same tile in the same tick.
* Variable 18 has the format RRRRYYXX
** YYXX: Relative position of the triggering tile to the current tile in X and Y direction. 0 if the current tile is the triggering tile, negative if the triggering tile is northward, positive if southward. With this, you can tell apart the callings within the same tick.
** RRRR: Random bits, same for all tiles of a multi-tile building.

Via [[VariationalAction2/Houses#Cargo_acceptance_history_of_nearby_stations_.2864.29|Variable 64]] the triggering cargo types can be determined.

Return values are the same as for all [[Callbacks#Animation_control_.281B.2F25.2F140.2F152.2F159.29|animation trigger callbacks]].

Due to implementation details, up to 250 game ticks can pass between the actual acceptance and triggering this callback.

{{ttdp|}} This property has no effect if the station2 structure isn't present. The station2 structure is present if any of the following is true:
* Generalfixes is on, and miscmods.noextendstationrange is off
* Any of fifoloading, newcargos or irregularstations is on

=== Availability years (long format) - Minimum (21) - Maximum (22) ===

Those two properties allow to specify a range of dates (based on year zero(0) that are not limited to the 1930 dates. So earlier buildings can be introduced. Be sure to add substantial houses to the sets, if you do not wat to have uniform towns, since the current earliest houses will remain in their current 1920 era. Mind also the warning wrt. introduction years as described at property 0A.

{{ottdp|15|no}} A value of FFFF is treated as the game's MAX_YEAR instead of a literal year 65535.

=== Tile acceptance list (23) ===
{{ottdp|1.9|no|ottdrev=48b334cf}}

Format:
<numinput> (<cargotype> <acceptance>)*

{| |-
!Size!!Variable!!Meaning
|-
|B||numinput||Number of (<cargotype> <acceptance>) pairs to follow,
|-
|B||cargotype||Cargotype (from CTT) to accept.
|-
|B||acceptance||Acceptance in 1/8 units.
|}

This property defines up to 16 cargotypes, which are accepted by the house.
Use this property instead of property 0D..0F.

Action0/Houses

2025-04-16T13:42:17Z

Frosch: /* Extra Flags (19) */

== Introduction ==

For town buildings (or simply houses), the offset defines the first house ID for this action 0. House IDs, like station IDs, are unique within each grf file, and in total each game can only have 255 IDs in TTDPatch and 512 IDs in OpenTTD for all active grf files.

{{ottdp|15}} Since OpenTTD 15, the limits are increased to 4096 IDs, both per-grf and in total.

To start using a house ID, you must first define it by setting its property 08 (see below). If you try to modify a house ID whose property 08 isn't set, your request is ignored, but not reported as an error, either.

== Properties ==

{| |-
!Number!![[GRFActionsDetailed|Size]]!!Version!!Description
|-
|08||B||{{ottdp|0.6|2.5|ttdprev=alpha 34}}||Substitute building type
|-
|09||B||{{ottdp|0.6|2.5|ttdprev=alpha 34}}||Building flags
|-
|0A||W||{{ottdp|0.6|2.5|ttdprev=alpha 34}}||Availability years
|-
|0B||B||{{ottdp|0.6|2.5|ttdprev=alpha 34}}||Population
|-
|0C||B||{{ottdp|0.6|2.5|ttdprev=alpha 34}}||Mail generation multiplier
|-
|0D||B||{{ottdp|0.6|2.5|ttdprev=alpha 34}}||Passenger acceptance
|-
|0E||B||{{ottdp|0.6|2.5|ttdprev=alpha 34}}||Mail acceptance
|-
|0F||B||{{ottdp|0.6|2.5|ttdprev=alpha 34}}||Goods, food or fizzy drinks acceptance
|-
|10||W||{{ottdp|0.6|2.5|ttdprev=alpha 34}}||LA rating decrease on removal (should be set to the same value for every tile for multi-tile buildings)
|-
|11||B||{{ottdp|0.6|2.5|ttdprev=alpha 34}}||Removal cost multiplier (should be set to the same value for every tile for multi-tile buildings)
|-
|12||W||{{ottdp|0.6|2.5|ttdprev=alpha 34}}||Building name ID
|-
|13||W||{{ottdp|0.6|2.5|ttdprev=alpha 34}}||Building availability mask
|-
|14||B||{{ottdp|0.6|2.5|ttdprev=alpha 34}}||House callback flags
|-
|15||B||{{ottdp|0.6|2.5|ttdprev=alpha 34}}||House override byte
|-
|16||B||{{ottdp|0.6|2.5|ttdprev=alpha 34}}||Periodic refresh multiplier
|-
|17||4*B||{{ottdp|0.6|2.5|ttdprev=alpha 35}}||Four random colours to use
|-
|18||B||{{ottdp|0.6|2.5|ttdprev=alpha 35}}||Relative probability of appearing
|-
|19||B||{{ottdp|0.6|2.5|ttdprev=alpha 38}}||Extra flags
|-
|1A||B||{{ottdp|0.6|2.5|ttdprev=alpha 39}}||Animation frames
|-
|1B||B||{{ottdp|0.6|2.5|ttdprev=alpha 39}}||Animation speed
|-
|1C||B||{{ottdp|0.6|2.5|ttdprev=alpha 43}}||Class of the building type
|-
|1D||B||{{ottdp|0.6|2.5|ttdprev=alpha 55 vcs 2}}||Callback flags 2
|-
|1E||D||{{ottdp|0.6|2.5|ttdprev=alpha 55 vcs 2}}||Accepted cargo types
|-
|1F||B||{{ottdp|0.6|2.6|ttdprev=r1554}}||Minimum life span in years
|-
|20||V||{{ottdp|1.2|2.6|ottdrev=r23072|ttdprev=r1677}}||Cargo acceptance watch list
|-
|21||W||{{ottdp|0.7|no|ottdrev=r13437}}||Long year (zero based) of minimum appearance
|-
|22||W||{{ottdp|0.7|no|ottdrev=r13437}}||Long year (zero based) of maximum appearance
|-
|23||V||{{ottdp|1.9|no|ottdrev=48b334cf}}||Tile acceptance list
|-
|24||W n*W||{{ottdp|15}}||List of badges
|}

When a town decides to expand, each active house type (both old and new ones) has a uniform probability to appear, so the more new houses you define, the fewer old TTD buildings will appear.

== Descriptions ==

=== Substitute building type (08) ===

This building type will be used instead of your new one if your definition isn't available for any reason (the grf file is not found, for example).

Don't set a substitute building type that is larger than your new one (for example, don't set 14 (stadium) for an 1x1 building) because this may corrupt savegames. Setting this property automatically copies every property of the substitute building to your new building, so you don't have to change properties that are the same as the substitute.

House flags 40 and 80 are exceptions; these flags are never set automatically. Only the first property 08 setting copies properties; if you later change it, properties will stay.

There's a special use of this property beginning from alpha 72: if you set it to FFh, you can disable an old house type. In this case, the ID used must be the number of old house type you want to disable. Disabling only prevents building the type in towns; houses already present on the map will stay unchanged. The type can still be overridden, and overriding affects houses present on the map.

If this house's action 3 appears before this property is set, the action 3 will have no effect.

=== Building flags (09) ===

{| |-
!Bit!!Value!!Meaning
|-
|0||1||This is a 1x1 building
|-
|1||2||This building can be built only on flat land (if clear, foundations are automatically displayed on sloped land)
|-
|2||4||This is a 2x1 building<ref name="large">If your building isn't 1x1, set flags for the north tile, then define the next 1 or 3 tiles tiles (by setting their property 8). The only bit that can be set in the flags of additional tiles is bit 5 (animation). There should be no property 8 setting between the first tile and the additional tiles.</ref>
|-
|3||8||This is a 1x2 building<ref name="large" />
|-
|4||10||This is a 2x2 building<ref name="large" /><ref>For 2x2 buildings, the first additional tile is the east one, the second is the west part and the third is the south part. You probably want to set the substitute for additional tiles to a TTD additional tile whose flags are already zero. 2x2 buildings are always built on flat land no matter how bit 1 is set.</ref>
|-
|5||20||Animation flag, set in tiles 04 and 05 (large office block). New buildings have a different animation scheme than large office blocks, but animation is still enabled with this bit.<ref>The animation flag works on a per-tile basis, so you should enable it for additional tiles of multi-tile buildings as well if you want all tiles to be animated.</ref>
|-
|6||40||This building is a church<ref name="only1">Only one church and one stadium can exist in a town. The town won't build buildings with the according flag set until the old church/stadium is removed. (This can be done by either the town or a player)</ref>
|-
|7||80||This building is a stadium<ref name="only1" />
|}

<references />

=== Availability years (0A) ===

The low byte is the minimum year, the high is the maximum. The building can only be built between these two years (inclusive). 1920 is added to both bytes before using the values.

{{ottdp|no| }}
Since the year counting stops in TTDPatch in 2070 even with [[ttwiki:EternalGame|EternalGame]] on, start years above 150 mean "never", and end years above 150 mean "forever". In OpenTTD there is no limit for the maximum year (resp. it is 5000000).

'''WARNING:''' Don't set the start year below 1930 (0Ah) unless you know what you're doing!

{{ttdp|}} If TTDPatch finds a building that is available before 1930, it will not build old building types until that year, so you have to provide at least one custom building type that is available before 1930 for every [[TownZones|town zone]], or TTD may deadlock while trying to create a random game or expand a town.

{{ottd|}} The availability of all active houses with the lowest availability year is set to start from year 0, so that always at least one house is available irrespective of starting year. Thus, if you de-activate default houses or set an introduction date prior to the default houses introduction year 1930, you should have at least for each [[TownZones|town zone]] a house with the same earliest availability year or you might end up with a situation where no house can be placed in a [[TownZones|town zone]].

=== Population (0B) and Mail generation multiplier (0C) ===
[[Image:House_production.png|frame|right|Actual house production roughly depends on squared value of the population / mail generation multiplier.]]

The population of the town will be increased by the amount set in prop. 0B if this building is built. Additional house parts should have a population of zero. The higher this value is, the more passengers this building generates.

The higher the mail generation multiplier is, the more mail the building generates. For multi-tile buildings, mail generation is done in per-tile basis, so you can specify different values for every tile, although distributing the generation equally between tiles is suggested.

This is how exactly passengers are generated: In each periodic processing (i.e. every 256 ticks), a random value 0<=X<=255 is generated for each house tile. If X isn't smaller than the population of the tile, no passengers are generated. Otherwise, X/8+1 passengers are generated (rounded down). If there is a recession going on, the number of generated passengers is halved, but this division gets rounded up instead of down. Mail generation happens in a similar manner, but with a new random value, and checking against the mail generation multiplier instead of the population.

You can further customize how the cargo is generated with the [[Callbacks#Custom_cargo_production_.282E.29 |callback 2E]]. 

=== Passenger (0D), Mail (0E) and Good/Food/Fizzy drinks (0F) acceptance ===

The acceptance is given in units of 1/8th and must not be larger than 8 eighths.

For property 0F, positive values indicate that the building accepts goods, and negative values (i.e. FF = 1/8th, FE = 2/8ths etc.) indicate acceptance of food or fizzy drinks, depending on the climate.

All the above three values can be set independently for tiles of multi-tile buildings, since every tile is processed individually when determining what a station accepts.

The type of accepted cargo can be modified using [[Action0Houses#Accepted_cargo_types|property 1E]].

{{ottdp|no| }} Note that in TTDPatch the officefood switch may modify acceptance in the sub-arctic and subtropical climates.

=== Building name ID (12) ===

The ID of the text that should be displayed in the land query window. The name can also be set by [[Action4|action 4]] (see there). Should be set to the same value for every tile for multi-tile buildings.

=== Building availability mask (13) ===

{| |-
!Bit!!Value!!Meaning
|-
|0..4||1,2,4,8,10||which [[VariationalAction2/Houses#Town zone (42)|town zone(s)]] the building can be built in
|-
|11||800||can appear in sub-arctic climate above the snow line
|-
|12||1000||can appear in temperate climate
|-
|13||2000||can appear in sub-arctic climate below the snow line
|-
|14||4000||can appear in subtropical climate
|-
|15||8000||can appear in toyland climate
|}

This property should be set to zero for additional building tiles.

=== House callback flags (14,1D) ===

For houses, the following [[callbacks]] can be defined by setting the corresponding bit in property 14:

{| |-
!Bit!!Value!!Variable 0C value!!Version!!Callback
|-
|0||1||17||{{ottdp| | }}||decide whether the house can be built on a given tile
|-
|1||2||1A||{{ottdp| | }}||decide the following frame of the animations
|-
|2||4||1B||{{ottdp| | }}||periodically start/stop the animation
|-
|3||8||1C||{{ottdp| | }}||change animation when construction state changes
|-
|4||10||1E||{{ottdp| | }}||decide the color of the building
|-
|5||20||1F||{{ottdp| | }}||decide the cargos amounts accepted
|-
|6||40||20||{{ottdp| | }}||decide the length of the current animation frame
|-
|7||80||21||{{ottdp| | }}||trigger destruction of building
|}

Property 1D was introduced after all bits of property 14 were filled. Its usage is the same, only the meaning of bits is different:

{| |-
!Bit!!Value!!Variable 0C value!!Version!!Callback
|-
|0||1||2A||{{ottdp| | }}||decide the cargo types accepted
|-
|1||2||2E||{{ottdp| | }}||custom cargo production
|-
|2||4||143||{{ottdp| | }}||conditional protection
|-
|3||8||14E||{{ottdp|1.0|2.6|ottdrev=r17558|ttdprev=2249}}||decide if default foundations need to be drawn
|-
|4||10||14F||{{ottdp|1.0|2.6|ottdrev=r17558|ttdprev=2249}}||allow or deny autosloping below the tile
|}

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 variational Action2 for callbacks.

Callback flags are ignored for additional building tiles.

=== House override byte (15) ===

Setting this property makes this building appear instead of the given old TTD building type. Setting the property is ignored if the given old house type is already overridden. You can set this property more than once to override more old building types.

No new house of the overridden types will be built in towns.

This property works in a per-tile basis, so you override tiles of old multi-tile buildings individually, although the old type will still be built if you don't override its north tile.

=== Periodic refresh multiplier (16) ===

This is used for random triggers, and sets how often the tile is re-randomized. When set to X, the tile will be re-randomized on every (X+1)-th periodic processing. (In other words, every (X+1)*256 game ticks.) If you want all tiles to be re-randomized, you must set this (but not necessarily to the same value) for each tile.

If callback 1B is enabled in property 14, it is also called after re-randomizing random bits.

{{ottdp|1.1|2.5|ttdprev=2.5 beta 9}} In TTDPatch versions before TTDPatch 2.6 r1639 and TTDPatch 2.5 beta 9 (including beta 9), this variable could have any value between 0 and 255. After these versions, the upper limit has been lowered to 63. To maintain compatibility, values above 63 will be interpreted as 63.

=== Random colours (17) ===

This specifies four colors used for random painting (see [[Action2HousesIndustryTiles]]). Each byte of the dword defines a color, the values are the same as in Action2, except that numbering starts from zero instead of 775. If not set, this defaults to 04 08 0c 06 (red, blue, orange and green, the colors of the modern office building). Can be set to different values for tiles of multi-tile buildings.

=== Probability (18) ===

This sets the relative probability of this house being built. Old TTD house types have a probability of 16, and this is the default for new types as well.

Increase (or better multiply) this value to make your building appear relatively more often, or decrease (divide) it to make it rarer. If you set this to zero, the house type never appears. The minimal useful value 1 means it's sixteen times less probable to build this type than a normal type, while the maximum setting of 255 means it's almost sixteen times more probable.

The probability is relative since the absolute probability depends on the count and probability of other houses as well: the more types are available (and the higher their probabilities are), the less the chance is that your type will be chosen.

=== Extra Flags (19) ===

{| |-
!Bit!!Value!!Version!!Meaning
|-
|0||1||{{ottdp|0.6|2.5}}||This building appears during the generation of a town, but not later, i.e. will appear in random games, but new ones won't be built during the game. Useful for buildings that are intended to be historical.
|-
|1||2||{{ottdp|0.6|2.5}}||This building is protected, i.e. towns and AI players won't remove it. Human players can still remove it, so you may need to set a high remove cost/rating to make them think twice.
|-
|2||4||{{ottdp|0.6|2.5}}||Synchronized [[Callbacks#Animation_control_.281B.2F25.2F140.2F152.2F159.29| callback 1B]]. (for multi-tile buildings)<ref>If synchronized callbacks are enabled, callback 1B will be called when the periodic processing reaches the main tile of the building, and not when it reaches the current tile. This is useful if your animation must run synchronously on every tile of the building. If this bit is set, callback 1B is called according to the main tile's property 16, not the current one, to make sure every tile stays in sync. This bit can also be set for a subset of the tiles of a house, and will only affect those tiles then.</ref>
|-
|3||8||{{ottdp|0.6|2.5|ttdprev=beta 2}}||[[Callbacks#Next animation frame (1A/26/141/153/158) |Callback 1A]] needs random bits
|}

<references />

=== Animation Frames (1A) ===

The bottom seven bits define how many frames the animation consists of, minus one. (I.e. 0 means 1 frame, 1 means 2 frames etc.) The highest bit has another purpose (see below), so the biggest supported value is 7F (128 frames).

The highest bit is set if the animation is looping, i.e. it should start again from the first frame after showing the last frame. Non-looping animations stop after the last frame, leaving it on the screen. Both kinds of animations start automatically when the building is created. It's recommended to use callback 1B with non-looping animations, so they are played multiple times.

{{ottdp|0.6|2.5|ottdrev=r12347|ttdprev=r1639}} In TTDPatch versions before TTDPatch 2.6 r1639 and TTDPatch 2.5 beta 9 (including beta 9) and OpenTTD before r12347, the frame number was limited to 32. If you intend to maintain compatibility with those versions, you should not use animations longer than 32 frames.

=== Animation Speed (1B) ===

This is the amount of time between switching frames.

The default value is 2, which means the switch occurs every 108 milliseconds. Increasing this value by one doubles the wait, i.e. 3 will cause 216 ms delay, while 4 will pause 432 ms, and so on. Values below 2 have the same effect as 2, so the default is the fastest possible setting. The maximum is 16, which means 1769 seconds (approx. half an hour) delay. Settings above this value may cause strange behaviour.

=== Building Class (1C) ===

Types that were given the same class byte are considered to be in the same class. If you don't explicitly set this value, the type is considered to have no class (it won't be considered to be class 0). The scope of a class is the current GRF file, so two types are never in the same class if they were defined by different GRF files. Currently, this property affects variable 44 only.

This property is a per-tile one, you can set it for additional tiles as well. It's a better idea, however, to set it for the main tile only, since var. 44 counts tiles, not buildings, and you may count multi-tile multiple times otherwise.

=== Accepted cargo types (1E) ===

There may be cases when you want your house to accept something other than the default types (passenger, mail, goods and food). This property allows you to do that. If this property is set to FFFFFFFFh (the default), the meaning of properties 0D, 0E and 0F aren't changed, that is, they are the passenger, mail and goods/food acceptances, accordingly. If this property isn't FFFFFFFFh, the first three bytes must be climate-dependent cargo slot numbers (the fourth byte is ignored). In this case property 0D is the amount of acceptance of the first cargo type given, 0E is the same for the second type and 0F is the same for the third type.

From GRF version 7 and above, the meaning of this property changes: instead of climate-dependent cargo slot numbers, you have to give climate-independent cargo IDs. If your GRF has a cargo translation table, then this ID is the index in that table; otherwise, it's the cargo slot number. Acceptance of cargoes not currently present will automatically be disabled.

{{ottd|15.0}} Since 15.0, a default cargo translation table corresponding to the climate is used if one is not provided.

=== Minimum life span in years (1F) ===

Towns are prevented from destroying the house if it hasn't yet reached the age given here. The default is 0, which means towns are free to remove the house any time they like. Please note that this setting doesn't prevent AI players from removing the house; only towns are affected. If you need to protect your building from AI players as well, you can set the "protected" flag (property 19 bit 1), or use [[Callbacks#Protect building conditionally (143) |callback 143]] and use your custom code to decide who (and when) is allowed to remove the building.

For this to operate consequently on multi-tile buildings, you must set the same minimum lifespan for all tiles of the building.

=== Cargo acceptance watch list (20) ===

This property is a list of cargo types, types whose acceptance should be watched. The first byte is the length of the list, the remaining bytes identify cargo types. {{grfFrom|7}} If your GRF is version 7 or above, and has a cargo translation table, the bytes are indexes in the table; otherwise, they are cargo slot numbers. When a cargo from this list is accepted by the current tile, [[Callbacks#Watched cargo accepted (148) |callback 148]] is called on ''all'' tiles of the building. See [[Callbacks#Watched cargo accepted (148) |callback 148]] for more details about how this happens.

{{ttdp|}} This property has no effect if the station2 structure isn't present. The station2 structure is present if any of the following is true:
* Generalfixes is on, and miscmods.noextendstationrange is off
* Any of fifoloading, newcargos or irregularstations is on

=== Availability years (long format) - Minimum (21) - Maximum (22) ===

Those two properties allow to specify a range of dates (based on year zero(0) that are not limited to the 1930 dates. So earlier buildings can be introduced. Be sure to add substantial houses to the sets, if you do not wat to have uniform towns, since the current earliest houses will remain in their current 1920 era. Mind also the warning wrt. introduction years as described at property 0A.

{{ottdp|15|no}} A value of FFFF is treated as the game's MAX_YEAR instead of a literal year 65535.

=== Tile acceptance list (23) ===
{{ottdp|1.9|no|ottdrev=48b334cf}}

Format:
<numinput> (<cargotype> <acceptance>)*

{| |-
!Size!!Variable!!Meaning
|-
|B||numinput||Number of (<cargotype> <acceptance>) pairs to follow,
|-
|B||cargotype||Cargotype (from CTT) to accept.
|-
|B||acceptance||Acceptance in 1/8 units.
|}

This property defines up to 16 cargotypes, which are accepted by the house.
Use this property instead of property 0D..0F.

Action0/Road Stops

2025-04-15T11:46:14Z

Frosch: /* Animation triggers (10) */

==Introduction==
Defining properties of road stops.

Road stop IDs may be freely chosen. In action 0, you need only specify IDs relative to the set, i.e. the ID of the first road stop type is 00, the second road type is 01 and so on.

OpenTTD supports 64000 road stops per game, and 64000 road stop IDs per GRF file.

The property you '''must''' set for each road stop ID is 08 (in addition to defining an action 3 for it). Also, all road stop IDs must get their classes in the right order, starting from ID 00 onwards.

== Properties ==
{|
!Number!![[GRFActionsDetailed|Size]]!!Version!!Description
|-
|08||D||{{ottdp|14}}||Class label, see below
|-
|09||B||{{ottdp|14}}||Road stop type
|-
|0A||W||{{ottdp|14}}||Road stop name text ID
|-
|0B||W||{{ottdp|14}}||Class name text ID
|-
|0C||B||{{ottdp|14}}||Draw mode
|-
|0D||D||{{ottdp|14}}||Random trigger cargoes
|-
|0E||W||{{ottdp|14}}||Animation information
|-
|0F||B||{{ottdp|14}}||Animation speed
|-
|10||W||{{ottdp|14}}||Animation triggers
|-
|11||B||{{ottdp|14}}||Callback flags, see below
|-
|12||D||{{ottdp|14}}||General flags, see below
|-
|15||W||{{ottdp|14}}||Cost multipiers, see below
|-
|16||W n*W||{{ottdp|15}}||List of badges
|}

== Descriptions ==

=== Road stop class (08) ===

New road stops are grouped graphics into classes.

Only two classes are pre-defined:

{| |-
!Name!!Class ID!!Intended use for road stops
|-
|DFLT||44 46 4C 54||Default road stops
|-
|WAYP||57 41 59 50||{{ottdp|15}} Road waypoints
|}

{{ottdp|15}} Road stop classes which start with the byte FF are considered road waypoint classes, and will appear in the road waypoint construction window instead of the road bus/truck stop construction windows.

It is recommended that the class identifier used is unique to your GRF(s).

=== Road stop type (09) ===

{| |-
!Value!!Meaning
|-
|0||Passenger/bus stop
|-
|1||Freight/lorry stop
|-
|2||Both passenger/bus and freight/lorry stops
|}

The default value is 2: Both passenger/bus and freight/lorry stops

=== Road stop name text ID (0A) ===

The text ID for this road stop (word value). This textid should be either a TTD textid or a D4xx textid (set via D0xx in action4).

=== Class name text ID (0B) ===

The text ID for the road stop class.

When specifying a road stop, you don't need to set a class name again if you already did for another one with the same class.

=== Draw mode (0C) ===

{| |-
!Bit!!Value!!Meaning
|-
|0||1||Bay stops: Draw road type ground sprite
|-
|1||2||Drive through stops: Draw road/tram type overlays
|-
|2||4||{{ottdp|15}} Road waypoints: Draw the sprite layout ground tile (on top of the road)
|}

The default value is 3 (bits 0 and 1 both set).

The remaining bits are reserved for future use.

=== Cargo types for random triggers (0D) ===

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

=== Animation information (0E) ===

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 (0F) ===
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 (10) ===
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

Roadstops have the same animation triggers as [[Action0/Stations#Animation_triggers_.2818.29|rail stations]].

=== Callback flags (11) ===
For road stops, 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 the road stop available in construction window (non-zero callback return) or not (callback returns zero)
|-
|1||2||141||Decide next animation frame
|-
|2||4||142||Decide animation speed
|}
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.

=== General Flags (12) ===

{| |-
!Bit!!Value!!Meaning
|-
|0||1||[[Callbacks#Next animation frame (1A/26/141/153/158)|callback 141]] needs random bits in var. 10
|-
|2||4||Do not show catenary graphics
|-
|3||8||Only allow drive-through stops (not bay stops)
|-
|4||10||Do not automatically build connecting road pieces
|-
|5||20||Only show in the road build menu (not tram)
|-
|6||40||Only show in the tram build menu (not road)
|-
|8||100||{{ottdp|15}} Read the draw mode from register 0x100, overriding the default value in property 0C

|}

The default value is 0 (no bits set).

The remaining bits are reserved for future use.

=== Cost multipiers (15) ===

The first byte is the build cost multiplier.

The second byte is the removal cost multiplier.

The total property length is 2 bytes.

A value of 16 produces a build or removal cost the same as non-NewGRF road stops.

== Examples ==

Callback: Animation control

2025-04-15T11:45:06Z

Frosch: roadstops

== Animation control (1B/25/140/152/159) ==

Called periodically, in a time interval specified in property 16 (houses) or when an animation trigger happens (industry tiles, stations, roadstops, airport tiles and objects). Returns the number of the frame the animation should jump to, or one of the following special values:

{| |-
!Value!!Meaning
|-
|FF||stop animation in its current frame
|-
|FE||start animation with its current frame
|-
|FD||leave the animation in its current state (do nothing)
|}

* For multi-tile town buildings, [[Action0/Houses#Extra_Flags_.2819.29|property 19/bit 2]] modifies this callback slightly, see details there.

* Except for CB 1B (houses), the low byte of variable 18 contains the reason (animation trigger) for the call. This is formatted as the number of the bit that was set in the relevant action 0 property. The other bits may contain additional information specific for the trigger/reason.
:{| |-
! Feature !! Callback !! Animation triggers
|-
| Houses || 1B || none
|-
| Industry tiles || 25 || [[Action0/Industry_Tiles#Triggers_for_callback_25_.2811.29|Property 11]]
|-
| Stations/Roadstops || 140 || [[Action0/Stations#Animation_triggers_.2818.29|Property 18]]
|-
| Airport tiles || 152 || [[Action0/Airport_Tiles#Animation_triggers_via_callback_153_.2811.29|Property 11]]
|-
| Objects || 159 || [[Action0/Objects#Animation_triggers_.2813.29|Property 13]]
|}

* Except for CB 1B (houses), the callbacks are always used when defined, no bit in the action 0 property needs to be set to activate them.

* {{ottdp| |2.5|ttdprev=beta 2}} Since TTDPatch 2.5 beta 2, these callbacks get random bits in variable 10, to allow randomizing changes.

* For callback 1B (houses), the exact randomness depends on bit 2 of [[Action0/Houses#Extra_Flags_.2819.29|property 19]] (synchronized callback 1B). If the callback is synchronized, the high 16 bits will be the same for all tiles and the low 16 bits will be different for each tile. Otherwise, all 32 bits will be independent for each tile.

* For CB 25 (industry tiles), the randomness depends on the type of the event. For triggers that happen for the whole industry (triggers 2, 3 and 4), the high 16 bits will be the same for all tiles, while the low 16 bits will be different. For other triggers, all 32 bits are independent.

* For CB 140 (stations, roadstops), the high 16 bits are the same for all tiles triggered, while the low 16 bits are different for each tile.

* Like all animation callbacks, if the high byte of the result is nonzero, it will be interpreted as a sound effect number, and the corresponding sound effect will be played at the tile.
[[Category:Callbacks]]

Note: Every time the animation frame is changed the map tile will be refreshed, even if the selected graphics stay the same. Therefore using the animation frame as a timer should be avoided, and animation triggers should be preferred instead.

Callback: Next animation frame

2025-04-15T11:42:10Z

Frosch: roadstops

== Next animation frame (1A/26/141/153/158) ==

Called in every animation frame, this callback returns the number of the next frame to display. Additionally, it can return these special values:

{| |-
!Value!!Meaning
|-
|FF||stop animation. The current frame stays on screen until the animation is restarted.
|-
|FE||continue with next frame as usual. You can return this for stages where you don't want to do anything special.
|}

{{ottdp| |2.5|ttdprev=beta 2}} From TTDPatch 2.5 beta 2, you can ask for random bits in variable 10. To enable this, set bit 3 of property 19 for houses, bit 0 of property 12 for industry tiles, bit 2 of property 13 for stations, bit 0 of property 12 for roadstops, or bit 12 of property 10 for objects.

Like all animation callbacks, if the high byte of the result is nonzero, it will be interpreted as a sound effect number, and the corresponding sound effect will be played at the tile.
[[Category:Callbacks]]

Note: Every time the animation frame is changed the map tile will be refreshed, even if the selected graphics stay the same. Therefore using the animation frame as a timer should be avoided, and animation triggers should be preferred instead.

Callback: Station availability

2025-04-15T11:39:39Z

Frosch: roadstops

== Station/Rodstop availability (13) ==

This sets whether a station/roadstop can be constructed or not, i.e. whether it can be selected in the station construction window.  Returning 1 as callback return indicates the station can be built, and a return code of 0 removes the station from the selection.

{{grfTill|7}} Note that GRF versions 7 and lower only distinguished zero and non-zero return values.
[[Category:Callbacks]]

Callbacks

2025-04-15T11:37:50Z

Frosch: roadstops

==Introduction==

A callback is a special action 2 that the patch "calls" in order to modify various features, an example being the visual effect of train vehicles.  See the [[ttwiki:CallbacksTut|callback tutorial]] on how to use them.

In the final action 2 of a chain of VarAction2s, the second byte of the matching entry has to have bit 7 set to identify it as a callback result.

For example, 04 00 is not a callback result (but it may be the ID of another chained action 2), whereas 04 80 is a callback result with a value of 4. In total a callback has 15 bit result values, where the upper 7 bits are stored in the second byte. For example, 54 C2 is a callback result with a value of 4254=16980, where again the second byte has bit 7 set, changing the 42 into C2.

{{grfTill|7}} For GRF version 7 and below not all 15 bit values are available as return values, only values between 00 and 7EFF.
For compatibility with earlier patch versions, FF in the high byte is taken to mean the same thing as 80, so 04 FF also has a callback result of 4. Note that if your grf file needs to be compatible with versions before TTDPatch 2.0.1 alpha 40, you must set the high byte to FF, and so can use only 8 bit results.

{{grfFrom|8}} For GRF version 8 and above this compatibility layer has been removed. Callbacks can return all 15 bit values between 00 and 7FFF.

To check for a specific callback, use an [[VariationalAction2]] or [[VarAction2Advanced]] to check for variable 0C.
* Variable 0C contains the callback number.
* Variable 0C is a word, thus the VarAction2 must use type 85.
* Results can be specified directly using 8xxx values (see above), or with 8xxx value in subsequent (Basic/Variational/Random)Action2 which are referenced as usual with their set-id.
* The default case of the VarAction2 must point to the regular graphics chain, so that unknown/future callbacks results in a "callback failure" result.

Example:
<Sprite-number> * <Length> 02 <feature> <set-id> 85 0C 00 \wxFFFF
<nvar> (<set-id/result> \wx <callback> \wx <callback>){n}
<set-id of graphics chain>

The format for VarAction2 is explained in detail on the [[VariationalAction2]] page.

== List of callbacks ==

The following callbacks are defined by the patch.  The number of the callback is what will be stored in variable 0C so that you can return the right results if you have several callbacks.  All callbacks are explained in more detail below.

'''PLEASE NOTE:''' Since TTDPatch 2.5 beta 5, the size of variable 0C has changed, and now there are word-sized callback numbers as well. To maintain backwards compatibility, only callbacks 10..3F can be checked using a byte-sized check. Callbacks 140 and above, on the other hand, must be checked using a word or dword sized check, to make sure they are identified uniquely.

{| |-
!Number!!Feature(s)!!Meaning
|-
|10||Vehicles||[[Callback: Visual effect and wagon power|Visual effect and wagon power]]
|-
|11||Vehicles||[[Callback: Wagon length|Wagon length]]
|-
|12||Vehicles||[[Callback: Load amount|Load amount]]
|-
|13||Stations/Roadstops||[[Callback: Station availability|Station availability]]
|-
|14||Stations||[[Callback: Station sprite layout|Select sprite layout]]
|-
|15||Vehicles||[[Callback: Refitted capacity callback|Refitted capacity callback]]
|-
|16||Trains||[[Callback: Articulated engine|Build articulated engines]]
|-
|17||Houses||[[Callback: House construction check|House construction check]]
|-
|18||Several <ref name="generic">Generic callbacks are called for the feature, not any specific vehicle ID. Read the [[Action3#n-id|Action 3]] entry on how to define these.</ref>||[[Callback: AI construction/purchase selection|AI construction/purchase selection]]
|-
|19||Vehicles||[[Callback: Cargo Subtype Display|Cargo sub-type display]]
|-
|1A||Houses||Next animation frame
|-
|1B||Houses||Animation control
|-
|1C||Houses||Construction stage changes
|-
|1D||Trains||Can wagon be attached
|-
|1E||Houses||Decide colour of building
|-
|1F||Houses||Cargo acceptance
|-
|20||Houses||Length of animation frame
|-
|21||Houses||Trigger building destruction
|-
|22||Industries||Availability
|-
|23||Vehicles||Additional text in purchase screen
|-
|24||Stations||Custom station layout
|-
|25||Industry tiles||Animation control
|-
|26||Industry tiles||Next animation frame
|-
|27||Industry tiles||Length of animation frame
|-
|28||Industries||Industry location permissibility
|-
|29||Industries||Random production change
|-
|2A||Houses||Get accepted cargo types
|-
|2B||Industry tiles||Decide cargo acceptance
|-
|2C||Industry tiles||Get accepted cargo types
|-
|2D||Vehicles||Select colour mapping for vehicle
|-
|2E||Houses||Custom cargo production
|-
|2F||Industry tiles||Custom shape check
|-
|30||Industry tiles||Decide drawing default foundations
|-
|31||Vehicles||Start/stop check
|-
|32||Vehicles||32-day callback
|-
|33||Several||Sound effect callback
|-
|34||Vehicles <ref name="generic"/>||Autoreplace vehicle selection
|-
|35||Industries||Monthly random production change
|-
|36||Vehicles||Change vehicle Properties
|-
|37||Industries||Cargo sub-type display
|-
|38||Industries||Show additional text in fund window
|-
|39||Cargoes||Custom profit calculation
|-
|3A||Industries||Show additional text in industry window
|-
|3B||Industries||Control special effects
|-
|3C||Industry tiles||Disable autosloping
|-
|3D||Industries||Opt out of accepting cargo
|-
|40..13F|| ||--Reserved--
|-
|140||Stations/Roadstops||Animation control
|-
|141||Stations/Roadstops||Next animation frame
|-
|142||Stations/Roadstops||Length of animation frame
|-
|143||Houses||Protect building conditionally
|-
|144||Sounds <ref name="generic"/>||{{ottdp|1.2|2.6|ottdrev=r23144|ttdprev=r821}} Ambient sound effects
|-
|145||Cargoes||Custom station rating calculation
|-
|146||New Signals <ref name="generic"/>||New signals sprite drawing
|-
|147||Canals||Add sprite offset
|-
|148||Houses||Watched cargo accepted
|-
|149||Stations||Land slope check
|-
|14A||Industries||Decide industry color
|-
|14B||Industries||Decide input cargo types
|-
|14C||Industries||Decide output cargo types
|-
|14D||Houses||Customized building name
|-
|14E||Houses||Decide drawing default foundations
|-
|14F||Houses||Disable autosloping
|-
|150||Airport tiles||{{ottdp|1.1|no|ottdrev=r19197}} Decide drawing default foundations
|-
|152||Airport tiles||{{ottdp|1.1|no|ottdrev=r19197}} Animation control
|-
|153||Airport tiles||{{ottdp|1.1|no|ottdrev=r19197}} Next Animation frame
|-
|154||Airport tiles||{{ottdp|1.1|no|ottdrev=r19197}} Length of animation frame
|-
|155||Airports||{{ottdp|1.1|no|ottdrev=r20373}} Extra information about airport layout in the build gui
|-
|156||Airports||{{ottdp|1.1|no|ottdrev=r20373}} Airport layout name
|-
|157||Objects||Land slope check
|-
|158||Objects||Next animation frame
|-
|159||Objects||Animation control
|-
|15A||Objects||Length of animation frame
|-
|15B||Objects||Decide colour of building
|-
|15C||Objects||Show additional text in building window
|-
|15D||Objects||Disable autosloping
|-
|15E||Vehicles||{{ottdp|1.2|no|ottdrev=r23124}} Refit cost factor
|-
|15F||Industries||{{ottdp|1.3|no|ottdrev=r24186}} Set initial production level on construction
|-
|160||Vehicles||{{ottdp|1.5|no|ottdrev=r26747}} Advanced effect creation
|-
|161||Vehicles||{{ottdp|14|no|ottdrev=g05ed9f56fd}} Engine name
|-
|162||Vehicles||{{ottdp|14|no|ottdrev=gddd609ce9b}} Probability of reversing rail vehicle on build
|-
|163||Vehicles||{{ottdp|15|no|ottdrev=gd2496b6ec4}} Custom refit
|}
<references/>

{{:Callback: Visual effect and wagon power}}
{{:Callback: Wagon length}}
{{:Callback: Load amount}}
{{:Callback: Station availability}}
{{:Callback: Station sprite layout}}
{{:Callback: Refitted capacity callback}}
{{:Callback: Articulated engine}}
{{:Callback: House construction check}}
{{:Callback: AI construction/purchase selection}}
{{:Callback: Cargo Subtype Display}}
{{:Callback: Next animation frame}}
{{:Callback: Animation control}}
{{:Callback: Construction stage changes}}
{{:Callback: Can wagon be attached}}
{{:Callback: Building colour}}
{{:Callback: Cargo acceptance}}
{{:Callback: Length of animation frame}}
{{:Callback: Trigger building destruction}}
{{:Callback: Industry availability}}
{{:Callback: Additional text in purchase screen}}
{{:Callback: Custom station layout}}
{{:Callback: Industry location permissibility}}
{{:Callback: Random production change}}
{{:Callback: Get accepted cargo types}}
{{:Callback: Decide cargo acceptance}}
{{:Callback: Select colour mapping for vehicle}}
{{:Callback: Custom cargo production}}
{{:Callback: Custom shape check}}
{{:Callback: Decide drawing default foundations}}
{{:Callback: Vehicle Start/stop check}}
{{:Callback: 32-day callback}}
{{:Callback: Sound effect}}
{{:Callback: Autoreplace vehicle selection}}
{{:Callback: Monthly random production change}}
{{:Callback: Change vehicle properties}}
{{:Callback: Cargo sub-type display for industries}}
{{:Callback: Show additional text in fund/building window}}
{{:Callback: Custom profit calculation for cargoes}}
{{:Callback: Show additional text in industry window}}
{{:Callback: Control special industry effects}}
{{:Callback: Disable autosloping}}
{{:Callback: Opt out of accepting cargo}}
{{:Callback: Protect building conditionally}}
{{:Callback: Ambient sound effects}}
{{:Callback: Custom station rating calculation}}
{{:Callback: New signals sprite drawing callback}}
{{:Callback: Add sprite offset callback}}
{{:Callback: Watched cargo accepted}}
{{:Callback: Station slope check}}
{{:Callback: Decide industry colour}}
{{:Callback: Decide input and output cargo types}}
{{:Callback: Customized building name}}
{{:Callback: Extra information about layout in the build gui}}
{{:Callback: Layout name}}
{{:Callback: Object slope check}}
{{:Callback: Decide object colour}}
{{:Callback: Refit cost factor}}
{{:Callback: Set initial production level on construction}}
{{:Callback: Advanced effect creation}}
{{:Callback: Engine name}}
{{:Callback: Build probability}}
{{:Callback: Custom refit}}

RandomAction2

2025-04-15T11:26:03Z

Frosch: roadstops

==Introduction==

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

== Format ==

The data looks as follows:

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

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

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

{| |-
!'''Element'''!![[GRFActionsDetailed|'''Size''']]!!'''Description'''
|-
|<Sprite-number>||dec||A sequential sprite number
|-
|<length>||dec||The total number of bytes used in this action.
|-
|02||B||Defines action 02
|-
|<feature>||B||For what type of vehicle/station/... should this definition be used?
|-
|<set-id>||B||The ID of this action 2 (used like a cargo ID)
|-
|80, 83, 84||B||Type of random action, see below.
|-
|<count>||B||(when present) Location of controlling vehicle.
|-
|<random-triggers>||B||When to re-randomize
|-
|<randbit>||B||What random bit to use for this action 2
|-
|<nrand>||B||Number of set-ids to choose from, must be a power of 2
|-
|<set-ids>||W||Action 2 set-ids to choose from.
|}

== Description ==

=== Sprite-number ===

This is just the number you are at.

=== Length ===

Count the number of bytes in this action.

===Feature===

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

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

=== set-ID ===

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

=== 80/83/84 ===

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

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

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

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

=== count ===

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

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

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

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

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

=== random-triggers ===

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

Trigger bits are feature-specific, see below.

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

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

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

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

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

=== randbit ===

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

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

=== nrand ===

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

=== set-ids ===

Action 2 IDs to randomly choose from

== Triggers ==

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

=== Vehicles ===

Vehicles have 8 random bits, increased to 16 since {{ottdp|14.0|no}}, and the following triggers:

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

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

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

=== Stations ===

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

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

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

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

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

=== Town building triggers ===

Town buildings have 8 random bits.

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

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

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

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

=== Industry tile triggers ===

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

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

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

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

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

=== Canals ===

Canals / Rivers have 8 random bits.

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

=== Objects ===

Objects have 8 random bits per tile of the object.

There are no triggers for objects however.

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

=== Railtypes ===

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

There are no triggers.

=== Roadtypes ===

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

There are no triggers.

=== Tramtypes ===

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

There are no triggers.

=== Road stops ===

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

{| |-
!Bit!!Value!!Version!!Trigger
|-
|0||01||{{ottdp|14}}||new cargo waiting
|-
|1||02||{{ottdp|14}}||no more cargo
|-
|2||04||{{ottdp|14}}||road vehicle arrives (starts unloading/loading)
|-
|3||08||{{ottdp|14}}||road vehicle leaves (done unloading & loading)
|-
|4||10||{{ottdp|14}}||road vehicle loads or unloads cargo
|}

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

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

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

=== Other features ===

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

==Example==

NML:Switch

2025-04-14T14:55:14Z

Frosch: update parent scopes

{{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="wikitable sortable"
! Feature
! SELF
! PARENT
! permanent 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
| Town
| 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
|-
| FEAT_ROADTYPES
| Roadtype on tile
| N/A
| no
|-
| FEAT_TRAMTYPES
| Tramtype on tile
| N/A
| no
|-
| FEAT_ROADSTOPS
| Road stop
| Town
| 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.

VariationalAction2/Roadtypes

2025-04-13T11:29:55Z

Frosch: variable 45

==Introduction==

== Variables ==

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

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

'''Format:''' byte

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

=== Enhanced tunnels (41) ===

'''Format:''' byte

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

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

'''Format:''' byte

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

=== Track types (45) ===

'''Format:''' __RRttrr
* rr: Translated roadtype.
* tt: Translated tramtype.
* RR: Translated railtype.
* __: reserved for future use

Special values for rr, tt, RR:
* 0xFF: Track not present on tile.
* 0xFE: Track present, but no matching entry in translation table.

==Example==

VariationalAction2/Railtypes

2025-04-13T11:29:12Z

Frosch: variable 45

==Introduction==

== Variables ==

{| |-
!Variable !![[GRFActionsDetailed|Size]]!!Version !! Description
|-
|10||D||{{ottdp|1.3|ottdrev=r24367}}||Additional information for sprite selection - See [[Action3/Railtypes#Signal_sprites_.280B.29|Action3 Signals]]
|-
|18||D||{{ottdp|1.3|ottdrev=r24367}}||Additional information for sprite selection - See [[Action3/Railtypes#Signal_sprites_.280B.29|Action3 Signals]]
|-
|40||B||{{ottdp|1.0|ottdrev=r19056}}||Terrain type: 0 normal, 1 desert, 2 rainforest, 4 on or above snowline.
|-
|41||B||{{ottdp|1.0|ottdrev=r19056}}||Enhanced tunnels; entrance has track above. Always 0 in OpenTTD.
|-
|42||B||{{ottdp|1.0|ottdrev=r19056}}||Level crossing status: 0 if open (or not a crossing), 1 if closed.
|-
|43||D||{{ottdp|1.0|ottdrev=r19056}}||Depot construction date (long format, 0 based); other: current date
|-
|44||B||{{ottdp|1.2|ottdrev=r23866}}||[[TownZones|Town zone]] of the tile. (Only available for level crossings and depots.)
|-
|45||D||{{ottdp|15}}||Track types
|}

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

'''Format:''' byte

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

=== Enhanced tunnels (41) ===

'''Format:''' byte

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

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

'''Format:''' byte

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

=== Track types (45) ===

'''Format:''' __RRttrr
* rr: Translated roadtype.
* tt: Translated tramtype.
* RR: Translated railtype.
* __: reserved for future use

Special values for rr, tt, RR:
* 0xFF: Track not present on tile.
* 0xFE: Track present, but no matching entry in translation table.

==Example==

File:Max tile sprite size.png

2025-04-04T14:02:33Z

Frosch: Frosch uploaded a new version of File:Max tile sprite size.png

== Summary ==
Maximum visible size of sprites on tiles.
Applies since OpenTTD 1.5.

NML:Spritelayout

2025-04-04T13:57:03Z

Frosch: Undo revision 4973 by Frosch (talk)

{{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, automatically choosen from sea, river and canal sprites, including river and canal borders.
* <code style="color:darkgreen">GROUNDSPRITE_CLEARED <ref name="spritenames" /></code> ground tile that has just been bulldozed (with brown colour)
* <code style="color:darkgreen">GROUNDSPRITE_RAIL_X <ref name="spritenames" /></code> ground tile with rail and terrain appropriate ground, NE-SW orientation (provided by railtype)
* <code style="color:darkgreen">GROUNDSPRITE_RAIL_Y <ref name="spritenames" /></code> ground tile with rail and terrain appropriate ground, NW-SE orientation (provided by railtype)

<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.
* For road stops the usage of the ground sprite depends on the [[NML:Roadstops#List of draw mode flags|''draw_mode'' property]].
* For objects the usage of the ground sprite may be skipped depending on the [[NML:Objects#List of object flags|''OBJ_FLAG_DRAW_WATER'' flag]], which has the same effect as ''GROUNDSPRITE_WATER''.

===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. '''Unless you know exactly what you are doing, please follow the recommendations below. They are most likely exactly what you need'''. 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. Default value is 0.
** <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. Default value is 0.
** <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. Default value is 0.
** <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. Default value is 16.
** <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. Default value is 16.
** <code style="color:darkgreen">zextent</code>: Size of the bounding box, in the Z-direction. Must be a compile-time constant. Unit is pixels. Default value is 16.
* <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.

===Strong recommendations for bounding boxes===

For industries, houses, objects, and non-track station tiles:
* Use at most one building sprite; and child sprites for everything else.
** Do not set ''xoffset'', ''yoffset'' or ''zoffset''. The default value 0 applies.
** Do not set ''xextent'' or ''yextent''. The default value 16 applies.
** Set ''zextent'' to "<number of occupied height levels> * 8 - 2". The number of occupied height levels is important for objects allowed under bridges. Otherwise this only needs to be a rough estimate.
* If no sprite visually extends over the ground sprite, you do not need any building sprite: Child sprites can be used for further sprites.

For rail station track tiles:
* Use child sprites of the ground sprite for things "below the train".
* Use exactly two building sprites, possibly with child sprites.
* The first building sprite is used for things "behind the train".
** Set ''xoffset'', ''yoffset'', ''zoffset'' to 0.
** For track in X direction: Set ''xextent'' to 16, ''yextent'' to 5.
** For track in Y direction: Set ''xextent'' to 5, ''yextent'' to 16.
** Set ''zextent'' to "<number of occupied height levels> * 8 - 2". A rough estimate is good enough.
* The second building sprite is used for things "in-front or above the train".
** For track in X direction: Set ''xoffset'' to 0, ''yoffset'' to 11.
** For track in Y direction: Set ''xoffset'' to 11, ''yoffset'' to 0.
** Set ''zoffset'' to 0.
** For track in X direction: Set ''xextent'' to 16, ''yextent'' to 5.
** For track in Y direction: Set ''xextent'' to 5, ''yextent'' to 16.
** Set ''zextent'' to "<number of occupied height levels> * 8 - 2". A rough estimate is good enough.

===Maximum sprite size===

Ground sprites and their child sprites must not extend over the edges of a regular ground sprite of the slope.

Building sprites and their child sprites:
* must not extend below the south tile edges,
* must not extend left/right of the west/east tile corners,
* must not extend above the north corner by more than 200 pixels including the (default) foundation. If foundations are present, this is reduced by up to 16 pixels (steep slope S) to 184 pixels.

The following image shows the limitations for flat tiles, and the extreme cases of steep slopes:

[[File:Max_tile_sprite_size.png]]

These values apply since {{ottd|1.5}}.

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

2025-04-04T13:47:45Z

Frosch: /* Maximum sprite size */

{{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, automatically choosen from sea, river and canal sprites, including river and canal borders.
* <code style="color:darkgreen">GROUNDSPRITE_CLEARED <ref name="spritenames" /></code> ground tile that has just been bulldozed (with brown colour)
* <code style="color:darkgreen">GROUNDSPRITE_RAIL_X <ref name="spritenames" /></code> ground tile with rail and terrain appropriate ground, NE-SW orientation (provided by railtype)
* <code style="color:darkgreen">GROUNDSPRITE_RAIL_Y <ref name="spritenames" /></code> ground tile with rail and terrain appropriate ground, NW-SE orientation (provided by railtype)

<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.
* For road stops the usage of the ground sprite depends on the [[NML:Roadstops#List of draw mode flags|''draw_mode'' property]].
* For objects the usage of the ground sprite may be skipped depending on the [[NML:Objects#List of object flags|''OBJ_FLAG_DRAW_WATER'' flag]], which has the same effect as ''GROUNDSPRITE_WATER''.

===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. '''Unless you know exactly what you are doing, please follow the recommendations below. They are most likely exactly what you need'''. 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. Default value is 0.
** <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. Default value is 0.
** <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. Default value is 0.
** <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. Default value is 16.
** <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. Default value is 16.
** <code style="color:darkgreen">zextent</code>: Size of the bounding box, in the Z-direction. Must be a compile-time constant. Unit is pixels. Default value is 16.
* <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.

===Strong recommendations for bounding boxes===

For industries, houses, objects, and non-track station tiles:
* Use at most one building sprite; and child sprites for everything else.
** Do not set ''xoffset'', ''yoffset'' or ''zoffset''. The default value 0 applies.
** Do not set ''xextent'' or ''yextent''. The default value 16 applies.
** Set ''zextent'' to "<number of occupied height levels> * 8 - 2". The number of occupied height levels is important for objects allowed under bridges. Otherwise this only needs to be a rough estimate.
* If no sprite visually extends over the ground sprite, you do not need any building sprite: Child sprites can be used for further sprites.

For rail station track tiles:
* Use child sprites of the ground sprite for things "below the train".
* Use exactly two building sprites, possibly with child sprites.
* The first building sprite is used for things "behind the train".
** Set ''xoffset'', ''yoffset'', ''zoffset'' to 0.
** For track in X direction: Set ''xextent'' to 16, ''yextent'' to 5.
** For track in Y direction: Set ''xextent'' to 5, ''yextent'' to 16.
** Set ''zextent'' to "<number of occupied height levels> * 8 - 2". A rough estimate is good enough.
* The second building sprite is used for things "in-front or above the train".
** For track in X direction: Set ''xoffset'' to 0, ''yoffset'' to 11.
** For track in Y direction: Set ''xoffset'' to 11, ''yoffset'' to 0.
** Set ''zoffset'' to 0.
** For track in X direction: Set ''xextent'' to 16, ''yextent'' to 5.
** For track in Y direction: Set ''xextent'' to 5, ''yextent'' to 16.
** Set ''zextent'' to "<number of occupied height levels> * 8 - 2". A rough estimate is good enough.

===Maximum sprite size===

Ground sprites and their child sprites must not extend over the edges of a regular ground sprite of the slope.

Building sprites and their child sprites:
* must not extend below the south tile edges,
* must not extend left/right of the west/east tile corners,
* must not extend above the north corner by more than 200 pixels including the (default) foundation. If foundations are present, this is reduced by up to 16 pixels (steep slope N) to 184 pixels.

The following image shows the limitations for flat tiles, and the extreme cases of steep slopes:

[[File:Max_tile_sprite_size.png]]

These values apply since {{ottd|1.5}}.

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

2025-04-04T13:38:50Z

Frosch: /* Maximum sprite size */

NML:Spritelayout

2025-04-04T13:07:51Z

Frosch: expand on the maximum sprite size

{{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, automatically choosen from sea, river and canal sprites, including river and canal borders.
* <code style="color:darkgreen">GROUNDSPRITE_CLEARED <ref name="spritenames" /></code> ground tile that has just been bulldozed (with brown colour)
* <code style="color:darkgreen">GROUNDSPRITE_RAIL_X <ref name="spritenames" /></code> ground tile with rail and terrain appropriate ground, NE-SW orientation (provided by railtype)
* <code style="color:darkgreen">GROUNDSPRITE_RAIL_Y <ref name="spritenames" /></code> ground tile with rail and terrain appropriate ground, NW-SE orientation (provided by railtype)

<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.
* For road stops the usage of the ground sprite depends on the [[NML:Roadstops#List of draw mode flags|''draw_mode'' property]].
* For objects the usage of the ground sprite may be skipped depending on the [[NML:Objects#List of object flags|''OBJ_FLAG_DRAW_WATER'' flag]], which has the same effect as ''GROUNDSPRITE_WATER''.

===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. '''Unless you know exactly what you are doing, please follow the recommendations below. They are most likely exactly what you need'''. 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. Default value is 0.
** <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. Default value is 0.
** <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. Default value is 0.
** <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. Default value is 16.
** <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. Default value is 16.
** <code style="color:darkgreen">zextent</code>: Size of the bounding box, in the Z-direction. Must be a compile-time constant. Unit is pixels. Default value is 16.
* <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.

===Strong recommendations for bounding boxes===

For industries, houses, objects, and non-track station tiles:
* Use at most one building sprite; and child sprites for everything else.
** Do not set ''xoffset'', ''yoffset'' or ''zoffset''. The default value 0 applies.
** Do not set ''xextent'' or ''yextent''. The default value 16 applies.
** Set ''zextent'' to "<number of occupied height levels> * 8 - 2". The number of occupied height levels is important for objects allowed under bridges. Otherwise this only needs to be a rough estimate.
* If no sprite visually extends over the ground sprite, you do not need any building sprite: Child sprites can be used for further sprites.

For rail station track tiles:
* Use child sprites of the ground sprite for things "below the train".
* Use exactly two building sprites, possibly with child sprites.
* The first building sprite is used for things "behind the train".
** Set ''xoffset'', ''yoffset'', ''zoffset'' to 0.
** For track in X direction: Set ''xextent'' to 16, ''yextent'' to 5.
** For track in Y direction: Set ''xextent'' to 5, ''yextent'' to 16.
** Set ''zextent'' to "<number of occupied height levels> * 8 - 2". A rough estimate is good enough.
* The second building sprite is used for things "in-front or above the train".
** For track in X direction: Set ''xoffset'' to 0, ''yoffset'' to 11.
** For track in Y direction: Set ''xoffset'' to 11, ''yoffset'' to 0.
** Set ''zoffset'' to 0.
** For track in X direction: Set ''xextent'' to 16, ''yextent'' to 5.
** For track in Y direction: Set ''xextent'' to 5, ''yextent'' to 16.
** Set ''zextent'' to "<number of occupied height levels> * 8 - 2". A rough estimate is good enough.

===Maximum sprite size===

Ground sprites and their child sprites must not extend over the edges of a regular ground sprite of the slope.

Building sprites and their child sprites:
* must not extend below the south tile edges,
* must not extend left/right of the west/east tile corners,
* must not extend above the north corner by more than 200 pixels including the (default) foundation. If foundations are present, this is reduced by up to 16 pixels (steep slope S) to 184 pixels.

The following image shows the limitations for flat tiles, and the extreme cases of steep slopes:

[[File:Max_tile_sprite_size.png]]

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

File:Max tile sprite size.png

2025-04-04T13:00:14Z

Frosch: Maximum visible size of sprites on tiles. Applies since OpenTTD 1.5.

== Summary ==
Maximum visible size of sprites on tiles.
Applies since OpenTTD 1.5.