GRFSpecs - User contributions [en-gb]

Callbacks

2013-10-19T11:46:33Z

Gesia: /* Introduction */

==Introduction==

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

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

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

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

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

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

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

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

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.  The number of the callback is what will be stored in variable 0C so that you can return the right results if you have several callbacks.  All callbacks are explained in more detail below.

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

{| |-
!Number!!Feature(s)!!Meaning
|-
|10||Vehicles||[[Callback: Visual effect and wagon power|Visual effect and wagon power]]
|-
|11||Vehicles||[[Callback: Wagon length|Wagon length]]
|-
|12||Vehicles||[[Callback: Load amount|Load amount]]
|-
|13||Stations||[[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}}

Talk:Callbacks

2013-10-19T11:44:50Z

Gesia:

--[[User:Gesia|Gesia]] ([[User talk:Gesia|talk]]) 21:48, 17 October 2013 (UTC)

The new introduction states that variable 1C is a word and therefore type 85 must be used.

However, the paragraph below mentions variable 0C and some GRFs (e.g. Ikarus 6) use type 81, which seems to work ingame:

81 * 9 02 01 02 01 01 00 00 00 00
82 * 14 02 01 10 '''''81 0C''''' 00 FF 01 02 FF 23 23 02 00
83 * 7 00 01 01 01 02 0E FF
84 * 10 03 01 01 02 01 FF 10 00 A1 00

I'm guessing some relevant information is still missing?

--[[User:Frosch|Frosch]] ([[User talk:Frosch|talk]]) 18:06, 18 October 2013 (UTC)
1C was wrong, I copied that from your example :p It's in fact 0C.

Testing callbacks with type 81 was deprecated 2005 or 2006. It should no longer be used. It only still works because new callback IDs were assigned in a way, so that old NewGRF do not break. That's the reason why there is a gap from 3E to 13F.

--[[User:Gesia|Gesia]] ([[User talk:Gesia|talk]]) 11:44, 19 October 2013 (UTC)

How smart of me to point out my own mistakes as somebody elses, isn't it? Seriously though: sorry, that was pretty stupid.

After having a closer look it seems to me that several well known NewGRFs actually use type 81. Hence, I took the liberty of adding your answer (in slightly modified form) to the introduction.

Callbacks

2013-10-19T11:41:05Z

Gesia: /* Introduction */ Added note about old NewGRFs using depreciated type 81

==Introduction==

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

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

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

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

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

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

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

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

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 backwards-compatible way until now.

== List of callbacks ==

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

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

{| |-
!Number!!Feature(s)!!Meaning
|-
|10||Vehicles||[[Callback: Visual effect and wagon power|Visual effect and wagon power]]
|-
|11||Vehicles||[[Callback: Wagon length|Wagon length]]
|-
|12||Vehicles||[[Callback: Load amount|Load amount]]
|-
|13||Stations||[[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}}

Talk:Callbacks

2013-10-17T21:48:38Z

Gesia: Discussion started for "callbacks"

Callback: Additional text in purchase screen

2013-10-16T18:03:50Z

Gesia: /* Additional text in purchase screen (23) */ Example added

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

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

A text string for feature 48 in the D0XX range must be defined before using this callback. Line breaks (0D) and colors are supported. The return value of this callback is the XX of a D0XX string ID.

As of r1908, text IDs D100..D3FF may also be returned.

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

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

Example for setting additional text for a road vehicle:

// Define string with ID D001. Bit 7 of the language byte must be set to 1, because the string ID is a word.
4 * 32 04 48 83 01 01 D0 "Hint: This is a " 0D "new line." 00
// The callback
5 * 14 02 01 10 81 0C 00 FF 01 01 80 23 23 02 00

{{grfFrom|8}} Since GRF version 8 the value 400 can be returned to display no text. In older versions it is necessary to fail the callback.

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

[[Category:Callbacks]]

Callbacks

2013-10-16T17:43:22Z

Gesia: /* Format: */ Added section about callback format, because I missed it very much while trying to get the grasp of it.

==Introduction==

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

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

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

== Format ==

A callback has the same format as a VarAction2 with some values used in a different way:

<Sprite-number> * <Length> 02 <feature> <set-id> <type> 1C <varadjust> <nvar> (<value> <callback> <callback>){n} <default>

{| |-
!'''Element'''!![[GRFActionsDetailed|'''Size''']]!!'''Description'''
|-
|<Sprite-number>||dec||A sequential sprite number
|-
|<length>||dec||The total number of bytes used in this action.
|-
|02||B||Defines action 02
|-
|<feature>||B||For what type of vehicle/station should this definition be used?
|-
|<set-id>||B||The ID of this action 2 (used like a cargo ID)
|-
|<type>||B||Size definition, 81 for Byte, 85 for Word, 89 for DWord
|-
|1C||B||The callback variable
|-
|<varadjust>||V||How to manipulate the value before deciding.
|-
|<nvar>||B||Number of callbacks
|-
|<value>||W||The return value, with bit 15 set to 1 to indicate a callback result.
|-
|<callback>||B/W/D||The callback code, must be repeated to comply with the format of VarAction2.
|-
|<default>||W||00 00, <set-it> 00, or something else.
|}

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

You repeat the sequence of <value> <callback> <callback> as often as <nvar> specifies.

<callback> has a size of B, W, or D, depending on <type>.

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

== List of callbacks ==

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

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

{| |-
!Number!!Feature(s)!!Meaning
|-
|10||Vehicles||[[Callback: Visual effect and wagon power|Visual effect and wagon power]]
|-
|11||Vehicles||[[Callback: Wagon length|Wagon length]]
|-
|12||Vehicles||[[Callback: Load amount|Load amount]]
|-
|13||Stations||[[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}}

VariationalAction2

2013-10-16T15:15:17Z

Gesia: /* Format */

==Introduction==

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

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

== Format ==

The data looks as follows:

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

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

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

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

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

== Description ==

=== Sprite-number ===

This is just the number you are at.

=== Length ===

Count the number of bytes in this action.

=== Feature ===

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

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

=== Set-ID ===

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

=== Type ===

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

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

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

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

=== Variable ===

Variational Action 2 allows accessing these variables:

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

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

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

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

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

=== varadjust ===

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

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

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

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

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

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

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

=== nvar ===

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

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

=== sets and ranges ===

For each of the ranges to check, you give the set-id as a '''WORD''' value (i.e. with a 00 following, e.g. set-id 5 becomes 05 00, or - in case of a callback result - by setting the high bit, e.g. 05 80), followed by the low and high limits of this range.  The first range that matches will be used.

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

=== default ===

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

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

</pre>