Difference between revisions of "Callbacks"

From GRFSpecs
Jump to navigationJump to search
m (16 revisions)
(convert formatting)
Line 1: Line 1:
  +
==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 [[CallbacksTut|callback tutorial]] on how to use them.
'''''List of available callbacks'''''
 
 
=Callbacks=
 
 
{maketoc}
 
 
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 [[CallbacksTut|callback tutorial]] on how to use them.
 
   
 
In the final action 2 of a chain of variational action 2s, the second byte of the matching entry has to have bit 7 set to identify it as a callback result. (Previously, it was required that the second byte be FF, but now only bit 7 needs to be set.)
 
In the final action 2 of a chain of variational action 2s, the second byte of the matching entry has to have bit 7 set to identify it as a callback result. (Previously, it was required that the second byte be FF, but now only bit 7 needs to be set.)
Line 20: Line 15:
 
'''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.
 
'''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
 
  +
!Number!!Feature(s)!!Meaning
 
  +
|-
10|Vehicles|Visual effect and wagon power
 
  +
|10||Vehicles||Visual effect and wagon power
 
  +
|-
11|Vehicles|Wagon length
 
  +
|11||Vehicles||Wagon length
 
  +
|-
12|Vehicles|Load amount
 
  +
|12||Vehicles||Load amount
 
  +
|-
13|Stations|Station availability
 
  +
|13||Stations||Station availability
 
  +
|-
14|Stations|Use callback to select sprite layout
 
  +
|14||Stations||Use callback to select sprite layout
 
  +
|-
15|Vehicles|Set refitted capacity
 
  +
|15||Vehicles||Set refitted capacity
 
  +
|-
16|Trains|Build articulated engines
 
  +
|16||Trains||Build articulated engines
 
  +
|-
17|Houses|House construction check
 
  +
|17||Houses||House construction check
 
  +
|-
18|Several (G*)|AI construction/purchase selection
 
  +
|18||Several (G*)||AI construction/purchase selection
 
  +
|-
19|Vehicles|Cargo sub-type display
 
  +
|19||Vehicles||Cargo sub-type display
 
  +
|-
1A|Houses|Next animation frame
 
  +
|1A||Houses||Next animation frame
 
  +
|-
1B|Houses|Animation control
 
  +
|1B||Houses||Animation control
 
  +
|-
1C|Houses|Construction stage changes
 
  +
|1C||Houses||Construction stage changes
 
  +
|-
1D|Trains|Can wagon be attached
 
  +
|1D||Trains||Can wagon be attached
 
  +
|-
1E|Houses|Decide colour of building
 
  +
|1E||Houses||Decide colour of building
 
  +
|-
1F|Houses|Cargo acceptance
 
  +
|1F||Houses||Cargo acceptance
 
  +
|-
20|Houses|Length of animation frame
 
  +
|20||Houses||Length of animation frame
 
  +
|-
21|Houses|Trigger building destruction
 
  +
|21||Houses||Trigger building destruction
 
  +
|-
22|Industries|Availability
 
  +
|22||Industries||Availability
 
  +
|-
23|Vehicles|Additional text in purchase screen
 
  +
|23||Vehicles||Additional text in purchase screen
 
  +
|-
24|Stations|Custom station layout
 
  +
|24||Stations||Custom station layout
 
  +
|-
25|Industry tiles|Animation control
 
  +
|25||Industry tiles||Animation control
 
  +
|-
26|Industry tiles|Next animation frame
 
  +
|26||Industry tiles||Next animation frame
 
  +
|-
27|Industry tiles|Length of animation frame
 
  +
|27||Industry tiles||Length of animation frame
 
  +
|-
28|Industries|Industry location permissibility
 
  +
|28||Industries||Industry location permissibility
 
  +
|-
29|Industries|Random production change
 
  +
|29||Industries||Random production change
 
  +
|-
2A|Houses|Get accepted cargo types
 
  +
|2A||Houses||Get accepted cargo types
 
  +
|-
2B|Industry tiles|Decide cargo acceptance
 
  +
|2B||Industry tiles||Decide cargo acceptance
 
  +
|-
2C|Industry tiles|Get accepted cargo types
 
  +
|2C||Industry tiles||Get accepted cargo types
 
  +
|-
2D|Vehicles|Select colour mapping for vehicle
 
  +
|2D||Vehicles||Select colour mapping for vehicle
 
  +
|-
2E|Houses|Custom cargo production
 
  +
|2E||Houses||Custom cargo production
 
  +
|-
2F|Industry tiles|Custom shape check
 
  +
|2F||Industry tiles||Custom shape check
 
  +
|-
30|Industry tiles|Decide drawing default foundations
 
  +
|30||Industry tiles||Decide drawing default foundations
 
  +
|-
31|Vehicles|Start/stop check
 
  +
|31||Vehicles||Start/stop check
 
  +
|-
32|Vehicles|32-day callback
 
  +
|32||Vehicles||32-day callback
 
  +
|-
33|Several|Sound effect callback
 
  +
|33||Several||Sound effect callback
 
  +
|-
34|Vehicles (G*)|Autoreplace vehicle selection
 
  +
|34||Vehicles (G*)||Autoreplace vehicle selection
 
  +
|-
35|Industries|Monthly random production change
 
  +
|35||Industries||Monthly random production change
 
  +
|-
36|Vehicles|Change vehicle Properties
 
  +
|36||Vehicles||Change vehicle Properties
 
  +
|-
37|Industries|Cargo sub-type display
 
  +
|37||Industries||Cargo sub-type display
 
  +
|-
38|Industries|Show additional text in fund window
 
  +
|38||Industries||Show additional text in fund window
 
  +
|-
39|Cargoes|Custom profit calculation
 
  +
|39||Cargoes||Custom profit calculation
 
  +
|-
3A|Industries|Show additional text in industry window
 
  +
|3A||Industries||Show additional text in industry window
 
  +
|-
3B|Industries|Control special effects
 
  +
|3B||Industries||Control special effects
 
  +
|-
3C|Industry tiles|Disable autosloping
 
  +
|3C||Industry tiles||Disable autosloping
 
  +
|-
3D|Industries|Opt out of accepting cargo
 
  +
|3D||Industries||Opt out of accepting cargo
 
  +
|-
40..13F| |--Reserved--
 
  +
|40..13F|| ||--Reserved--
 
  +
|-
140|Stations|Animation control
 
  +
|140||Stations||Animation control
 
  +
|-
141|Stations|Next animation frame
 
  +
|141||Stations||Next animation frame
 
  +
|-
142|Stations|Length of animation frame
 
  +
|142||Stations||Length of animation frame
 
  +
|-
143|Houses|Protect building conditionally
 
  +
|143||Houses||Protect building conditionally
 
  +
|-
144|Sounds (G*)|Ambient sound effects
 
  +
|144||Sounds (G*)||Ambient sound effects
 
  +
|-
145|Cargoes|Custom station rating calculation
 
  +
|145||Cargoes||Custom station rating calculation
 
  +
|-
146|New Signals (G*)|New signals sprite drawing|
 
  +
|146||New Signals (G*)||New signals sprite drawing||
 
  +
|-
147|Canals|Add sprite offset
 
  +
|147||Canals||Add sprite offset
 
  +
|-
148|Houses|Watched cargo accepted
 
  +
|148||Houses||Watched cargo accepted
 
  +
|-
149|Stations|Land slope check
 
  +
|149||Stations||Land slope check
 
  +
|-
14A|Industries|Decide industry color
 
  +
|14A||Industries||Decide industry color
 
  +
|-
14B|Industries|Decide input cargo types
 
  +
|14B||Industries||Decide input cargo types
 
  +
|-
14C|Industries|Decide output cargo types
 
  +
|14C||Industries||Decide output cargo types
 
  +
|-
14D|Houses|Customized building name
 
  +
|14D||Houses||Customized building name
 
  +
|-
14E|Houses|Decide drawing default foundations
 
  +
|14E||Houses||Decide drawing default foundations
 
  +
|-
14F|Houses|Disable autosloping
 
  +
|14F||Houses||Disable autosloping
 
  +
|-
150|Airport tiles|Decide drawing default foundations
 
  +
|150||Airport tiles||Decide drawing default foundations
 
  +
|-
152|Airport tiles|Animation control (OpenTTD > r19197)
 
  +
|152||Airport tiles||Animation control (OpenTTD > r19197)
 
  +
|-
153|Airport tiles|Next Animation frame (OpenTTD > r19197)
 
  +
|153||Airport tiles||Next Animation frame (OpenTTD > r19197)
 
  +
|-
154|Airport tiles|Length of animation frame (OpenTTD > r19197)
 
  +
|154||Airport tiles||Length of animation frame (OpenTTD > r19197)
 
  +
|-
155|Airports|Extra information about airport layout in the build gui (OpenTTD > r20372)
 
  +
|155||Airports||Extra information about airport layout in the build gui (OpenTTD > r20372)
 
  +
|-
156|Airports|Airport layout name (OpenTTD > r20373)
 
  +
|156||Airports||Airport layout name (OpenTTD > r20373)
 
  +
|-
157|Objects|Land slope check
 
  +
|157||Objects||Land slope check
 
  +
|-
158|Objects|Next animation frame
 
  +
|158||Objects||Next animation frame
 
  +
|-
159|Objects|Animation control
 
  +
|159||Objects||Animation control
 
  +
|-
15A|Objects|Length of animation frame
 
  +
|15A||Objects||Length of animation frame
 
  +
|-
15B|Objects|Decide colour of building
 
  +
|15B||Objects||Decide colour of building
 
  +
|-
15C|Objects|Show additional text in building window
 
  +
|15C||Objects||Show additional text in building window
 
  +
|-
15D|Objects|Disable autosloping||
 
  +
|15D||Objects||Disable autosloping
 
  +
