View source for Callbacks

==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. &nbsp;See the [[ttwiki:CallbacksTut|callback tutorial]] on how to use them.

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

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

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

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

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

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

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

Note: Some NewGRFs still use type 81 for callbacks. However, testing callbacks with type 81 has been depreciated since 2005/2006 and should not be used. It only still works because new callback IDs were assigned in a backwards-compatible way.

== List of callbacks ==

The following callbacks are defined by the patch. &nbsp;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. &nbsp;All callbacks are explained in more detail below.

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

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

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