|}
<nowiki><nowiki>*</nowiki></nowiki> Generic callbacks are called for the feature, not any specific vehicle ID. Read the [[Action3#n%2Did|Action 3]] entry on how to define these.
 
  +
(*) Generic callbacks are called for the feature, not any specific vehicle ID. Read the [[Action3#n%2Did|Action 3]] entry on how to define these.
   
 
==Visual effect and wagon power (10)==
 
==Visual effect and wagon power (10)==
Line 226: Line 222:
 
Vehicle variable B9 (for a variational action 2) will be set to the new, climate-specific cargo type (column 3, type B in the [[CargoTypes|cargo type list]]), or to FF when only checking whether the vehicle is refittable.
 
Vehicle variable B9 (for a variational action 2) will be set to the new, climate-specific cargo type (column 3, type B in the [[CargoTypes|cargo type list]]), or to FF when only checking whether the vehicle is refittable.
   
Unlike regular refitted capacities (including those from callback 36), the return value is not subject to the usual division of capacities for cargoes other than passengers on trains and planes, instead the capacity is used exactly as returned by the callback. See also the summary page about &nbsp;[[VehicleRefitting|vehicle refitting]].
+
Unlike regular refitted capacities (including those from callback 36), the return value is not subject to the usual division of capacities for cargoes other than passengers on trains and planes, instead the capacity is used exactly as returned by the callback. See also the summary page about &nbsp;[[VehicleRefitting||vehicle refitting]].
   
 
==Articulated engine callback (16)==
 
==Articulated engine callback (16)==
Line 256: Line 252:
 
Since the vehicle hasn't been bought yet, you cannot use the usual 40+x or 80+x vehicle variables, instead you have the following:
 
Since the vehicle hasn't been bought yet, you cannot use the usual 40+x or 80+x vehicle variables, instead you have the following:
   
  +
{| |-
||Variable|Size|Content
 
  +
!Variable!!Size!!Content
 
  +
|-
80|B|cargo type (climate specific, column 3, type B in the [[CargoTypes|cargo type list]])
 
  +
|80||B||cargo type (climate specific, column 3, type B in the [[CargoTypes|cargo type list]])
 
  +
|-
81|B|cargo type (climate independent, column 1, type A in the [[CargoTypes|cargo type list]])
 
  +
|81||B||cargo type (climate independent, column 1, type A in the [[CargoTypes|cargo type list]])
 
  +
|-
82|B|default selection
 
  +
|82||B||default selection
 
  +
|-
83|B|source [[IndustryTypes|industry type]]. For new industries the substitute type is returned starting with OpenTTD r20108.
 
  +
|83||B||source [[IndustryTypes|industry type]]. For new industries the substitute type is returned starting with OpenTTD r20108.
 
  +
|-
84|B|destination [[IndustryTypes|industry type]]. For new industries the substitute type is returned starting with OpenTTD r20108.
 
  +
|84||B||destination [[IndustryTypes|industry type]]. For new industries the substitute type is returned starting with OpenTTD r20108.
 
  +
|-
85|B|distance between source and destination, in (dx+dy)/2
 
  +
|85||B||distance between source and destination, in (dx+dy)/2
 
  +
|-
86|B|AI construction event
 
  +
|86||B||AI construction event
 
  +
|-
87|B|Construction number; for wagons: number of wagon; for stations 0=source station, 1=destination station
 
  +
|87||B||Construction number; for wagons: number of wagon; for stations 0=source station, 1=destination station
 
  +
|-
88|B|Station size in form NL; N=number of platforms, L=length
 
  +
|88||B||Station size in form NL; N=number of platforms, L=length
 
  +
|-
40|D|xxxxxxTT, TT=cargo slot from cargo translation table or same as var.81 if no table, available since r1167/2.5b9||
 
  +
|40||D||xxxxxxTT, TT=cargo slot from cargo translation table or same as var.81 if no table, available since r1167/2.5b9
  +
|}
   
 
The callback will be called for following construction events, stored in variable 86:
 
The callback will be called for following construction events, stored in variable 86:
   
  +
{| |-
||Group|Feature|Var.86|Type|Description
 
  +
!Group!!Feature!!Var.86!!Type!!Description
 
  +
|-
Trains|00|00|Check|Regular rail engine
 
  +
|Trains||00||00||Check||Regular rail engine
 
  +
|-
| |01|Check|Electric rail engine
 
  +
||| ||01||Check||Electric rail engine
 
  +
|-
| |02|Check|Monorail engine
 
  +
||| ||02||Check||Monorail engine
 
  +
|-
| |03|Check|Maglev engine
 
  +
||| ||03||Check||Maglev engine
 
  +
|-
| |08|Get|Regular rail wagon
 
  +
||| ||08||Get||Regular rail wagon
 
  +
|-
| |09|Get|Electric rail wagon
 
  +
||| ||09||Get||Electric rail wagon
 
  +
|-
| |0A|Get|Monorail wagon
 
  +
||| ||0A||Get||Monorail wagon
 
  +
|-
| |0B|Get|Maglev wagon
 
  +
||| ||0B||Get||Maglev wagon
 
  +
|-
| |0F|Get|Track type to build
 
  +
||| ||0F||Get||Track type to build
 
  +
|-
Road Vehicles|01|00|Check|Road vehicle
 
  +
|Road Vehicles||01||00||Check||Road vehicle
 
  +
|-
| |01|Get|First road vehicle ID to try
 
  +
||| ||01||Get||First road vehicle ID to try
 
  +
|-
| |02|Get|Number of road vehicles to try
 
  +
||| ||02||Get||Number of road vehicles to try
 
  +
|-
Ships|02|00|Check|Ship
 
  +
|Ships||02||00||Check||Ship
 
  +
|-
| |01|Get|First ship ID to try
 
  +
||| ||01||Get||First ship ID to try
 
  +
|-
| |02|Get|Number of ships to try
 
  +
||| ||02||Get||Number of ships to try
 
  +
|-
Aircraft|03|00|Check|Aircraft
 
  +
|Aircraft||03||00||Check||Aircraft
 
  +
|-
Stations|04|00|Get|Station ID||
 
  +
|Stations||04||00||Get||Station ID
  +
|}
   
 
Notes:
 
Notes:
*&quot;Check&quot; means to check if it should try to buy this vehicle (with ID in var.82). Return 00 to disallow purchase, or a non-zero value to allow it. If allowed, the computer will buy the highest-cost (or AI rank for train engines) vehicle it can find that is available and has high enough reliability.
+
*"Check" means to check if it should try to buy this vehicle (with ID in var.82). Return 00 to disallow purchase, or a non-zero value to allow it. If allowed, the computer will buy the highest-cost (or AI rank for train engines) vehicle it can find that is available and has high enough reliability.
*&quot;Get&quot; means to find out which ID (etc.) to use. The default in var.82 is what it will use if the callback fails.
+
*"Get" means to find out which ID (etc.) to use. The default in var.82 is what it will use if the callback fails.
 
*For train engines and aircraft, the AI always checks all available engines.
 
*For train engines and aircraft, the AI always checks all available engines.
 
*For road vehicles and ships, the AI has a built-in list of vehicles to try, you can use callback event 01 and 02 to change that list.
 
*For road vehicles and ships, the AI has a built-in list of vehicles to try, you can use callback event 01 and 02 to change that list.
 
*For trains, the track types (0=regular, 1=electric, 2=monorail, 3=maglev) are automatically mapped as appropriate depending on the electrifiedrailways/unifiedmaglev switches. For best results, assume that all four are available. The game will then use the correct one if it is not available.
 
*For trains, the track types (0=regular, 1=electric, 2=monorail, 3=maglev) are automatically mapped as appropriate depending on the electrifiedrailways/unifiedmaglev switches. For best results, assume that all four are available. The game will then use the correct one if it is not available.
   
This callback is &quot;chained&quot;, i.e. if a result is not a callback result (high bit is not set), then the request is passed on to the previous generic callback handler, i.e. they are checked in reverse order. This makes it possible to leave certain decisions to the previous handler and allows some cooperation between several .grf files.
+
This callback is "chained", i.e. if a result is not a callback result (high bit is not set), then the request is passed on to the previous generic callback handler, i.e. they are checked in reverse order. This makes it possible to leave certain decisions to the previous handler and allows some cooperation between several .grf files.
   
 
==Cargo Subtype Display (19)==
 
==Cargo Subtype Display (19)==
Line 337: Line 337:
 
Called in every animation frame, this callback returns the number of the next frame to display. Additionally, it can return these special values:
 
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
 
  +
!Value!!Meaning
 
  +
|-
FF|stop animation. The current frame stays on screen until the animation is restarted.
 
  +
|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.||
 
  +
|FE||continue with next frame as usual. You can return this for stages where you don't want to do anything special.
  +
|}
   
 
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, or bit 2 of property 13 for stations.
 
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, or bit 2 of property 13 for stations.
Line 351: Line 353:
 
Called periodically, in a time interval specified in property 16 (houses) or when an animation trigger happens (industry tiles and stations). Returns the number of the frame the animation should jump to, or one of the following special values:
 
Called periodically, in a time interval specified in property 16 (houses) or when an animation trigger happens (industry tiles and stations). Returns the number of the frame the animation should jump to, or one of the following special values:
   
  +
{| |-
||Value|Meaning
 
  +
!Value!!Meaning
 
  +
|-
FF|stop animation in its current frame
 
  +
|FF||stop animation in its current frame
 
  +
|-
FE|start animation with its current frame
 
  +
|FE||start animation with its current frame
 
  +
|-
FD|leave the animation in its current state (do nothing)||
 
  +
|FD||leave the animation in its current state (do nothing)
  +
|}
   
 
For multi-tile town buildings, [[Action0Houses#Extra_Flags_19_|property 19/bit 2]] modifies this callback slightly, see details there.
 
For multi-tile town buildings, [[Action0Houses#Extra_Flags_19_|property 19/bit 2]] modifies this callback slightly, see details there.
Line 399: Line 403:
 
Return values:
 
Return values:
   
  +
{| |-
||Return|Meaning
 
  +
!Return!!Meaning
 
  +
|-
xx|Disallow attaching and use the D0xx text ID as second line of an error message,
 
  +
|xx||Disallow attaching and use the D0xx text ID as second line of an error message,
 
  +
|-
FD|Disallow attaching with the standard message (incompatible rail types)
 
  +
|FD||Disallow attaching with the standard message (incompatible rail types)
 
  +
|-
FE|Allow attaching
 
  +
|FE||Allow attaching
 
  +
|-
FF|Allow attaching if the rail types match (default)||
 
  +
|FF||Allow attaching if the rail types match (default)
  +
|}
   
 
It you return FE, you would allow attaching for example a monorail wagon to a regular rail vehicle, so if that's not what you intend, return FF.
 
It you return FE, you would allow attaching for example a monorail wagon to a regular rail vehicle, so if that's not what you intend, return FF.
Line 425: Line 431:
 
Called to decide what the building tile can accept. Uses 15 return bits. The returned word should have the layout of Sgmp, where the letters mean the following:
 
Called to decide what the building tile can accept. Uses 15 return bits. The returned word should have the layout of Sgmp, where the letters mean the following:
   
  +
{| |-
||Symbol|Meaning
 
  +
!Symbol!!Meaning
  +
|-
  +
|S||1 if the building should accept food/fizzy drinks instead of goods
  +
|-
  +
|g||If S is 1, the food acceptance in 1/8 units
  +
|-
  +
|||If S is 0, the goods acceptance in 1/8 units
  +
|-
  +
|m||mail acceptance in 1/8 units
  +
|-
  +
|p||passenger acceptance in 1/8 units
  +
|}
   
  +
So, for example, giving the ID 8426h means "4/8 goods, 2/8 mail, 6/8 passenger", while giving the ID 9205 means "2/8 food, 5/8 passenger".
S|1 if the building should accept food/fizzy drinks instead of goods
 
 
g|If S is 1, the food acceptance in 1/8 units
 
 
|If S is 0, the goods acceptance in 1/8 units
 
 
m|mail acceptance in 1/8 units
 
 
p|passenger acceptance in 1/8 units||
 
 
So, for example, giving the ID 8426h means &quot;4/8 goods, 2/8 mail, 6/8 passenger&quot;, while giving the ID 9205 means &quot;2/8 food, 5/8 passenger&quot;.
 
   
 
If property 1E and/or callback 2A is used, the meaning changes slightly. In this case, p means the acceptance of the first cargo type given, m means the same for the second cargo type, and g is the same for the third cargo type, while S must be zero.
 
If property 1E and/or callback 2A is used, the meaning changes slightly. In this case, p means the acceptance of the first cargo type given, m means the same for the second cargo type, and g is the same for the third cargo type, while S must be zero.
Line 459: Line 467:
 
During this callback, variable 18 (extra callback info 2) can contain the following values:
 
During this callback, variable 18 (extra callback info 2) can contain the following values:
   
  +
{| |-
||Variable 18|Meaning
 
  +
!Variable 18!!Meaning
 
  +
|-
0|TTD is generating a map and needs to know if your type can appear.
 
  +
|0||TTD is generating a map and needs to know if your type can appear.
 
  +
|-
1|TTD decided to build a new random industry during regular gameplay and needs to know if it can choose your type.
 
  +
|1||TTD decided to build a new random industry during regular gameplay and needs to know if it can choose your type.
 
  +
|-
2|The user tries to build/prospect for your industry via the new industry window. TTD needs to know if the player is allowed to do this.||
 
  +
|2||The user tries to build/prospect for your industry via the new industry window. TTD needs to know if the player is allowed to do this.
  +
|}
   
 
==Additional text in purchase screen (23)==
 
==Additional text in purchase screen (23)==
   
This callback is called when TTDPatch displays the vehicle stats of any vehicle in its purchase screen. The return value is the &quot;xx&quot; of a D0xx text ID to be shown below all other stats. The callback is always used when defined, no bit in the action 0 property needs to be set to activate it. As of r1908, text IDs D100..D3FF may also be returned.
+
This callback is called when TTDPatch displays the vehicle stats of any vehicle in its purchase screen. The return value is the "xx" of a D0xx text ID to be shown below all other stats. The callback is always used when defined, no bit in the action 0 property needs to be set to activate it. As of r1908, text IDs D100..D3FF may also be returned.
   
How many lines are available depends on the type of vehicle and its other properties, for instance the presence or absence of a &quot;refittable to&quot; line or powered wagons etc. 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. Lines are wrapped automatically, or may be broken explicitly using the newline character 0D.
   
 
If cargo FF (buy menu sprite) is handled explicitly for a vehicle, then the varaction 2 handling callback 23 must be in the buy menu varaction 2 chain.
 
If cargo FF (buy menu sprite) is handled explicitly for a vehicle, then the varaction 2 handling callback 23 must be in the buy menu varaction 2 chain.
Line 489: Line 499:
 
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:
 
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''']]|Meaning
 
  +
!Variable!![[GRFActionsDetailed!!'''Size''']]!!Meaning
  +
|-
  +
|40+x|| ||Not accessible
  +
|-
  +
|5F|| ||Since OpenTTD r19744: Random bits the industry starts with after construction. Accessible via RandomAction2 as well.
  +
|-
  +
|60+x|| ||Only var. 62 and vars 64..68 can be used
  +
|-
  +
|80||W||Coordinates of the selected position
  +
|-
  +
|86||B||Number of the selected layout, according to property 0A
  +
|-
  +
|87||B||Ground type of the selected spot (see [[VarAction2Canals|canal variable 81]] for details)
  +
|-
  +
|88||B||Town zone of the selected spot (see [[VarAction2Houses#Town_zone_42_|house variable 42]] for details)
  +
|-
  +
|89||B||Distance between the closest town and the selected position.
  +
|-
  +
|8A||B||Height of the lowest corner of the tile (between 00h and 80h, one land height unit equals 8 units)
  +
|-
  +
|8B||W||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||Square of the Euclidean distance between the closest town and the selected position
  +
|-
  +
|8F||D||32 random bits (since r1816 and r11985)
  +
|}
   
  +
Unless explicitly noted, distances are Manhattan distance, not Euclidean distance, ie. -+||x-x0||+||y-y0||+- instead of -+sqrt
40+x| |Not accessible
 
   
5F| |Since OpenTTD r19744: Random bits the industry starts with after construction. Accessible via RandomAction2 as well.
 
   
  +
... LOTS OF STUFF MISSING HERE ...
60+x| |Only var. 62 and vars 64..68 can be used
 
   
80|W|Coordinates of the selected position
 
   
  +
[[Action11|Action 11]]. If the callback returns a failure code (not a callback result), the default TTD sound effect will be played. If the callback returns a sound number that is neither a TTD sound, nor a sound from action 11, nothing will be played.
86|B|Number of the selected layout, according to property 0A
 
   
  +
{| |-
87|B|Ground type of the selected spot (see [[VarAction2Canals|canal variable 81]] for details)
 
  +
!Var. 10!!Event
 
  +
|-
88|B|Town zone of the selected spot (see [[VarAction2Houses#Town_zone_42_|house variable 42]] for details)
 
  +
|1||Start sound, called when leaving a station or depot, take-off sound for planes
 
  +
|-
89|B|Distance between the closest town and the selected position.
 
  +
|2||Tunnel sound, called when vehicle enters tunnel
 
  +
|-
8A|B|Height of the lowest corner of the tile (between 00h and 80h, one land height unit equals 8 units)
 
  +
|3||Breakdown sound, called when vehicle breaks down (not for planes)
 
  +
|-
8B|W|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)
 
  +
|4||Running sound, called once per engine tick, but no more than once per vehicle motion
 
  +
|-
8D|W|Square of the Euclidean distance between the closest town and the selected position
 
  +
|5||Touchdown sound, for planes only (obviously)
 
  +
|-
8F|D|32 random bits (since r1816 and r11985)||
 
  +
|6||Train visual effect generation (steam plume, diesel smoke, electric spark)
 
  +
|-
Unless explicitly noted, distances are Manhattan distance, not Euclidean distance, ie. -+|x-x0|+|y-y0|+- instead of -+<nowiki><nowiki>sqrt[[Action11|Action 11]]. If the callback returns a failure code (not a callback result), the default TTD sound effect will be played. If the callback returns a sound number that is neither a TTD sound, nor a sound from action 11, nothing will be played.
 
  +
|7||Running sound, called every 16 engine ticks if in motion
 
  +
|-
||Var. 10|Event
 
  +
|8||Stopped sound, called every 16 engine ticks if stopped (e.g. at signal/in station)
 
  +
|-
1|Start sound, called when leaving a station or depot, take-off sound for planes
 
  +
|9||Load/unload sound, called when consist loads or unloads cargo
 
  +
|-
2|Tunnel sound, called when vehicle enters tunnel
 
  +
|10||Bridge sound, called as generic feature 06 callback every time a consist moves on a bridge. Variables 40+x, 60+x and 80+x refer to the vehicle and bits 0..7 of variable 18 hold the bridge type
 
  +
|}
3|Breakdown sound, called when vehicle breaks down (not for planes)
 
 
4|Running sound, called once per engine tick, but no more than once per vehicle motion
 
 
5|Touchdown sound, for planes only (obviously)
 
 
6|Train visual effect generation (steam plume, diesel smoke, electric spark)
 
 
7|Running sound, called every 16 engine ticks if in motion
 
 
8|Stopped sound, called every 16 engine ticks if stopped (e.g. at signal/in station)
 
 
9|Load/unload sound, called when consist loads or unloads cargo
 
 
10|Bridge sound, called as generic feature 06 callback every time a consist moves on a bridge. Variables 40+x, 60+x and 80+x refer to the vehicle and bits 0..7 of variable 18 hold the bridge type||
 
   
 
For the running sounds, it is advisable to check the [[VarAction2Vehicles#Motion_counter_46_|motion counter]] and to only return a successful sound effect number every so many vehicle motion ticks. This way, the sounds will be played more frequently the faster the train is. Alternatively, you can check the tick counter variable and play the sound effect every so many engine ticks, so that it is played at a constant rate, or, of course, switch between both modes depending on vehicle speed.
 
For the running sounds, it is advisable to check the [[VarAction2Vehicles#Motion_counter_46_|motion counter]] and to only return a successful sound effect number every so many vehicle motion ticks. This way, the sounds will be played more frequently the faster the train is. Alternatively, you can check the tick counter variable and play the sound effect every so many engine ticks, so that it is played at a constant rate, or, of course, switch between both modes depending on vehicle speed.
Line 553: Line 573:
 
If the callback fails, i.e. if no suitable ID could be found by any of the callbacks in the generic chain, the vehicle is not upgraded, and is simply renewed instead. &nbsp;If an ID is available but the player lacks the cash to upgrade, the patch waits for the cash to become available instead of either picking a worse engine or renewing the vehicle.
 
If the callback fails, i.e. if no suitable ID could be found by any of the callbacks in the generic chain, the vehicle is not upgraded, and is simply renewed instead. &nbsp;If an ID is available but the player lacks the cash to upgrade, the patch waits for the cash to become available instead of either picking a worse engine or renewing the vehicle.
   
For trains, each engine head will be replaced by one vehicle of the new type. &nbsp;As such, it is advisable for only return &quot;compatible&quot; IDs for trains that require a particular construction or arrangement of engine heads.
+
For trains, each engine head will be replaced by one vehicle of the new type. &nbsp;As such, it is advisable for only return "compatible" IDs for trains that require a particular construction or arrangement of engine heads.
   
 
The callback is always used when defined, no bit in the action 0 property needs to be set to activate it.
 
The callback is always used when defined, no bit in the action 0 property needs to be set to activate it.
Line 567: Line 587:
 
The following properties are supported:
 
The following properties are supported:
   
  +
{| |-
||Feature|Property|Minimum version|OpenTTD rev|
 
  +
!Feature!!Property!!Minimum version!!OpenTTD rev!!
 
  +
|-
Trains (00)|''07 (Load amount)''| - | - |''Changeable via [[Callbacks#Load_amount_callback_12_|callback 12]]''
 
  +
|Trains (00)||''07 (Load amount)''|| - || - ||''Changeable via [[Callbacks#Load_amount_callback_12_|callback 12]]''
 
  +
|-
|09 (Speed)|2.5 beta 6|r9671|
 
  +
|||09 (Speed)||2.5 beta 6||r9671||
 
  +
|-
|0B (Power)|2.5 beta 6|r9671|
 
  +
|||0B (Power)||2.5 beta 6||r9671||
 
  +
|-
|0D (Running cost factor)|2.6 rev 1420|r9671|
 
  +
|||0D (Running cost factor)||2.6 rev 1420||r9671||
 
  +
|-
|14 (Cargo capacity)|2.6 rev 1966|r9828|See also [[Callbacks#Refitted_capacity_callback_15_|callback 15]]
 
  +
|||14 (Cargo capacity)||2.6 rev 1966||r9828||See also [[Callbacks#Refitted_capacity_callback_15_|callback 15]]
 
  +
|-
|16 (Weight)|2.6 rev 1887|r9780|
 
  +
|||16 (Weight)||2.6 rev 1887||r9780||
 
  +
|-
|17 (Cost factor)| |r9806|
 
  +
|||17 (Cost factor)|| ||r9806||
 
  +
|-
|1F (Tractive effort)|2.5 beta 6|r9671|
 
  +
|||1F (Tractive effort)||2.5 beta 6||r9671||
 
  +
|-
|''21 (Short wagons)''| - | - |''Changeable via [[Callbacks#Wagon_length_callback_11_|callback 11]]''
 
  +
|||''21 (Short wagons)''|| - || - ||''Changeable via [[Callbacks#Wagon_length_callback_11_|callback 11]]''
 
  +
|-
|''22 (Visual effect & powered wagons)''| - | - |''Changeable via [[Callbacks#Visual_effect_and_wagon_power_10_|callback 10]]''
 
  +
|||''22 (Visual effect & powered wagons)''|| - || - ||''Changeable via [[Callbacks#Visual_effect_and_wagon_power_10_|callback 10]]''
 
  +
|-
|25 (User data)|2.5 beta 6|r11431|
 
  +
|||25 (User data)||2.5 beta 6||r11431||
 
  +
|-
Road Vehicles (01)|''07 (Load amount)''| - | - |''Changeable via [[Callbacks#Load_amount_callback_12_|callback 12]]''
 
  +
|Road Vehicles (01)||''07 (Load amount)''|| - || - ||''Changeable via [[Callbacks#Load_amount_callback_12_|callback 12]]''
 
  +
|-
|09 (Running cost factor)| |r18011|
 
  +
|||09 (Running cost factor)|| ||r18011||
 
  +
|-
|0F (Cargo capacity)| |r9828|See also [[Callbacks#Refitted_capacity_callback_15_|callback 15]]
 
  +
|||0F (Cargo capacity)|| ||r9828||See also [[Callbacks#Refitted_capacity_callback_15_|callback 15]]
 
  +
|-
|11 (Cost factor)| |r9806|
 
  +
|||11 (Cost factor)|| ||r9806||
 
  +
|-
|13 (Power)| |r21058|
 
  +
|||13 (Power)|| ||r21058||
 
  +
|-
|14 (Weight)| |r21058|
 
  +
|||14 (Weight)|| ||r21058||
 
  +
|-
|15 (Speed)| |r21100|
 
  +
|||15 (Speed)|| ||r21100||
 
  +
|-
|18 (Tractive effort)| |r21058|
 
  +
|||18 (Tractive effort)|| ||r21058||
 
  +
|-
Ships (02)|''07 (Load amount)''| - | - |''Changeable via [[Callbacks#Load_amount_callback_12_|callback 12]]''
 
  +
|Ships (02)||''07 (Load amount)''|| - || - ||''Changeable via [[Callbacks#Load_amount_callback_12_|callback 12]]''
 
  +
|-
|0A (Cost factor)| 2.6 rev 1990 |r9806|
 
  +
|||0A (Cost factor)|| 2.6 rev 1990 ||r9806||
 
  +
|-
|0B (Speed)|2.5 beta 6|r9671|
 
  +
|||0B (Speed)||2.5 beta 6||r9671||
 
  +
|-
|0D (Cargo capacity)| 2.6 rev 1990 |r9828|See also [[Callbacks#Refitted_capacity_callback_15_|callback 15]]
 
  +
|||0D (Cargo capacity)|| 2.6 rev 1990 ||r9828||See also [[Callbacks#Refitted_capacity_callback_15_|callback 15]]
 
  +
|-
|0F (Running cost factor)| 2.6 rev 1510 |r9808|
 
  +
|||0F (Running cost factor)|| 2.6 rev 1510 ||r9808||
 
  +
|-
Planes (03)|''07 (Load amount)''| - | - |''Changeable via [[Callbacks#Load_amount_callback_12_|callback 12]]''
 
  +
|Planes (03)||''07 (Load amount)''|| - || - ||''Changeable via [[Callbacks#Load_amount_callback_12_|callback 12]]''
 
  +
|-
|0B (Cost factor)| |r9806|
 
  +
|||0B (Cost factor)|| ||r9806||
 
  +
|-
|0C (Speed)|2.5 beta 6|r9671|
 
  +
|||0C (Speed)||2.5 beta 6||r9671||
 
  +
|-
|0E (Running cost factor)|2.6 r1507|r9678|
 
  +
|||0E (Running cost factor)||2.6 r1507||r9678||
 
  +
|-
|0F (Passenger capacity)| |r19218|See also [[Callbacks#Refitted_capacity_callback_15_|callback 15]]
 
  +
|||0F (Passenger capacity)|| ||r19218||See also [[Callbacks#Refitted_capacity_callback_15_|callback 15]]
 
  +
|-
|11 (Mail capacity)| |r19218| ||
 
  +
|||11 (Mail capacity)|| ||r19218||
  +
|}
   
 
Most properties will only change when the vehicle is bought, serviced (enters a depot), visits a station or on loading of a saved game. Other ones such as TE are called every time a TE calculation is run.
 
Most properties will only change when the vehicle is bought, serviced (enters a depot), visits a station or on loading of a saved game. Other ones such as TE are called every time a TE calculation is run.
Line 643: Line 665:
 
During the callback, the lowest byte of var. 18 can have the following values:
 
During the callback, the lowest byte of var. 18 can have the following values:
   
  +
{| |-
||Number|Meaning
 
  +
!Number!!Meaning
 
  +
|-
00|Return subtext for first accepted cargo type
 
  +
|00||Return subtext for first accepted cargo type
 
  +
|-
01|Return subtext for second accepted cargo type
 
  +
|01||Return subtext for second accepted cargo type
 
  +
|-
02|Return subtext for third accepted cargo type
 
  +
|02||Return subtext for third accepted cargo type
 
  +
|-
03|Return subtext for first produced cargo type
 
  +
|03||Return subtext for first produced cargo type
 
  +
|-
04|Return subtext for second produced cargo type||
 
  +
|04||Return subtext for second produced cargo type
  +
|}
   
 
Bits 8..15 of var. 18 can have the following values:
 
Bits 8..15 of var. 18 can have the following values:
   
  +
{| |-
||Number|Meaning
 
  +
!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
 
  +
|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.
 
  +
|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.
 
  +
|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||
 
  +
|other values||Reserved for future use
  +
|}
   
 
Other bits of var. 18 are reserved for future use.
 
Other bits of var. 18 are reserved for future use.
Line 676: Line 702:
   
 
Since OpenTTD r20086 and TTDPatch r2354, the contents of registers 100h..105h are copied onto the text reference stack.
 
Since OpenTTD r20086 and TTDPatch r2354, the contents of registers 100h..105h are copied onto the text reference stack.
 
{cookie}
 
   
 
==Custom profit calculation for cargoes (39)==
 
==Custom profit calculation for cargoes (39)==
Line 717: Line 741:
 
For multi-tile buildings, the callback will be called for the type of the tile the player wants to destroy. Therefore, to get consistent behaviour, you must enable this callback for every tile and respond it the same way no matter which tile it is called for.
 
For multi-tile buildings, the callback will be called for the type of the tile the player wants to destroy. Therefore, to get consistent behaviour, you must enable this callback for every tile and respond it the same way no matter which tile it is called for.
   
Since TTDPatch 2.6 r1705, you can use this callback to prevent building &quot;town&quot; industries (banks, water towers, etc.) over your house. The lowest byte of variable 10 is zero for &quot;normal&quot; demolition and one when TTD wants to remove the house for the sake of a new industry. Other values of variable 10 are reserved for future use.
+
Since TTDPatch 2.6 r1705, you can use this callback to prevent building "town" industries (banks, water towers, etc.) over your house. The lowest byte of variable 10 is zero for "normal" demolition and one when TTD wants to remove the house for the sake of a new industry. Other values of variable 10 are reserved for future use.
   
 
==Ambient sound effects (144)==
 
==Ambient sound effects (144)==
Line 727: Line 751:
 
To decide whether to play a sound, and what sound to play, Var.Action 2 variable 10 holds the following information: THRRxxxt
 
To decide whether to play a sound, and what sound to play, Var.Action 2 variable 10 holds the following information: THRRxxxt
   
  +
{| |-
||Field|Meaning
 
  +
!Field!!Meaning
 
  +
|-
T|Tile class, 0=bare land, 4=trees, 6=water
 
  +
|T||Tile class, 0=bare land, 4=trees, 6=water
 
  +
|-
H|Height of north corner of tile
 
  +
|H||Height of north corner of tile
 
  +
|-
RR|8 random bits
 
  +
|RR||8 random bits
 
  +
|-
xxx|Reserved
 
  +
|xxx||Reserved
 
  +
|-
t|Terrain type; &nbsp;0 normal (grass), 1 desert, 2 rainforest, 4 on or above snowline||
 
  +
|t||Terrain type; &nbsp;0 normal (grass), 1 desert, 2 rainforest, 4 on or above snowline
 
  +
|}
This callback must be enabled by bit 4 in [[ActionD#Misc_GRF_Features_9E_|action D var 9E]].
 
  +
|-
  +
|This callback must be enabled by bit 4 in [[ActionD#Misc_GRF_Features_9E_|action D var 9E]].
   
 
==Custom station rating calculation (145)==
 
==Custom station rating calculation (145)==
Line 748: Line 774:
 
* Time since the cargo was last picked up:
 
* Time since the cargo was last picked up:
   
  +
{| |-
||Time units (days)|Score (%, rounded)
 
  +
!Time units (days)!!Score (%, rounded)
 
  +
|-
&gt;21 (&gt;52.5 days)|0 (0%)
 
  +
|&gt;21 (&gt;52.5 days)||0 (0%)
 
  +
|-
13..21 (32.5 days..52.5 days)|25 (10%)
 
  +
|13..21 (32.5 days..52.5 days)||25 (10%)
 
  +
|-
7..12 (17.5 days..32.5 days)|50 (20%)
 
  +
|7..12 (17.5 days..32.5 days)||50 (20%)
 
  +
|-
4..6 (10 days..17.5 days)|95 (37%)
 
  +
|4..6 (10 days..17.5 days)||95 (37%)
 
  +
|-
0..3 (0 days..10 days)|130 (51%)||
 
  +
|0..3 (0 days..10 days)||130 (51%)
  +
|}
   
 
The time unit used equals 185 engine ticks, or 2.5 TTD days. For ships, the time units are divided by 4 before calculating this component, so ships have four times more time before the ratings start dropping.
 
The time unit used equals 185 engine ticks, or 2.5 TTD days. For ships, the time units are divided by 4 before calculating this component, so ships have four times more time before the ratings start dropping.
 
* Amount of cargo waiting:
 
* Amount of cargo waiting:
   
  +
{| |-
||Amount of cargo|Score (%, rounded)
 
  +
!Amount of cargo!!Score (%, rounded)
 
  +
|-
&gt;1500|-90 (-35%)
 
  +
|&gt;1500||-90 (-35%)
 
  +
|-
1001..1500|-35 (-14%)
 
  +
|1001..1500||-35 (-14%)
 
  +
|-
601..1000|0 (0%)
 
  +
|601..1000||0 (0%)
 
  +
|-
301..600|10 (4%)
 
  +
|301..600||10 (4%)
 
  +
|-
101..300|30 (12%)
 
  +
|101..300||30 (12%)
 
  +
|-
0..100|40 (16%)||
 
  +
|0..100||40 (16%)
  +
|}
 
* Max. speed of the last vehicle picking up the cargo:
 
* Max. speed of the last vehicle picking up the cargo:
   
This calculation is somewhat complicated. The maximum speed of the vehicle is expressed in &quot;speed units&quot;. For trains and road vehicles, the speed unit is 1 km/h; for ships, it's 0.5 km/h; for aircraft, it's 8 mph. If the max. speed is above 255 speed units, 255 is used instead. If the vehicle is slower than 85 units, no points are awarded; otherwise, you get (speed_units-85)/4 points. Therefore, the maximum you can get is 42 points, or 16%.
+
This calculation is somewhat complicated. The maximum speed of the vehicle is expressed in "speed units". For trains and road vehicles, the speed unit is 1 km/h; for ships, it's 0.5 km/h; for aircraft, it's 8 mph. If the max. speed is above 255 speed units, 255 is used instead. If the vehicle is slower than 85 units, no points are awarded; otherwise, you get (speed_units-85)/4 points. Therefore, the maximum you can get is 42 points, or 16%.
 
* Age of the last carrier picking up the cargo:
 
* Age of the last carrier picking up the cargo:
   
 
The original calculation goes like this:
 
The original calculation goes like this:
   
  +
{| |-
||Age of vehicle (years)|Score (%, rounded)
 
  +
!Age of vehicle (years)!!Score (%, rounded)
 
  +
|-
2|10 (4%)
 
  +
|2||10 (4%)
 
  +
|-
1|20 (8%)
 
  +
|1||20 (8%)
 
  +
|-
0|33 (13%)||
 
  +
|0||33 (13%)
  +
|}
   
 
If the newagerating switch is turned on, the calculation changes. You get 33 points for vehicles younger than 5 years, and get 0 points for vehicles older than 21 years. Between these two ages, score drops slowly, by 2 points per year.
 
If the newagerating switch is turned on, the calculation changes. You get 33 points for vehicles younger than 5 years, and get 0 points for vehicles older than 21 years. Between these two ages, score drops slowly, by 2 points per year.
 
* Bonus for AI companies
 
* Bonus for AI companies
   
  +
{| |-
||AI intelligence setting|Score (%, rounded)
 
  +
!AI intelligence setting!!Score (%, rounded)
 
  +
|-
Low|0 (0%)
 
  +
|Low||0 (0%)
 
  +
|-
Medium|31 (12%)
 
  +
|Medium||31 (12%)
 
  +
|-
High|63 (25%)||
 
  +
|High||63 (25%)
  +
|}
   
 
That is, AI players cheat to get good ratings for their brain-dead routes.
 
That is, AI players cheat to get good ratings for their brain-dead routes.
Line 807: Line 841:
 
If your company has erected a statue in the nearest town, you get 26 points (10%) bonus to all cargo ratings.
 
If your company has erected a statue in the nearest town, you get 26 points (10%) bonus to all cargo ratings.
   
If a human player does everything perfectly, the maximum rating she can get is 271 points, while the worst possible transport service gets -90 points; for &quot;highly intelligent&quot; AI players, the corresponding values are 334 and -27, respectively. The resulting value gets clamped to the 0..255 range. TTD makes sure the ratings change slowly, but steadily: every 2.5 days, the actual rating moves towards the value calculated above, by no more than 2 points. For example, you 'd need at least 320 days to go from 0% to 100%, even if your service is perfect. When a cargo type first appears at a station, its rating is set to 175 points (69%), so it takes some time until it gets adjusted to the actual parameters of the service.
+
If a human player does everything perfectly, the maximum rating she can get is 271 points, while the worst possible transport service gets -90 points; for "highly intelligent" AI players, the corresponding values are 334 and -27, respectively. The resulting value gets clamped to the 0..255 range. TTD makes sure the ratings change slowly, but steadily: every 2.5 days, the actual rating moves towards the value calculated above, by no more than 2 points. For example, you 'd need at least 320 days to go from 0% to 100%, even if your service is perfect. When a cargo type first appears at a station, its rating is set to 175 points (69%), so it takes some time until it gets adjusted to the actual parameters of the service.
   
 
The callback allows you to replace the first three components (days since last pickup, amount waiting and max. speed of last vehicle) in the calculation above. If your callback succeeds, the first three components are skipped and the returned value is used instead their results. Bit 14 is considered the sign bit, so you can return negative numbers (and need not to worry about calculated callback results yielding a negative result, as long as you stay in the range -16384..16383). During the callback, variable 18 has the value ssaaaatt, where
 
The callback allows you to replace the first three components (days since last pickup, amount waiting and max. speed of last vehicle) in the calculation above. If your callback succeeds, the first three components are skipped and the returned value is used instead their results. Bit 14 is considered the sign bit, so you can return negative numbers (and need not to worry about calculated callback results yielding a negative result, as long as you stay in the range -16384..16383). During the callback, variable 18 has the value ssaaaatt, where
Line 816: Line 850:
 
The lowest byte of variable 10 contains one of the following values:
 
The lowest byte of variable 10 contains one of the following values:
   
  +
{| |-
||value|meaning
 
  +
!value!!meaning
  +
|-
  +
|10h||the last vehicle entering the station was a train
  +
|-
  +
|11h||the last vehicle entering the station was a road vehicle
  +
|-
  +
|12h||the last vehicle entering the station was a ship
  +
|-
  +
|13h||the last vehicle entering the station was an aircraft
  +
|-
  +
|00h||no vehicle entered the station yet, or the last one entering was sold
  +
|}
   
  +
Please note that there's only one "last vehicle" field per station, so the vehicle this refers to may not have picked up any of your cargo. The original TTD calculation doesn't care about this and just uses the field to get the vehicle type used in the first component.
10h|the last vehicle entering the station was a train
 
 
11h|the last vehicle entering the station was a road vehicle
 
 
12h|the last vehicle entering the station was a ship
 
 
13h|the last vehicle entering the station was an aircraft
 
 
00h|no vehicle entered the station yet, or the last one entering was sold||
 
 
Please note that there's only one &quot;last vehicle&quot; field per station, so the vehicle this refers to may not have picked up any of your cargo. The original TTD calculation doesn't care about this and just uses the field to get the vehicle type used in the first component.
 
   
 
Currently, you can only use variables 10 and 18 for your decision, since neither vehicle nor station variables are available for a cargo callback. As soon as the architecture of TTDPatch allows this, the callback will be given access to the station and the last vehicle that entered.
 
Currently, you can only use variables 10 and 18 for your decision, since neither vehicle nor station variables are available for a cargo callback. As soon as the architecture of TTDPatch allows this, the callback will be given access to the station and the last vehicle that entered.
Line 840: Line 876:
 
Add an offset to the default sprite number to be drawn.
 
Add an offset to the default sprite number to be drawn.
   
  +
{| |-
||Feature|Accessible Variables
 
  +
!Feature!!Accessible Variables
 
  +
|-
Canals|80+x variables are accessible by Canals. See [[VarAction2Canals]]||
 
  +
|Canals||80+x variables are accessible by Canals. See [[VarAction2Canals]]
  +
|}
   
 
The default number is accessible in variable 10 (extra callback info 1) to decide if the sprite number needs an offset.
 
The default number is accessible in variable 10 (extra callback info 1) to decide if the sprite number needs an offset.
Line 848: Line 886:
 
==Land slope check (149/157)==
 
==Land slope check (149/157)==
   
This callback is called for each tile where the new station part will be built. It can return zero to accept the current tile or one to make the station building fail with the &quot;Land sloped in wrong direction&quot; error message. Other return values are reserved for future use, don't use them for now.
+
This callback is called for each tile where the new station part will be built. It can return zero to accept the current tile or one to make the station building fail with the "Land sloped in wrong direction" error message. Other return values are reserved for future use, don't use them for now.
   
 
Since the station isn't built yet, no 8x variables can be accessed. Only variables 43 and 67 will work from the 4x and 6x variables. You get the following information, though:
 
Since the station isn't built yet, no 8x variables can be accessed. Only variables 43 and 67 will work from the 4x and 6x variables. You get the following information, though:
 
* variable 18:
 
* variable 18:
   
  +
{| |-
||bit numbers|Meaning
 
  +
!bit numbers!!Meaning
 
  +
|-
0..7|offset of current tile on the platform, 0 is the northmost tile
 
  +
|0..7||offset of current tile on the platform, 0 is the northmost tile
 
  +
|-
8..15|bits 8..15: current platform number, 0 is the northmost platform
 
  +
|8..15||bits 8..15: current platform number, 0 is the northmost platform
 
  +
|-
16..23|total length of station being built
 
  +
|16..23||total length of station being built
 
  +
|-
24..31|total number of platforms being built||
 
  +
|24..31||total number of platforms being built
  +
|}
 
* variable 10:
 
* variable 10:
   
  +
{| |-
||bit numbers|Meaning
 
  +
!bit numbers!!Meaning
 
  +
|-
4..7|Slope info of the current tile:~pp~
 
  +
|4..7||Slope info of the current tile:~pp~
   
 
bit 7 - N corner is elevated
 
bit 7 - N corner is elevated
Line 875: Line 916:
   
 
bit 4 - W corner is elevated~/pp~
 
bit 4 - W corner is elevated~/pp~
  +
|-
 
0..3|the same information, but &quot;mirrored&quot; (bit 0 and 2 swapped) if the station is built in the NW-SE orientation. This allows you to check slopes without checking the orientation explicitly.
+
|0..3||the same information, but "mirrored" (bit 0 and 2 swapped) if the station is built in the NW-SE orientation. This allows you to check slopes without checking the orientation explicitly.
  +
|-
 
other bits|reserved for future use||
+
|other bits||reserved for future use
  +
|}
   
 
The callback is called only after the normal checks TTD does for slopes, so it's not possible
 
The callback is called only after the normal checks TTD does for slopes, so it's not possible
Line 900: Line 942:
 
These callbacks are called when the industry is built, and allow customizing the input and output cargo types dynamically. Both callbacks are called repeatedly, with the lowest byte of variable 10 starting from zero and increasing after every call; you should return a cargo type each time, or FFh to terminate the list. (A failed callback terminates the list, too.) The same limitations apply as for callback 14A: industry tiles aren't yet placed, and some industry variables contain junk. You can use random action2s, however. The interpretation of the returned value depends on two factors: the current GRF version number and the presence of a cargo translation table:
 
These callbacks are called when the industry is built, and allow customizing the input and output cargo types dynamically. Both callbacks are called repeatedly, with the lowest byte of variable 10 starting from zero and increasing after every call; you should return a cargo type each time, or FFh to terminate the list. (A failed callback terminates the list, too.) The same limitations apply as for callback 14A: industry tiles aren't yet placed, and some industry variables contain junk. You can use random action2s, however. The interpretation of the returned value depends on two factors: the current GRF version number and the presence of a cargo translation table:
   
  +
{| |-
||GRF version|Has cargo translation table|Interpretation
 
  +
!GRF version!!Has cargo translation table!!Interpretation
 
  +
|-
6 or below| |Climate-dependent cargo slot number
 
  +
|6 or below|| ||Climate-dependent cargo slot number
 
  +
|-
7 or above|No|Cargo bit
 
  +
|7 or above||No||Cargo bit
 
  +
|-
7 or above|Yes|Index in the translation table||
 
  +
|7 or above||Yes||Index in the translation table
  +
|}
   
 
Although currently callback 14B is called no more than three times, and callback 14C no more than twice, this may change between versions/implementations, to allow more input/output types. To be safe, you should return FFh as the last element even when you use all three input types or both output types.
 
Although currently callback 14B is called no more than three times, and callback 14C no more than twice, this may change between versions/implementations, to allow more input/output types. To be safe, you should return FFh as the last element even when you use all three input types or both output types.
Line 912: Line 956:
 
==House customized building name (14D)==
 
==House customized building name (14D)==
   
This callback is activated from the Tile Description Query tool, when enquiring a house. &nbsp;Variable 10 will be set to 1 if the house is complete, otherwise it will be 0. &nbsp;The return value is the &quot;xx&quot; of a D0xx text ID. &nbsp;If the callback fails, the Query tool will use the house name set in property 12 (Building name ID).
+
This callback is activated from the Tile Description Query tool, when enquiring a house. &nbsp;Variable 10 will be set to 1 if the house is complete, otherwise it will be 0. &nbsp;The return value is the "xx" of a D0xx text ID. &nbsp;If the callback fails, the Query tool will use the house name set in property 12 (Building name ID).
   
 
Since this callback is not performed frequently, you do not need to specify a mask. &nbsp;It will always be performed, and the name will only change when successful.
 
Since this callback is not performed frequently, you do not need to specify a mask. &nbsp;It will always be performed, and the name will only change when successful.

Revision as of 20:11, 14 June 2011

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 callback tutorial on how to use them.

In the final action 2 of a chain of variational action 2s, the second byte of the matching entry has to have bit 7 set to identify it as a callback result. (Previously, it was required that the second byte be FF, but now only bit 7 needs to be set.)

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.  For some callbacks, 15 bit results are possible, in which case 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.

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 2.0.1 alpha 40, you must set the high byte to FF, and so can use only 8 bit results.

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 Visual effect and wagon power
11 Vehicles Wagon length
12 Vehicles Load amount
13 Stations Station availability
14 Stations Use callback to select sprite layout
15 Vehicles Set refitted capacity
16 Trains Build articulated engines
17 Houses House construction check
18 Several (G*) AI construction/purchase selection
19 Vehicles 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 (G*) 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 Animation control
141 Stations Next animation frame
142 Stations Length of animation frame
143 Houses Protect building conditionally
144 Sounds (G*) Ambient sound effects
145 Cargoes Custom station rating calculation
146 New Signals (G*) 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 Decide drawing default foundations
152 Airport tiles Animation control (OpenTTD > r19197)
153 Airport tiles Next Animation frame (OpenTTD > r19197)
154 Airport tiles Length of animation frame (OpenTTD > r19197)
155 Airports Extra information about airport layout in the build gui (OpenTTD > r20372)
156 Airports Airport layout name (OpenTTD > r20373)
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

(*) Generic callbacks are called for the feature, not any specific vehicle ID. Read the Action 3 entry on how to define these.

Visual effect and wagon power (10)

This callback is used to determine the visual effect to use for a vehicle and whether a train wagon is powered (adding power and weight to the train).

The 'powered wagon'-flag only applies for train wagons that would by default be powered (i.e. property 1B is set).

The visual effect applies to all train vehicles (since OpenTTD r21238 for road vehicles and ships as well).

The callback is only called when loading a game, when the train reverses, or when rearranging the train in a depot.

In OpenTTD the 'visual effect' is also updated when the vehicle enters track of a different railtype. The 'powered wagon'-flag may not change in that case.

If the callback fails for any reason (e.g. not defined, action 2 does not return callback result etc.), the value of the corresponding action 0 property ( train property 22, road vehicle property 21, ship property 1C ) is used instead.  For possible return values, refer to these properties as well.

Wagon length callback (11)

This callback is used instead of property 21 whenever the train leaves a depot or is displayed inside a depot. If the callback fails, the value of property 21 is used instead.

Road vehicles do not have a property for this purpose. If the callback fails, a length of 8/8 is used.

The callback result may change only when whole vehicle chain is inside a depot.

Load amount callback (12)

This callback is used instead of property 07 when loading a game or rearranging a train in a depot (or when buying other vehicles). If the callback fails, the value of property 07 is used instead.

Note: For aircraft carrying both passengers and mail this callback is broken (wrt. mail) in TTDP and OTTD before r14672.

Since OTTD r14672 the callback is called for passengers and for mail. The mail compartment behaves like a wagon attached to a train engine. I.e. to read general variables of the aircraft you have to use varaction2 type 82/86/8A (related object), as most variables are not valid for the mail compartment.

Finally to distinguish the passenger and the mail part you can use variable 47 or even 40.

Station availability callback (13)

This sets whether a station can be constructed or not, i.e. whether it can be selected in the station construction window.  A non-zero callback return indicates the station can be built, and a return code of zero removes the station from the selection.

Station sprite layout (14)

Callback 14 selects an entry from the sprite layout (set by prop. 09 or the default if unset), and if its return value is invalid then the sprite layout given from the tile type will be used.  You can use this to have more than 4 different sprite sets to choose from.

Bit 0 (station orientation) of the return value is ignored, and instead set to bit 0 of the actual tile, so that you do not have to check the orientation explicitly and return the two corresponding values, instead just organize the layouts such that even numbers correspond to X orientation (NE-SW) and odd numbers corresponding to Y orientation (NW-SE).

The effect is like having additional tile types that are however not actually built, but only show different graphics depending on this callback.

Refitted capacity callback (15)

This callback is used when a vehicle is refitted, to find the new capacity. It is a 15 bit callback since 2.0.1 alpha 40, and allows return values up to 7EFF=32511 units of cargo.

Vehicle variable B9 (for a variational action 2) will be set to the new, climate-specific cargo type (column 3, type B in the cargo type list), or to FF when only checking whether the vehicle is refittable.

Unlike regular refitted capacities (including those from callback 36), the return value is not subject to the usual division of capacities for cargoes other than passengers on trains and planes, instead the capacity is used exactly as returned by the callback. See also the summary page about  |vehicle refitting.

Articulated engine callback (16)

This allows building articulated engines or wagons, i.e. vehicles made from several individual vehicles.  If this callback is in use, additional vehicles will be added until the callback returns FF.

The callback return is interpreted as the ID of the vehicle to add.  If 80 is added to the ID, the vehicle will be reversed (as if Ctrl was held while bought).

Note that since the train is not yet built, you cannot use train variables in action 2. Instead, use variable 10 (extra callback info 1), which is set to 01 for the first articulated part, 02 for the second and so on.

If more than the first vehicle contains cargo, the callback must work in the buy menu as well. (This is only supported since 2.5 beta 8.)  This means that it will be called with cargo type FF in the action 3. Otherwise, the cargo amount shown in the buy menu will only be for the first part of the articulated vehicle.

In OpenTTD the cargo class of the first road vehicles is used to determine whether the vehicle can stop at bus or truck stops regardless of the capacity of the first vehicle. If the cargo class bit for passengers is set it can go to bus stops when the is not set it can go to truck stops. See also the page about  vehicle refitting.

House construction check (17)

This callback is used to determine if the given building type can be built on a position. It should return a nonzero value to allow building and zero to cancel it.

Since the building is not created yet, you can't use variables 40 and 41 (they return zero). You can use variable 42, 43, 44, 45 and all town variables, though. Since OpenTTD r19744 you can also access the random bits via RandomAction2 or variable 5F.

Property 0A and 13 are checked even if the callback returns a nonzero value; they can cancel building as well.

For multi-tile buildings, this callback is always called for the north tile type, but the position you can access through variables 40, 42 and 43 is not guaranteed to be the final position of the north tile. It is guaranteed, though, that if the building really gets built, one of its tiles will occupy that tile. So, for example, if you return zero for desert tiles, this neither means that your building won't occupy any desert tiles, nor that its north tile will be on a non-desert tile; it only means that at least one tile of the building will be on a non-desert tile. (e.g. it can still be built on the very edge of a desert) This restriction was removed in OTTD r13489, the callback is now called for the final position of the north tile.

AI construction/purchase selection (18)

This generic feature callback is called for various decisions when the AI is constructing a new route. For example, normally the AI has a hardcoded list of wagons for each cargo type, but with this callback you can make the selection depend on source and destination industries as well as service distance among other things.

Since the vehicle hasn't been bought yet, you cannot use the usual 40+x or 80+x vehicle variables, instead you have the following:

Variable Size Content
80 B cargo type (climate specific, column 3, type B in the cargo type list)
81 B cargo type (climate independent, column 1, type A in the cargo type list)
82 B default selection
83 B source industry type. For new industries the substitute type is returned starting with OpenTTD r20108.
84 B destination industry type. For new industries the substitute type is returned starting with OpenTTD r20108.
85 B distance between source and destination, in (dx+dy)/2
86 B AI construction event
87 B Construction number; for wagons: number of wagon; for stations 0=source station, 1=destination station
88 B Station size in form NL; N=number of platforms, L=length
40 D xxxxxxTT, TT=cargo slot from cargo translation table or same as var.81 if no table, available since r1167/2.5b9

The callback will be called for following construction events, stored in variable 86:

Group Feature Var.86 Type Description
Trains 00 00 Check Regular rail engine
01 Check Electric rail engine
02 Check Monorail engine
03 Check Maglev engine
08 Get Regular rail wagon
09 Get Electric rail wagon
0A Get Monorail wagon
0B Get Maglev wagon
0F Get Track type to build
Road Vehicles 01 00 Check Road vehicle
01 Get First road vehicle ID to try
02 Get Number of road vehicles to try
Ships 02 00 Check Ship
01 Get First ship ID to try
02 Get Number of ships to try
Aircraft 03 00 Check Aircraft
Stations 04 00 Get Station ID

Notes:

  • "Check" means to check if it should try to buy this vehicle (with ID in var.82). Return 00 to disallow purchase, or a non-zero value to allow it. If allowed, the computer will buy the highest-cost (or AI rank for train engines) vehicle it can find that is available and has high enough reliability.
  • "Get" means to find out which ID (etc.) to use. The default in var.82 is what it will use if the callback fails.
  • For train engines and aircraft, the AI always checks all available engines.
  • For road vehicles and ships, the AI has a built-in list of vehicles to try, you can use callback event 01 and 02 to change that list.
  • For trains, the track types (0=regular, 1=electric, 2=monorail, 3=maglev) are automatically mapped as appropriate depending on the electrifiedrailways/unifiedmaglev switches. For best results, assume that all four are available. The game will then use the correct one if it is not available.

This callback is "chained", i.e. if a result is not a callback result (high bit is not set), then the request is passed on to the previous generic callback handler, i.e. they are checked in reverse order. This makes it possible to leave certain decisions to the previous handler and allows some cooperation between several .grf files.

Cargo Subtype Display (19)

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 returns FF.  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.

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.

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, or bit 2 of property 13 for stations.

Additionally all animation callbacks also allow to trigger sound effects as described in Callback 148.

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 and stations). 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, property 19/bit 2 modifies this callback slightly, see details there.

For industry tiles and stations, the low byte of variable 18 contains the reason for the call, i.e. the bit number of the event from property 11 or property 18, accordingly.

Unlike callback 1B, callbacks 25, 140 and 159 are always used when defined, no bit in the action 0 property needs to be set to activate them.

Since TTDPatch 2.5 beta 2, this callback gets random bits in variable 10, to allow randomizing changes.

For callback 1B, the exact randomness depends on bit 2 of 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 callback 25, 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 callback 140, the high 16 bits are the same for all tiles triggered, while the low 16 bits are different for each tile.

Additionally all animation callbacks also allow to trigger sound effects as described in Callback 148.

Construction stage changes (1C)

Called when the building changes its construction stage (during normal gameplay, that means exactly four times). Can return the same values as callback 1B. Variable 40 contains the new stage. You can return FF for stages that don't have animated graphics to save resources.

Watched cargo accepted (148)

Called when a cargo type specified in property 20 is accepted by a house tile, or to be more specific, in a station that has the house tile in its acceptance area. It 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. The low word of variable 18 contains the offset of the trigger tile relative to the current tile; the low byte contains the X offset, the high byte the Y offset. (0 means it's the same tile, negative coordinates mean it's northward, positive southward.) With this, you can tell apart the callings within the same tick. The high word of variable 18 contains random bits, the bits are the same for each tile of multi-tile buildings. The return values can be the same as for callback 1B.

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

This callback isn't available if the station2 structure isn't present - see the property 20 entry for more information.

If any of the above animation callbacks return a nonzero value in the high byte, it will be interpreted as a sound effect number, and the corresponding sound effect will be played on the house tile.

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 variational action 2s 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.

Var. action 2 type 82 (engine) refers to the engine the wagon is being attached to, starting from version 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.

Return values:

Return Meaning
xx Disallow attaching and use the D0xx text ID as second line of an error message,
FD Disallow attaching with the standard message (incompatible rail types)
FE Allow attaching
FF Allow attaching if the rail types match (default)

It you return FE, you would allow attaching for example a monorail wagon to a regular rail vehicle, so if that's not what you intend, return FF.

Building colour (1E)

Called to decide what colour mapping the building should use. Should return the number of the colour mapping to be used, for example, 775 for blue->dark blue mapping.

This can be useful if you want something more complex than four random colours.

From 2.0.1 alpha 67, you can return a value of col2*16+col1 plus bit 14 set, where col1 and col2 are two company colours. For example, a return value of 73 C0 uses col1=3=yellow and col2=7=dark green. If no two-company-colour maps have been installed, the colours from prop. 17 are used instead.

Uses 15 return bits.

Cargo acceptance (1F)

Called to decide what the building tile can accept. Uses 15 return bits. The returned word should have the layout of Sgmp, where the letters mean the following:

Symbol Meaning
S 1 if the building should accept food/fizzy drinks instead of goods
g If S is 1, the food acceptance in 1/8 units
If S is 0, the goods acceptance in 1/8 units
m mail acceptance in 1/8 units
p passenger acceptance in 1/8 units

So, for example, giving the ID 8426h means "4/8 goods, 2/8 mail, 6/8 passenger", while giving the ID 9205 means "2/8 food, 5/8 passenger".

If property 1E and/or callback 2A is used, the meaning changes slightly. In this case, p means the acceptance of the first cargo type given, m means the same for the second cargo type, and g is the same for the third cargo type, while S must be zero.

Length of animation frame (20/27/142/154/15A)

Called to decide how long the current animation frame should last. The value of the delay should be given in the same way as for property 1B/10/17. Decreasing the return value speeds the animation up instantly. Increasing, on the other hand, doesn't slow it down instantly: the actual duration of the current frame will be somewhere between the old and the new delays. The new delay is applied correctly for later frames.

Note: This is one of the most time consuming callbacks as it is called for every animated tile every ≈30 milliseconds. For better performance try to avoid using it where reasonable, e.g. try to use only the properties and put multiple identical looking animation frames after each other.

Trigger building destruction (21)

Called periodically, in a time interval specified by property 16. If it returns a nonzero value, the building gets removed from the map as if the town decided to destroy it. You can use this for example to remove a historical building, since those cannot be normally removed by towns.

Industry availability (22)

Called when TTDPatch needs to know if a given industry type is available.

Return zero to make your type available, or any nonzero value to disable it. This callback is intended for limiting your type as a whole, so you can't access any industry-specific variables, just the global ones. A good example for the use of this callback is a nuclear power plant that isn't allowed to appear before 1970.

During this callback, variable 18 (extra callback info 2) can contain the following values:

Variable 18 Meaning
0 TTD is generating a map and needs to know if your type can appear.
1 TTD decided to build a new random industry during regular gameplay and needs to know if it can choose your type.
2 The user tries to build/prospect for your industry via the new industry window. TTD needs to know if the player is allowed to do this.

Additional text in purchase screen (23)

This callback is called when TTDPatch displays the vehicle stats of any vehicle in its purchase screen. The return value is the "xx" of a D0xx text ID to be shown below all other stats. The callback is always used when defined, no bit in the action 0 property needs to be set to activate it. As of r1908, text IDs D100..D3FF may also be returned.

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. Lines are wrapped automatically, or may be broken explicitly using the newline character 0D.

If cargo FF (buy menu sprite) is handled explicitly for a vehicle, then the varaction 2 handling callback 23 must be in the buy menu varaction 2 chain.

Custom station layout (24)

After applying the values from station prop. 0E, this callback is used to further customize the tile layout.

It is called once for every tile that is being built, and returns the new tile type to build in its place or to leave the tile as defined by prop. 0E or TTD's default if the callback fails. The only possible return values are 00, 02, 04 and 06. Their meaning is the same as in prop. 0E.

Since the station hasn't yet been built, variables 40+x and 80+x are not available, instead variable 10 (extra callback info 1) contains the same information as variable 41 would contain. For the same reason, it uses the same cargo type in action 3 as the construction menu does (i.e., type FF if defined or else the default).

This callback is used always and does not need setting a bit in the action 0 property to activate it.

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]] Meaning
40+x Not accessible
5F Since OpenTTD r19744: Random bits the industry starts with after construction. Accessible via RandomAction2 as well.
60+x Only var. 62 and vars 64..68 can be used
80 W Coordinates of the selected position
86 B Number of the selected layout, according to property 0A
87 B Ground type of the selected spot (see canal variable 81 for details)
88 B Town zone of the selected spot (see house variable 42 for details)
89 B Distance between the closest town and the selected position.
8A B Height of the lowest corner of the tile (between 00h and 80h, one land height unit equals 8 units)
8B W 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 Square of the Euclidean distance between the closest town and the selected position
8F D 32 random bits (since r1816 and r11985)

Unless explicitly noted, distances are Manhattan distance, not Euclidean distance, ie. -+||x-x0||+||y-y0||+- instead of -+sqrt


... LOTS OF STUFF MISSING HERE ...


Action 11. If the callback returns a failure code (not a callback result), the default TTD sound effect will be played. If the callback returns a sound number that is neither a TTD sound, nor a sound from action 11, nothing will be played.

Var. 10 Event
1 Start sound, called when leaving a station or depot, take-off sound for planes
2 Tunnel sound, called when vehicle enters tunnel
3 Breakdown sound, called when vehicle breaks down (not for planes)
4 Running sound, called once per engine tick, but no more than once per vehicle motion
5 Touchdown sound, for planes only (obviously)
6 Train visual effect generation (steam plume, diesel smoke, electric spark)
7 Running sound, called every 16 engine ticks if in motion
8 Stopped sound, called every 16 engine ticks if stopped (e.g. at signal/in station)
9 Load/unload sound, called when consist loads or unloads cargo
10 Bridge sound, called as generic feature 06 callback every time a consist moves on a bridge. Variables 40+x, 60+x and 80+x refer to the vehicle and bits 0..7 of variable 18 hold the bridge type

For the running sounds, it is advisable to check the motion counter and to only return a successful sound effect number every so many vehicle motion ticks. This way, the sounds will be played more frequently the faster the train is. Alternatively, you can check the tick counter variable and play the sound effect every so many engine ticks, so that it is played at a constant rate, or, of course, switch between both modes depending on vehicle speed.

Note that if the planespeed switch is active, planes move the given number of times per engine tick. This means that their motion counter increases faster than for other vehicles, and thus to get reliable sound effects you need to divide the motion counter by the planespeed setting (readable via action D) before checking the value.

Autoreplace vehicle selection (34)

This callback is called whenever an old vehicle needs replacing. It returns the vehicle IDs to upgrade the current vehicle to. The vehicle variables are available as usual to decide which IDs would be appropriate to upgrade to.

The callback is repeatedly called, with the iteration number stored in variable 10.  The .grf file should return all possible IDs one by one, with the best ones listed first.  The patch will use the first vehicle from the list that is available to the player and has the required minimum reliability as set by the autoreplace switch, and abort the callback sequence at this point.

The callback sequence is also aborted when the returned ID is equal to the current vehicle ID. This is to prevent downgrading, and so you must take care to always return the ID of the vehicle for which the callback is called at the appropriate place in the sequence.

If the callback fails, i.e. if no suitable ID could be found by any of the callbacks in the generic chain, the vehicle is not upgraded, and is simply renewed instead.  If an ID is available but the player lacks the cash to upgrade, the patch waits for the cash to become available instead of either picking a worse engine or renewing the vehicle.

For trains, each engine head will be replaced by one vehicle of the new type.  As such, it is advisable for only return "compatible" IDs for trains that require a particular construction or arrangement of engine heads.

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

Monthly random production change (35)

Works exactly the same way as callback 29, except that it's called every month, allowing more frequent production changes.

Change vehicle properties (36)

This common callback allows modification of certain properties of a vehicle for which there exists no specific callback (like CBs 10, 11, 12). The low byte of variable 10 holds the property number from Action 0.

The following properties are supported:

Feature Property Minimum version OpenTTD rev
Trains (00) 07 (Load amount) - - Changeable via callback 12
09 (Speed) 2.5 beta 6 r9671
0B (Power) 2.5 beta 6 r9671
0D (Running cost factor) 2.6 rev 1420 r9671
14 (Cargo capacity) 2.6 rev 1966 r9828 See also callback 15
16 (Weight) 2.6 rev 1887 r9780
17 (Cost factor) r9806
1F (Tractive effort) 2.5 beta 6 r9671
21 (Short wagons) - - Changeable via callback 11
22 (Visual effect & powered wagons) - - Changeable via callback 10
25 (User data) 2.5 beta 6 r11431
Road Vehicles (01) 07 (Load amount) - - Changeable via callback 12
09 (Running cost factor) r18011
0F (Cargo capacity) r9828 See also callback 15
11 (Cost factor) r9806
13 (Power) r21058
14 (Weight) r21058
15 (Speed) r21100
18 (Tractive effort) r21058
Ships (02) 07 (Load amount) - - Changeable via callback 12
0A (Cost factor) 2.6 rev 1990 r9806
0B (Speed) 2.5 beta 6 r9671
0D (Cargo capacity) 2.6 rev 1990 r9828 See also callback 15
0F (Running cost factor) 2.6 rev 1510 r9808
Planes (03) 07 (Load amount) - - Changeable via callback 12
0B (Cost factor) r9806
0C (Speed) 2.5 beta 6 r9671
0E (Running cost factor) 2.6 r1507 r9678
0F (Passenger capacity) r19218 See also callback 15
11 (Mail capacity) r19218

Most properties will only change when the vehicle is bought, serviced (enters a depot), visits a station or on loading of a saved game. Other ones such as TE are called every time a TE calculation is run.

If the callback fails, the corresponding value from the action 0 property will be used. The callback is always used when defined, no bit in the action 0 property needs to be set to activate it.

Before r1758 (both 2.5 and 2.6), callback 36 was sometimes called with the 40+x and 80+x variables unavailable when they should have been available, or with not all 80+x variables properly initialized, causing some 40+x variables to be unsafe.

About the capacity properties see also the summary page about  vehicle refitting.

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. Just like callback 19, the return value must be the number of a D0xx string set by an action 4 in the same .grf file. Returning FFh causes no text to be displayed.

During the callback, the lowest byte of var. 18 can have the following values:

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

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

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

Since OpenTTD r17802, the contents of registers 100h..105h are copied onto the text reference stack.

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. The return value should be the number of a D0xx text to be displayed. 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.

Since OpenTTD r20086 and TTDPatch r2354, the contents of registers 100h..105h are copied onto the text reference stack.

Custom profit calculation for cargoes (39)

This callback is called every time cargo is delivered to a station, to get how much income the player should get. The low word of var. 18 contains the distance of the transfer, byte 3 contains the amount of cargo moved and the highest byte contains the time spent en-route (a unit of time is +185 ticks, or ca. 2.5 days). The result should be a signed multiplier that gets multiplied by the amount of cargo moved and the price factor, then gets divided by 8192. Since the highest bit must always be set for a callback result, TTDPatch checks for the second highest bit (bit 14) for the sign. Returning a negative value means that the player has to pay for the transfer instead of getting money from it. For example, the maximum returnable value of 16383 means that the player gets twice the price factor for every unit.

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. The return value should be the number of a D0xx text to be displayed. 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.

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.

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

Control special industry effects (3B)

This callback allows you to control some aspects of the special effects enabled in property 1A. The lowest byte of variable 18 always contains the number of the special effect, which equals to the bit number being set in property 1A. Currently only effect 0 (plant fields periodically) and effect 1 (cut nearby trees periodically) are supported.

  • For effect 0 you should return zero to avoid planting fields and any other value to plant a field. The callback is called every 256 ticks for a given industry. Variable 10 contains 32 random bits that can be used to randomize the behaviour. Industry variable AAh (word) can be used to make the plantings rarer, but please note that the low byte is always zero at this point. The default behaviour is giving 1/8 chance to plant a new field every 256 ticks.
  • For effect 1 you should return zero to avoid cutting a tree and any other value to try cutting one. The callback is called every 256 ticks for a given industry. You don't get random values this case, but you can still use variable AAh; the low byte is always zero here as well. The default behaviour is trying to cut a tree every 512 ticks.

Disable autosloping (3C/14F/15D)

With this callback, you can prevent the autoslope feature from altering the ground below a house/industry/object tile. To allow altering the ground, return zero. Returning anything other than zero will disallow land modifications.

Opt out of accepting cargo (3D)

With this callback, the industry can refuse accepting a cargo even if it's one of the input cargo types. If there's another industry nearby that accepts this cargo, that one will get it.

The lowest byte of var. 18 contains the ID of the cargo delivered. If your GRF has a cargo translation table installed, you will get the index from that table; otherwise, you will get the cargo bit associated with the cargo type. You must return zero if you don't want to accept the cargo, or 1 to accept it. Other return values are reserved for future use.

This callback should be used in conjunction with callback 2B, since the acceptance of the tiles and the acceptance of the industry itself should always agree. If you disable accepting a cargo via callback 3D, but forget to remove the acceptance from the tiles, the station will keep accepting the cargo and the player will keep getting the money, but the industry won't receive the cargo. On the other hand, if you remove acceptance from the tiles, but forget using callback 3D, your industry may still get the cargo. (For example, there may be another industry nearby whose tiles accept the cargo. This makes the station accept the cargo, and send it to the nearest industry, which happens to be yours, even though its tiles don't accept the cargo.)

Protect building conditionally (143)

This callback is called when someone tries to remove the building from the map. You can use this callback to prevent the town or AI players from removing the building if certain conditions are met. You can return 0 to allow the destruction, or 1 to disallow it, except for human players, who can always remove any building.

If you always return 1 from this callback, you achieve the same effect as turning on bit 1 of property 19. When this callback is enabled, bit 1 of property 19 is ignored. If the callback fails, the destruction is allowed.

For multi-tile buildings, the callback will be called for the type of the tile the player wants to destroy. Therefore, to get consistent behaviour, you must enable this callback for every tile and respond it the same way no matter which tile it is called for.

Since TTDPatch 2.6 r1705, you can use this callback to prevent building "town" industries (banks, water towers, etc.) over your house. The lowest byte of variable 10 is zero for "normal" demolition and one when TTD wants to remove the house for the sake of a new industry. Other values of variable 10 are reserved for future use.

Ambient sound effects (144)

This callback is a generic callback for feature 0C (new sounds) used for playing ambient sound effects.

The 15-bit return value is the sound effect number. Values from 0 to 72 (dec) are TTD's built-in sound effects, values beyond that refer to the sounds from Action 11.

To decide whether to play a sound, and what sound to play, Var.Action 2 variable 10 holds the following information: THRRxxxt

Field Meaning
T Tile class, 0=bare land, 4=trees, 6=water
H Height of north corner of tile
RR 8 random bits
xxx Reserved
t Terrain type;  0 normal (grass), 1 desert, 2 rainforest, 4 on or above snowline

|- |This callback must be enabled by bit 4 in action D var 9E.

Custom station rating calculation (145)

This callback allows you to modify part of the station cargo rating calculation for your cargo. To understand how to use it, you must first understand how the default rating calculation works:

Internally, the station rating is stored in a byte, 0 meaning 0% and 255 meaning 100%. The rating is calculated as the sum of the following components:

  • Time since the cargo was last picked up:
Time units (days) Score (%, rounded)
>21 (>52.5 days) 0 (0%)
13..21 (32.5 days..52.5 days) 25 (10%)
7..12 (17.5 days..32.5 days) 50 (20%)
4..6 (10 days..17.5 days) 95 (37%)
0..3 (0 days..10 days) 130 (51%)

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

  • Amount of cargo waiting:
Amount of cargo Score (%, rounded)
>1500 -90 (-35%)
1001..1500 -35 (-14%)
601..1000 0 (0%)
301..600 10 (4%)
101..300 30 (12%)
0..100 40 (16%)
  • Max. speed of the last vehicle picking up the cargo:

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

  • Age of the last carrier picking up the cargo:

The original calculation goes like this:

Age of vehicle (years) Score (%, rounded)
2 10 (4%)
1 20 (8%)
0 33 (13%)

If the newagerating switch is turned on, the calculation changes. You get 33 points for vehicles younger than 5 years, and get 0 points for vehicles older than 21 years. Between these two ages, score drops slowly, by 2 points per year.

  • Bonus for AI companies
AI intelligence setting Score (%, rounded)
Low 0 (0%)
Medium 31 (12%)
High 63 (25%)

That is, AI players cheat to get good ratings for their brain-dead routes.

  • Bonus for statue in nearest town

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

If a human player does everything perfectly, the maximum rating she can get is 271 points, while the worst possible transport service gets -90 points; for "highly intelligent" AI players, the corresponding values are 334 and -27, respectively. The resulting value gets clamped to the 0..255 range. TTD makes sure the ratings change slowly, but steadily: every 2.5 days, the actual rating moves towards the value calculated above, by no more than 2 points. For example, you 'd need at least 320 days to go from 0% to 100%, even if your service is perfect. When a cargo type first appears at a station, its rating is set to 175 points (69%), so it takes some time until it gets adjusted to the actual parameters of the service.

The callback allows you to replace the first three components (days since last pickup, amount waiting and max. speed of last vehicle) in the calculation above. If your callback succeeds, the first three components are skipped and the returned value is used instead their results. Bit 14 is considered the sign bit, so you can return negative numbers (and need not to worry about calculated callback results yielding a negative result, as long as you stay in the range -16384..16383). During the callback, variable 18 has the value ssaaaatt, where

  • tt is the time since the cargo was last picked up, in the time units described above (1 unit = 2.5 days independent of vehicle type)
  • aaaa is the amount of cargo waiting
  • ss is the speed of the last vehicle picking the cargo up, in the speed units described above (if no vehicle entered the station yet, the value is FFh)

The lowest byte of variable 10 contains one of the following values:

value meaning
10h the last vehicle entering the station was a train
11h the last vehicle entering the station was a road vehicle
12h the last vehicle entering the station was a ship
13h the last vehicle entering the station was an aircraft
00h no vehicle entered the station yet, or the last one entering was sold

Please note that there's only one "last vehicle" field per station, so the vehicle this refers to may not have picked up any of your cargo. The original TTD calculation doesn't care about this and just uses the field to get the vehicle type used in the first component.

Currently, you can only use variables 10 and 18 for your decision, since neither vehicle nor station variables are available for a cargo callback. As soon as the architecture of TTDPatch allows this, the callback will be given access to the station and the last vehicle that entered.

New signals sprite drawing callback (146)

This is a generic callback, and thus a generic action 3 must be used. It must be processed by a variational action 2 feature 0E, as indicated in the following link: VarAction2NewSignals.

Add sprite offset callback (147)

Add an offset to the default sprite number to be drawn.

Feature Accessible Variables
Canals 80+x variables are accessible by Canals. See VarAction2Canals

The default number is accessible in variable 10 (extra callback info 1) to decide if the sprite number needs an offset.

Land slope check (149/157)

This callback is called for each tile where the new station part will be built. It can return zero to accept the current tile or one to make the station building fail with the "Land sloped in wrong direction" error message. Other return values are reserved for future use, don't use them for now.

Since the station isn't built yet, no 8x variables can be accessed. Only variables 43 and 67 will work from the 4x and 6x variables. You get the following information, though:

  • variable 18:
bit numbers Meaning
0..7 offset of current tile on the platform, 0 is the northmost tile
8..15 bits 8..15: current platform number, 0 is the northmost platform
16..23 total length of station being built
24..31 total number of platforms being built
  • variable 10:
bit numbers Meaning
4..7 Slope info of the current tile:~pp~

bit 7 - N corner is elevated

bit 6 - E corner is elevated

bit 5 - S corner is elevated

bit 4 - W corner is elevated~/pp~

0..3 the same information, but "mirrored" (bit 0 and 2 swapped) if the station is built in the NW-SE orientation. This allows you to check slopes without checking the orientation explicitly.
other bits reserved for future use

The callback is called only after the normal checks TTD does for slopes, so it's not possible

to allow a slope that isn't allowed by default; you can only narrow the set of allowed slopes. If the callback fails, the tile will be accepted. It is, however, called for flat tiles, so you can force your station to sloped land. You can't access the station info even if the platform is added to an existing rail station or is overbuilding station tiles. That's because TTD will decide this later in the code, after the slope is already accepted.

This is called if available just before object construction, it does not require that any flags be set in the action0.

Please note that for Objects only the low byte of variable 18 is valid (Offset from north tile (origin), stored as YX) and that variable 10 does not have the reversed version, and bits 0 - 3 contain the actual raised corners (same order as bits 4 - 7).

Decide industry colour (14A)

This callback is called when the industry is being constructed, to override the selected colour of the industry (variable A8). This colour will be used for tile sprites that request recolouring, but don't supply a recolour sprite number. The following industry variables aren't yet filled and contain random junk: 86..87, 93, 9E..A1, A9. (You probably wouldn't need to read anything but 86..87 anyway, since these fields contain information about the past, and the industry doesn't yet have a past.) Industry tiles aren't placed yet, either.

Variables A7 and A8 are filled, however, and provide useful information. Variable A7 contains the number of the funder company, or 10h if the industry wasn't funded. Variable A8 contains the number of the colour scheme randomly picked by TTD, it's between 0 and 15. If you don't want to change the colour picked by default, you can either make the callback fail or just return variable A8 unchanged.

Only the lowest four bits of the returned value are used, the other bits are reserved for future use. Those four bits are copied into variable A8 after the callback returns. You can either use industry variable 45 to get the company colour of the funder (if there's any), use a random action2 to select a random colour scheme from a given list, or of course decide on global variables like position or game year.

Decide input and output cargo types (14B,14C)

These callbacks are called when the industry is built, and allow customizing the input and output cargo types dynamically. Both callbacks are called repeatedly, with the lowest byte of variable 10 starting from zero and increasing after every call; you should return a cargo type each time, or FFh to terminate the list. (A failed callback terminates the list, too.) The same limitations apply as for callback 14A: industry tiles aren't yet placed, and some industry variables contain junk. You can use random action2s, however. The interpretation of the returned value depends on two factors: the current GRF version number and the presence of a cargo translation table:

GRF version Has cargo translation table Interpretation
6 or below Climate-dependent cargo slot number
7 or above No Cargo bit
7 or above Yes Index in the translation table

Although currently callback 14B is called no more than three times, and callback 14C no more than twice, this may change between versions/implementations, to allow more input/output types. To be safe, you should return FFh as the last element even when you use all three input types or both output types.

House customized building name (14D)

This callback is activated from the Tile Description Query tool, when enquiring a house.  Variable 10 will be set to 1 if the house is complete, otherwise it will be 0.  The return value is the "xx" of a D0xx text ID.  If the callback fails, the Query tool will use the house name set in property 12 (Building name ID).

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

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

This callback allows you to display some extra text in the build airport gui. It should return a D0xx StringID. 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

Airport layout name (156)

This callback allows you to show a name for an airport layout. It should return a D0xx StringID. 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.

Decide object colour (15B)

This callback allows you to set/modify the colour of an object upon construction. Variable 10 contains the current company colour or a random colour for when there is no company, i.e. in the scenario editor. If the object wants a 2CC colour mapping two nibbles, i.e. two colours, are passed in variable 10, otherwise one nibble (colour).