Difference between revisions of "GlobalVariables"

From GRFSpecs
Jump to navigationJump to search
(→‎TTDPatch Version (0B / 8B): Use real footnote)
(OpenTTD versioning schema changed with version 12)
 
(25 intermediate revisions by 4 users not shown)
Line 6: Line 6:
 
!rowspan=2|'''Description'''
  
!rowspan=2|'''Description'''
 
|-
  
|-
−
|[[VariationalAction2 | VA2]]||A[[Action6|6]]/[[Action7|7]]/[[Action9|9]]||[[ActionD|ActD]]<ref>The Action D column refers to write access to the variables. Reading variables via Action D is the same as for Action 6/7/9.</ref>
 +
|[[VariationalAction2 | VA2]]||A[[Action6|6]]/[[Action7|7]]/[[Action9|9]]/[[ActionD|D]]<br>(read)||[[ActionD|ActD]]<br>(write)
 
|-
  
|-
−
|00||80|| ||W||{{ottdp|0.6| }}||current date (counted as days from 1920)<ref name="startdate">{{ottdp|0.7}} In multiplayer games OpenTTD doesn't report the current date and year to actions 6,7,9 and D, but the date and year the game was loaded. The reason lies in the fact that it was seen that use of this variable leads to desyncs in network games.</ref>
 +
|00||80|| ||W||{{ottdp|0.6|2.0}}||current date (counted as days from 1920)<ref name="startdate">{{ottdp|0.7}} In multiplayer games OpenTTD doesn't report the current date and year to actions 6,7,9 and D, but the date and year the game was loaded. The reason lies in the fact that it was seen that use of this variable leads to desyncs in network games.</ref>
 
|-
  
|-
−
|01||81|| ||B||{{ottdp|0.6| }}|| Current year (count from 1920, max. 2175 even with eternalgame)<ref name="startdate"/>
 +
|01||81|| ||B||{{ottdp|0.6|2.0}}|| Current year (count from 1920, max. 2175 even with eternalgame)<ref name="startdate"/>
 
|-
  
|-
−
|02||82|| ||B/D||{{ottdp|0.6| }}|| current month (0-11) in bits 0-7; the higher bytes contain unusable junk.<ref name="startdate"/><br/>{{ottdp|0.7|ottdrev=r13594}} Since OpenTTD r13594 'day of month' (0-30) is stored in bits 8-12, bit 15 is set in leapyears and 'day of year'(0-364 resp. 365) is stored in bits 16-24. All other bits are reserved and should be masked.
 +
|02||82|| ||B/D||{{ottdp|0.6|2.0}}|| current month (0-11) in bits 0-7; the higher bytes contain unusable junk.<ref name="startdate"/><br/>{{ottdp|0.7|ottdrev=r13594}} Since OpenTTD r13594 'day of month' (0-30) is stored in bits 8-12, bit 15 is set in leapyears and 'day of year'(0-364 resp. 365) is stored in bits 16-24. All other bits are reserved and should be masked.
 
|-
  
|-
−
|03||83|| ||B||{{ottdp|0.6| }}|| Current climate: 00 = temp, 01 = arctic, 02 = trop, 03 = toyland
 +
|03||83|| ||B||{{ottdp|0.6|2.0}}|| Current climate: 00 = temp, 01 = arctic, 02 = trop, 03 = toyland
 
|-
  
|-
−
| ||84|| ||D||{{ottdp|0.6| }}|| [[GrfLoadingStages|GRF loading stage]], see below
 +
| ||84|| ||D||{{ottdp|0.6|2.0}}|| [[GrfLoadingStages|GRF loading stage]], see [[#GRF_Loading_stage_.28-_.2F_84.29|below]]
 
|-
  
|-
−
| ||85|| ||B||{{ottdp|0.6| }}|| [[TTDPatchFlags|TTDPatch flags]]: only for bit tests
 +
| ||85|| ||B||{{ottdp|0.6|2.0}}|| [[TTDPatchFlags|TTDPatch flags]]: only for bit tests
 
|-
  
|-
−
|06||86|| ||B||{{ottdp|0.6| }}|| Road traffic side: bit 4 clear=left, set=right
 +
|06||86|| ||B||{{ottdp|0.6|2.0}}|| Road traffic side: bit 4 clear=left, set=right; other bits are reserved and must be masked.
 
|-
  
|-
−
| ||88|| ||4*B||{{ottdp|0.6| }}|| Checks specified GRFID (see condition-types below)<ref>The value of variable 88 can only be tested with the GRFID tests.</ref>
 +
| ||(87)||(87)||B||{{ottdp|no|no}}|| No longer used since TTDPatch 2.0. (was width of "€" character)
 
|-
  
|-
  +
| ||88|| ||4*B||{{ottdp|0.6|2.0}}|| Checks specified GRFID (see [[Action7#condition-type|condition-types]])<ref>The value of variable 88 can only be tested with the GRFID tests.</ref>
−
|09||89|| ||W||{{ottdp|0.6| }}|| date fraction, incremented by 0x375 every engine tick
  
 
|-
  
|-
−
|0A||8A|| ||W||{{ottdp|0.6| }}|| animation counter, incremented every tick
 +
|09||89|| ||W||{{ottdp|0.6|2.0}}|| date fraction, incremented by 0x375 every engine tick
 
|-
  
|-
  +
|0A||8A|| ||W||{{ottdp|0.6|2.0}}|| animation counter, incremented every tick
−
|0B||8B|| ||D||{{ottdp|no| }}|| TTDPatch version, see below <ref>OpenTTD reports some arbitrary TTDPatch 2.6 version number to make old GRFs work, which do not know about OpenTTD. Do not rely on this for new NewGRFs.</ref>
  
 
|-
  
|-
  +
|0B||8B|| ||D||{{ottdp|no|2.0}}|| [[Version_numbers#TTDPatch_version|TTDPatch version]], see [[#TTDPatch_Version_.280B_.2F_8B.29|below]] <ref>OpenTTD reports some arbitrary TTDPatch 2.6 version number to make old GRFs work, which do not know about OpenTTD. Do not rely on this for new NewGRFs.</ref><ref name="versionchecks">It is generally not useful to check version variables using Action 7. If you want to skip certain actions which are incompatible to some versions, you want to skip them during all loading stages. So, use Action 9.</ref>
−
|0C|| || ||W||{{ottdp|0.6| }}|| current [[Callbacks|callback]] ID (feature-specific), set to 00 when not in a callback
  
 
|-
  
|-
−
|0D||8D|| ||B||{{ottdp|0.6| }}|| TTD version, 0=DOS, 1=Windows
 +
|0C|| || ||W||{{ottdp|0.6|2.5}}|| current [[Callbacks|callback]] ID (feature-specific), set to 00 when not in a callback
 
|-
  
|-
−
|0E||8E||8E||B||{{ottdp|0.6| }}|| Y-Offset for train sprites
 +
|0D||8D|| ||B||{{ottdp|0.6|2.5}}|| TTD version, 0=DOS, 1=Windows
 
|-
  
|-
−
|0F||8F||8F||3*B||{{ottdp|0.6| }}|| Rail track type cost factors
 +
|0E||8E||8E||B||{{ottdp|0.6|2.5}}|| Y-Offset for train sprites
 
|-
  
|-
−
|10|| || ||D||{{ottdp|0.6| }}|| extra callback info 1, as described in the callback specs
 +
|0F||8F||8F||3*B||{{ottdp|0.6|2.5}}|| Rail track type cost factors
 
|-
  
|-
−
|11|| || ||B||{{ottdp|no| }}|| current rail tool type (for station callbacks)
 +
|10|| || ||D||{{ottdp|0.6|2.5}}|| Extra callback info 1, see [[#Extra_callback_info_.2810_.2F_-.29_and_.2818_.2F_-.29|below]].
 
|-
  
|-
−
|12||92|| ||B||{{ottdp|0.6| }}|| Game mode, 0 in title screen, 1 in game and 2 in editor
 +
|11|| || ||B||{{ottdp|no|2.5}}|| current rail tool type (for station callbacks)
  +
|-
  +
|12||92|| ||B||{{ottdp|0.6|2.5}}|| Game mode, 0 in title screen, 1 in game and 2 in editor
 
|-
  
|-
 
|13||93||93||W||{{ottdp|no|2.5|ttdprev=2.0.1 alpha 39}}|| Tile refresh offset to left <ref name="tilefresh">See [[ActionD#Tile+refresh+offsets|Action D]] for more details on tile refresh offsets and their use.</ref>
  
|13||93||93||W||{{ottdp|no|2.5|ttdprev=2.0.1 alpha 39}}|| Tile refresh offset to left <ref name="tilefresh">See [[ActionD#Tile+refresh+offsets|Action D]] for more details on tile refresh offsets and their use.</ref>
Line 52: Line 54:
 
|16||96||96||W||{{ottdp|no|2.5|ttdprev=2.0.1 alpha 39}}|| Tile refresh offset downwards <ref name="tilefresh"/>
  
|16||96||96||W||{{ottdp|no|2.5|ttdprev=2.0.1 alpha 39}}|| Tile refresh offset downwards <ref name="tilefresh"/>
 
|-
  
|-
−
| ||97||97||B||{{ottdp|no| }}|| Fixed snow line height <ref>This variable is a deprecated way to set the snow line height via NewGRFs using [[ActionD]]. It is superseded by the [[Action0/Global_Variables#Snow_line_height_table_.2810.29 | Action 0 snow line height table]]. To read the current snow line with [[VariationalAction2 | VarAct2]] in a running game, use variable 20 instead.</ref>
 +
| ||97||97||B||{{ottdp|no|2.5}}|| Fixed snow line height <ref>This variable is a deprecated way to set the snow line height via NewGRFs using [[ActionD]]. It is superseded by the [[Action0/Global Settings#Snow_line_height_table_.2810.29 | Action 0 snow line height table]]. To read the current snow line with [[VariationalAction2 | VarAct2]] in a running game, use variable 20 instead.</ref><ref name="heightlevel">{{grfTill|7}} For GRF version 7 and below these variable are multiples of 8; {{grfFrom|8}} for GRF version 8 and above they directly state the heightlevel as multiple of 1.</ref>
 
|-
  
|-
−
|18|| || ||D||{{ottdp|0.6| }}|| extra callback info 2, as described in the callback specs
 +
|18|| || ||D||{{ottdp|0.6|2.5}}|| Extra callback info 2, see [[#Extra_callback_info_.2810_.2F_-.29_and_.2818_.2F_-.29|below]].
 
|-
  
|-
−
| ||99||99||D||{{ottdp|no| }}|| Global ID offset
 +
| ||99||99||D||{{ottdp|no|2.5}}|| Global ID offset
 
|-
  
|-
−
|1A||9A|| ||D||{{ottdp|0.6| }}|| Has always all bits set; you can use this to make unconditional jumps
 +
|1A||9A|| ||D||{{ottdp|0.6|2.5}}|| Has always all bits set; you can use this to make unconditional jumps
 
|-
  
|-
−
|1B|| || ||B||{{ottdp|no| }}|| display options; bit 0=town names, 1=station names, 2=signs, 3=animation, 4=transparency, 5=full detail
 +
|1B|| || ||B||{{ottdp|no|2.5}}|| display options; bit 0=town names, 1=station names, 2=signs, 3=animation, 4=transparency, 5=full detail
 
|-
  
|-
−
|1C|| || ||D||{{ottdp|0.6| }}|| result from most recent VarAction2
 +
|1C|| || ||D||{{ottdp|0.6|2.5}}|| result from most recent VarAction2
 
|-
  
|-
−
|1D||9D|| ||D||{{ottdp|0.6| }}|| TTD Platform, 0=TTDPatch, 1=OpenTTD
 +
|1D||9D|| ||D||{{ottdp|0.6|2.5}}|| TTD Platform, 0=TTDPatch, 1=OpenTTD <ref name="versionchecks"/>
 
|-
  
|-
−
|1E||9E||9E||D||{{ottdp|0.6| }}|| Misc. GRF Features
 +
|1E||9E||9E||D||{{ottdp|0.6|2.5}}|| Misc. GRF Features
 
|-
  
|-
−
| || ||9F||D||{{ottdp|no| }}|| writable only: Locale-dependent settings
 +
| || ||9F||D||{{ottdp|no|2.5}}|| writable only: Locale-dependent settings
 
|-
  
|-
−
|20|| || ||B||{{ottdp|0.6| }}|| Current snow line height, FFh if snow isn't present at all
 +
|20|| || ||B||{{ottdp|0.6|2.5}}|| Current snow line height, FFh if snow isn't present at all <ref name="heightlevel"/>
 
|-
  
|-
−
|21||A1|| ||D||{{ottdp|0.6|no}}|| OpenTTD version, see below.
 +
|21||A1|| ||D||{{ottdp|0.6|no}}|| [[Version_numbers#OpenTTD_version|OpenTTD version]], see [[#OpenTTD_Version_.2821_.2F_A1.29|below]]. <ref name="versionchecks"/>
 
|-
  
|-
−
|22||A2|| ||D||{{ottdp|0.7| |ottdrev=r12499|ttdprev=r1857}}|| Difficulty level: 00= easy, 01=medium, 02=hard, 03=custom
 +
|22||A2|| ||D||{{ottdp|0.7|2.6|ottdrev=r12499|ttdprev=r1857}}|| Difficulty level: 00= easy, 01=medium, 02=hard, 03=custom
 
|-
  
|-
 
|23||A3|| ||D||{{ottdp|0.7|2.6|ottdrev=r13376|ttdpref=r2048}}|| Current date long format
  
|23||A3|| ||D||{{ottdp|0.7|2.6|ottdrev=r13376|ttdpref=r2048}}|| Current date long format
Line 88: Line 90:
   
 
== Special variables ==
  
== Special variables ==
−  
−
=== Display options (1B / -) ===
  
−
The definition of variable 1B is slightly feature-dependent. For features that can be drawn transparently (stations, bridges, houses, industry tiles and objects) bit 4 is set if the current feature will be drawn normally, and clear if the current feature will be drawn transparently. For these purposes, airports are stations. For all other features, bit 4 is undefined.
  
   
 
=== GRF Loading stage (- / 84) ===
  
=== GRF Loading stage (- / 84) ===
Line 96: Line 95:
 
Variable 84 is a BYTE variable up to TTDPatch 2.5r1220. Its lower byte (bits 0..7) are 0 for the post-load and GRF initialization stages and 01 for all other stages. The remaining bits are a bitmask, and including the lower byte have the following meaning:
  
Variable 84 is a BYTE variable up to TTDPatch 2.5r1220. Its lower byte (bits 0..7) are 0 for the post-load and GRF initialization stages and 01 for all other stages. The remaining bits are a bitmask, and including the lower byte have the following meaning:
 
{|
  
{|
−
!Bit!!Meaning
 +
!Bit!!Version!!Meaning
  +
|-
  +
|0||{{ottdp|0.6|2.0}}||Set after the "Initialization" stage completes
 
|-
  
|-
  +
|1..7||{{ottdp|0.6|2.0}}||Always clear
−
|0||Set after the "Initialization" stage completes
  
 
|-
  
|-
  +
|8||{{ottdp|0.6|2.5|ttdprev=r1220}}||Set during the "Reserve" stage only
−
|1..7||Always clear
  
 
|-
  
|-
−
|8||Set during the "Reserve" stage only
 +
|9||{{ottdp|0.6|2.5|ttdprev=r1220}}||Set during the "Activate" stage only
 
|-
  
|-
−
|9||Set during the "Activate" stage only
 +
|10||{{ottdp|0.6|2.5|ttdprev=r1220}}||Set during the "Test" stage only
 
|-
  
|-
  +
|11..15|| || Reserved. Do not test for them.
−
|10||Set during the "Test" stage only
  
 
|}
  
|}
   
Line 114: Line 115:
 
!Element!!Meaning!!Value
  
!Element!!Meaning!!Value
 
|-
  
|-
−
|MM||major||First number of the TTDPatch version
 +
|MM||major||First number of the [[Version_numbers#TTDPatch_version|TTDPatch version]]
 
|-
  
|-
 
|m||minor||Second number of the TTDPatch version
  
|m||minor||Second number of the TTDPatch version
Line 150: Line 151:
 
Since train sprites must normally have the same offsets on the map and in the depot view, they will appear either too low on the map or too high in the depot view. This variable moves all vehicles in the depot view down by this many pixels.
  
Since train sprites must normally have the same offsets on the map and in the depot view, they will appear either too low on the map or too high in the depot view. This variable moves all vehicles in the depot view down by this many pixels.
   
−
Since OpenTTD r16867 this variable works per grf file, that is: It only affects trains defined in the same grf.
 +
{{ottdp|1.0|no|ottdrev=r16867}} Since OpenTTD r16867 this variable works per grf file, that is: It only affects trains defined in the same grf.
   
 
=== Rail track type cost factors (0F / 8F) ===
  
=== Rail track type cost factors (0F / 8F) ===
Line 166: Line 167:
 
|-
  
|-
 
|08, 0D, 10||Regular, Electric, Monorail/Maglev||on
  
|08, 0D, 10||Regular, Electric, Monorail/Maglev||on
  +
|}
  +
  +
=== Extra callback info (10 / -) and (18 / -) ===
  +
These variables have callback specific meanings. They are described along the individual [[callbacks]].
  +
  +
Additionally they are used outside of callbacks for these special purposes:
  +
{| |-
  +
! [[Features|Feature]] !! Usage
  +
|-
  +
| Vehicles || Used to distinguish drawing of vehicles in the GUI or on the map. See [[Action2/Vehicles#Introduction|Action2]].
  +
|-
  +
| Stations || Used to compose station tiles with sprites from different Action-1-2-3 chains, or to draw custom foundations. See [[Action0/Stations#General_Flags_.2813.29|General station flags]] and [[AdvancedSpriteLayout]].
  +
|-
  +
| Railtypes || Used to distinguish between the type of tunnel portal or signal requested. See [[Action3/Railtypes#Tunnel_portal_overlay_.280A.29|Railtype tunnel portal overlay]] or [[Action3/Railtypes#Signal_sprites_.280B.29|Railtype signal sprites]] for details, respectively.
 
|}
  
|}
   
 
=== Tile refresh offsets (13,14,15,16 / 93,94,95,96) ===
  
=== Tile refresh offsets (13,14,15,16 / 93,94,95,96) ===
   
  +
These four variables belong to an experimental TTDPatch feature. However, their definition is based on an incomplete understanding of the drawing algorithm in TTD, so they actually do not achieve what they were meant to do. Consider this historic content.
−
These four offsets define the size and position of the rectangle refreshed when TTD decides to refresh a tile. The basis of the calculations is the pixel coordinate of the north corner of the tile.
  
   
  +
{{ottdp|no|2.5|ttdprev=2.0.1 alpha 39}}
−
After calculating it, TTD subtracts offset_left from it to get the x coordinate of the left edge, adds offset_right to get the x coordinate of the right edge, subtracts offset_up to get the y coordinate of the top edge and adds offset_down to get the y coordinate of the bottom edge. This results in refreshing (offset_left+offset_right)*(offset_up+offset_down) pixels. The default values of these variables are 31, 36, 122 and 32, respectively.
  
   
  +
''These four offsets define the size and position of the rectangle refreshed when TTD decides to refresh a tile. The basis of the calculations is the pixel coordinate of the north corner of the tile.''
−
Reading these values is not too useful, but you can modify them using action D as well, so your sprites that would exceed the original limits can still be redrawn and animated properly. Please note that TTD uses these values for every tile, so specifying too high values may slow the game down. Please also note that these variables are specified as dwords for technical reasons, but only the bottom word will be used.
  
   
  +
''After calculating it, TTD subtracts offset_left from it to get the x coordinate of the left edge, adds offset_right to get the x coordinate of the right edge, subtracts offset_up to get the y coordinate of the top edge and adds offset_down to get the y coordinate of the bottom edge. This results in refreshing (offset_left+offset_right)*(offset_up+offset_down) pixels. The default values of these variables are 31, 36, 122 and 32, respectively.''
−
Since these values are global to the entire game, you shouldn't just overwrite them with an action D. Instead, you should first check if they're big enough for you by using action 7, and skip your action D if they are. This way, the variables will be set to the maximal value needed, not just the value needed for the last grf in the list.
  
  +
  +
''Reading these values is not too useful, but you can modify them using action D as well, so your sprites that would exceed the original limits can still be redrawn and animated properly. Please note that TTD uses these values for every tile, so specifying too high values may slow the game down. Please also note that these variables are specified as dwords for technical reasons, but only the bottom word will be used.''
  +
  +
''Since these values are global to the entire game, you shouldn't just overwrite them with an action D. Instead, you should first check if they're big enough for you by using action 7, and skip your action D if they are. This way, the variables will be set to the maximal value needed, not just the value needed for the last grf in the list.''
   
 
=== Snow line height (- / 97) ===
  
=== Snow line height (- / 97) ===
   
−
This is only active if the tempsnowline switch is on. It defaults to FF (no snow) and 38 in the temperate and arctic climates, respectively. It must be set to a multiple of 8, which is one level of height difference.
 +
This is only active if the tempsnowline switch is on. It defaults to FF (no snow) and 38 (GRF version < 8) resp. 07 (GRF version >= 8) in the temperate and arctic climates, respectively.
  +
  +
{{grfTill|7}} For GRF version 7 and below it must be set to a multiple of 8, which is one level of height difference.
  +
  +
{{grfFrom|8}} For GRF version 8 and above the heightlevel is set directly as multiple of 1.
   
 
=== Global ID offset (- / 99) ===
  
=== Global ID offset (- / 99) ===
Line 203: Line 226:
 
|A||<tt><First-sprite></tt>
  
|A||<tt><First-sprite></tt>
 
|}
  
|}
  +
  +
=== Display options (1B / -) ===
  +
The definition of variable 1B is slightly feature-dependent. For features that can be drawn transparently (stations, bridges, houses, industry tiles and objects) bit 4 is set if the current feature will be drawn normally, and clear if the current feature will be drawn transparently. For these purposes, airports are stations. For all other features, bit 4 is undefined.
   
 
=== Misc. GRF Features (1E / 9E) ===
  
=== Misc. GRF Features (1E / 9E) ===
Line 212: Line 238:
   
 
|-
  
|-
−
|0||1||{{ottdp| | }}||Allow trees and fields in the desert
 +
|0||1||{{ottdp|no|2.5}}||Allow trees and fields in the desert
  +
|-
  +
|1||2||{{ottdp|0.6|2.5}}||Show pavement and lights in desert towns
 
|-
  
|-
−
|1||2||{{ottdp| | }}||Show pavement and lights in desert towns
 +
|2||4||{{ottdp|no|2.5}}||Fields have a height, using a 3D bounding box
 
|-
  
|-
  +
|3||8||{{ottdp|0.6|2.5}}||Display train vehicles with full width of 32 pixels in depot window (instead of 29 pixels)<ref>Since {{ottdp|1.0|no|ottdrev=r16867}} this flag works per grf file, that is: It only affects trains defined in the same GRF.</ref>
−
|2||4||{{ottdp| | }}||Fields have a height, using a 3D bounding box
  
 
|-
  
|-
  +
|4||10||{{ottdp|1.2|2.6|ottdrev=r23114|ttdprev=r821}}||Enable ambient sound effect callback 144
−
|3||8||{{ottdp| | }}||Display train vehicles with full width of 32 pixels in depot window (instead of 29 pixels)<ref>Since {{ottdp|1.0|no|ottdrev=r16867}} this flag works per grf file, that is: It only affects trains defined in the same GRF.</ref>
  
 
|-
  
|-
−
|4||10||{{ottdp| |2.6|ttdprev=r821}}||Enable ambient sound effect callback 144
 +
|5||20||{{ottdp|no|2.5/2.6|ttdprev=r1439, will be in yet unreleased 2.5 beta 10}}||Enable catenaries over the third track type (only with electrifiedrailway on)
 
|-
  
|-
−
|5||20||{{ottdp| |2.5|ttdprev=r1439 (beta 10)}}||Enable catenaries over the third track type (only with electrifiedrailway on)
 +
|6||40||{{ottdp|1.5|no|ottdrev=r27200}}||Enable usage of the second rocky tile set. (sprites 4042 to 4061)
 
|-
  
|-
−
|31||80000000||{{ottdp|no| }}||Only to be set by ttdpbase(w).grf for identification
 +
|31||80000000||{{ottdp|no|2.5}}||Only to be set by ttdpbase(w).grf for identification
 
|}
  
|}
   
Line 261: Line 289:
   
 
=== OpenTTD Version (21 / A1) ===
  
=== OpenTTD Version (21 / A1) ===
−
Variable A1 has the following format: Mmrbbbbb (though encoded in little endian as bb bb rb Mm). This variable has only a usefull meaning when variable 9D is 1 (OpenTTD). This variable can be used since OpenTTD r11330.
 +
Variable A1 has the following format: MmrSbbbb (though encoded in little endian as bb bb rS Mm). This variable has only a usefull meaning when variable 9D is 1 (OpenTTD). This variable can be used since OpenTTD r11330.
  +
  +
==== Format for OpenTTD &le; 1.8 ====
  +
{{ottd|&le;1.8}}
 
{|
  
{|
 
!Element!!Meaning!!Value
  
!Element!!Meaning!!Value
 
|-
  
|-
−
|M||major||First number of the OpenTTD version
 +
|M||major||First number of the [[Version_numbers#OpenTTD_version|OpenTTD version]]
 
|-
  
|-
 
|m||minor||Second number of the OpenTTD version
  
|m||minor||Second number of the OpenTTD version
Line 271: Line 302:
 
|r||revision||Third number of the OpenTTD version
  
|r||revision||Third number of the OpenTTD version
 
|-
  
|-
  +
|S||release||Flag for stable release: 80000h
−
|bbbbb||build||Subversion revision of a build leading towards a release. When a final release is done 80000h is set.
  
  +
|-
  +
|bbbb||build||SVN revision.
 
|}
  
|}
   
  +
==== Format for OpenTTD 1.9 to 1.11 ====
−
The presence of 80000h (bit 19 set) means that a release always has a higher version number than any builds leading to that release.
  
  +
{{ottd|1.9 - 1.11}} Since OpenTTD 1.9 there is no longer any SVN revision. The lower bits are unused, and should be masked.
   
  +
{|
−
Examples
  
  +
!Element!!Meaning!!Value
  +
|-
  +
|M||major||First number of the [[Version_numbers#OpenTTD_version|OpenTTD version]]
  +
|-
  +
|m||minor||Second number of the OpenTTD version
  +
|-
  +
|r||revision||Third number of the OpenTTD version
  +
|-
  +
|S||release||Flag for stable release: 80000h
  +
|-
  +
|bbbb||build||Reserved; mask bits to ignore them.
  +
|}
  +
  +
==== Format for OpenTTD &ge; 12 ====
  +
{{ottd|&ge;12}} The versioning of OpenTTD was changed, version 1.11 was followed by version 12.
  +
The upper bits Mm now specify the major version number.
  +
  +
{|
  +
!Element!!Meaning!!Value
  +
|-
  +
|Mm||major||First number of the [[Version_numbers#OpenTTD_version|OpenTTD version]] plus 16
  +
|-
  +
|r||revision||Second number of the OpenTTD version
  +
|-
  +
|S||release||Flag for stable release: 80000h
  +
|-
  +
|bbbb||build||Reserved; mask bits to ignore them.
  +
|}
  +
  +
==== Notes ====
  +
  +
* The presence of 80000h (bit 19 set) means that a release always has a higher version number than any builds leading to that release.
  +
* The offset "plus 16" in the version number since OpenTTD 12 ensures compatibility with the previous versioning schema. Version 0.11 is represented as 1Bh. The following version 12 is represented as (12 + 16) = 1Ch.
  +
  +
==== Examples ====
 
{|
  
{|
 
!Version!!Variable A1!!Elements
  
!Version!!Variable A1!!Elements
 
|-
  
|-
−
|0.6.0 r11330||06002C42||M=0, m=6, r=0, bbbbb=11330=2C42
 +
|0.6.0 r11330||06002C42||M=0, m=6, r=0, S=0, bbbb=11330=0x2C42
  +
|-
  +
|0.6.0 (release)||06080000||M=0, m=6, r=0, S=8, bbbb=0
  +
|-
  +
|1.11.0 (release)||1B08xxxx||M=1, m=11=0xB, r=0, S=8, bbbb=reserved
  +
|-
  +
|12.0 (release)||1C08xxxx||Mm=16+12=0x1C, r=0, S=8, bbbb=reserved
  +
|-
  +
|14.0 (alpha/nightly)||1E00xxxx||Mm=16+14=0x1E, r=0, S=0, bbbb=reserved
 
|-
  
|-
−
|0.6.0 (release)||06080000||M=0, m=6, r=0, bbbbb=0=80000 (due to release)
 +
|17.2 (release)||2128xxxx||Mm=16+17=0x21, r=2, S=8, bbbb=reserved
 
|}
  
|}

Latest revision as of 19:48, 27 June 2023

Overview

Variable Size Versions Description
VA2 A6/7/9/D
(read)		 ActD
(write)
00 80 W Supported by OpenTTD 0.60.6 Supported by TTDPatch 2.02.0 current date (counted as days from 1920)[1]
01 81 B Supported by OpenTTD 0.60.6 Supported by TTDPatch 2.02.0 Current year (count from 1920, max. 2175 even with eternalgame)[1]
02 82 B/D Supported by OpenTTD 0.60.6 Supported by TTDPatch 2.02.0 current month (0-11) in bits 0-7; the higher bytes contain unusable junk.[1]
Supported by OpenTTD 0.7 (r13594)0.7 Not supported by TTDPatch Since OpenTTD r13594 'day of month' (0-30) is stored in bits 8-12, bit 15 is set in leapyears and 'day of year'(0-364 resp. 365) is stored in bits 16-24. All other bits are reserved and should be masked.
03 83 B Supported by OpenTTD 0.60.6 Supported by TTDPatch 2.02.0 Current climate: 00 = temp, 01 = arctic, 02 = trop, 03 = toyland
84 D Supported by OpenTTD 0.60.6 Supported by TTDPatch 2.02.0 GRF loading stage, see below
85 B Supported by OpenTTD 0.60.6 Supported by TTDPatch 2.02.0 TTDPatch flags: only for bit tests
06 86 B Supported by OpenTTD 0.60.6 Supported by TTDPatch 2.02.0 Road traffic side: bit 4 clear=left, set=right; other bits are reserved and must be masked.
(87) (87) B Not supported by OpenTTD Not supported by TTDPatch No longer used since TTDPatch 2.0. (was width of "€" character)
88 4*B Supported by OpenTTD 0.60.6 Supported by TTDPatch 2.02.0 Checks specified GRFID (see condition-types)[2]
09 89 W Supported by OpenTTD 0.60.6 Supported by TTDPatch 2.02.0 date fraction, incremented by 0x375 every engine tick
0A 8A W Supported by OpenTTD 0.60.6 Supported by TTDPatch 2.02.0 animation counter, incremented every tick
0B 8B D Not supported by OpenTTD Supported by TTDPatch 2.02.0 TTDPatch version, see below [3][4]
0C W Supported by OpenTTD 0.60.6 Supported by TTDPatch 2.52.5 current callback ID (feature-specific), set to 00 when not in a callback
0D 8D B Supported by OpenTTD 0.60.6 Supported by TTDPatch 2.52.5 TTD version, 0=DOS, 1=Windows
0E 8E 8E B Supported by OpenTTD 0.60.6 Supported by TTDPatch 2.52.5 Y-Offset for train sprites
0F 8F 8F 3*B Supported by OpenTTD 0.60.6 Supported by TTDPatch 2.52.5 Rail track type cost factors
10 D Supported by OpenTTD 0.60.6 Supported by TTDPatch 2.52.5 Extra callback info 1, see below.
11 B Not supported by OpenTTD Supported by TTDPatch 2.52.5 current rail tool type (for station callbacks)
12 92 B Supported by OpenTTD 0.60.6 Supported by TTDPatch 2.52.5 Game mode, 0 in title screen, 1 in game and 2 in editor
13 93 93 W Not supported by OpenTTD Supported by TTDPatch 2.5 (2.0.1 alpha 39)2.5 Tile refresh offset to left [5]
14 94 94 W Not supported by OpenTTD Supported by TTDPatch 2.5 (2.0.1 alpha 39)2.5 Tile refresh offset to right [5]
15 95 95 W Not supported by OpenTTD Supported by TTDPatch 2.5 (2.0.1 alpha 39)2.5 Tile refresh offset upwards [5]
16 96 96 W Not supported by OpenTTD Supported by TTDPatch 2.5 (2.0.1 alpha 39)2.5 Tile refresh offset downwards [5]
97 97 B Not supported by OpenTTD Supported by TTDPatch 2.52.5 Fixed snow line height [6][7]
18 D Supported by OpenTTD 0.60.6 Supported by TTDPatch 2.52.5 Extra callback info 2, see below.
99 99 D Not supported by OpenTTD Supported by TTDPatch 2.52.5 Global ID offset
1A 9A D Supported by OpenTTD 0.60.6 Supported by TTDPatch 2.52.5 Has always all bits set; you can use this to make unconditional jumps
1B B Not supported by OpenTTD Supported by TTDPatch 2.52.5 display options; bit 0=town names, 1=station names, 2=signs, 3=animation, 4=transparency, 5=full detail
1C D Supported by OpenTTD 0.60.6 Supported by TTDPatch 2.52.5 result from most recent VarAction2
1D 9D D Supported by OpenTTD 0.60.6 Supported by TTDPatch 2.52.5 TTD Platform, 0=TTDPatch, 1=OpenTTD [4]
1E 9E 9E D Supported by OpenTTD 0.60.6 Supported by TTDPatch 2.52.5 Misc. GRF Features
9F D Not supported by OpenTTD Supported by TTDPatch 2.52.5 writable only: Locale-dependent settings
20 B Supported by OpenTTD 0.60.6 Supported by TTDPatch 2.52.5 Current snow line height, FFh if snow isn't present at all [7]
21 A1 D Supported by OpenTTD 0.60.6 Not supported by TTDPatch OpenTTD version, see below. [4]
22 A2 D Supported by OpenTTD 0.7 (r12499)0.7 Supported by TTDPatch 2.6 (r1857)2.6 Difficulty level: 00= easy, 01=medium, 02=hard, 03=custom
23 A3 D Supported by OpenTTD 0.7 (r13376)0.7 Supported by TTDPatch 2.62.6 Current date long format
24 A4 D Supported by OpenTTD 0.7 (r13376)0.7 Supported by TTDPatch 2.6 (r2048)2.6 Current year zero based
25 D Supported by OpenTTD 0.7 (r15739)0.7 Not supported by TTDPatch GRFID of the grf that contains the corresponding Action3. Useful when accessing the "related" object. Currently only supported for vehicles.

All other variable numbers are reserved and must not be used.

  1. ↑ 1.0 1.1 1.2 Supported by OpenTTD 0.70.7 Not supported by TTDPatch In multiplayer games OpenTTD doesn't report the current date and year to actions 6,7,9 and D, but the date and year the game was loaded. The reason lies in the fact that it was seen that use of this variable leads to desyncs in network games.
  2. ↑ The value of variable 88 can only be tested with the GRFID tests.
  3. ↑ OpenTTD reports some arbitrary TTDPatch 2.6 version number to make old GRFs work, which do not know about OpenTTD. Do not rely on this for new NewGRFs.
  4. ↑ 4.0 4.1 4.2 It is generally not useful to check version variables using Action 7. If you want to skip certain actions which are incompatible to some versions, you want to skip them during all loading stages. So, use Action 9.
  5. ↑ 5.0 5.1 5.2 5.3 See Action D for more details on tile refresh offsets and their use.
  6. ↑ This variable is a deprecated way to set the snow line height via NewGRFs using ActionD. It is superseded by the Action 0 snow line height table. To read the current snow line with VarAct2 in a running game, use variable 20 instead.
  7. ↑ 7.0 7.1 GRFv≤7 For GRF version 7 and below these variable are multiples of 8; GRFv≥8 for GRF version 8 and above they directly state the heightlevel as multiple of 1.

Special variables

GRF Loading stage (- / 84)

Variable 84 is a BYTE variable up to TTDPatch 2.5r1220. Its lower byte (bits 0..7) are 0 for the post-load and GRF initialization stages and 01 for all other stages. The remaining bits are a bitmask, and including the lower byte have the following meaning:

Bit Version Meaning
0 Supported by OpenTTD 0.60.6 Supported by TTDPatch 2.02.0 Set after the "Initialization" stage completes
1..7 Supported by OpenTTD 0.60.6 Supported by TTDPatch 2.02.0 Always clear
8 Supported by OpenTTD 0.60.6 Supported by TTDPatch 2.5 (r1220)2.5 Set during the "Reserve" stage only
9 Supported by OpenTTD 0.60.6 Supported by TTDPatch 2.5 (r1220)2.5 Set during the "Activate" stage only
10 Supported by OpenTTD 0.60.6 Supported by TTDPatch 2.5 (r1220)2.5 Set during the "Test" stage only
11..15 Reserved. Do not test for them.

TTDPatch Version (0B / 8B)

Variable 8B has the following format: MMmrbbbb (though encoded in little endian as bb bb mr MM)

Element Meaning Value
MM major First number of the TTDPatch version
m minor Second number of the TTDPatch version
r revision Third number of the TTDPatch version[1]
bbbb build Alpha/beta version number times ten (up to an including TTDPatch 2.5 beta 5), SVN revision (from TTDPatch 2.5 beta 5 r418 on)

Examples

Version Variable 8B Elements
1.9.1 alpha 50 019101F4 MM=01, m=9, r=1, bbbb=50*10=01F4
2.0 beta 4 02040028 MM=02, m=0, r=4[1], bbbb=4*10=0028
2.0 final 02070046 MM=02, m=0, r=7[1], bbbb=70=0046
2.0 rev 1 02070050 MM=02, m=0, r=7[1], bbbb=80=0050
2.0.1 alpha 3 020A001E MM=02, m=0, r=10[1], bbbb=3*10=001E
2.5 beta 2 02500014 MM=02, m=5, r=0, bbbb=2*10=0014
2.5 rev631 02500631 MM=02, m=5, r=0, bbbb=631=0631
  1. ↑ 1.0 1.1 1.2 1.3 1.4 For TTDPatch 2.0, r=7 and for TTDPatch 2.0.1 series, r=10 due to an oversight which used r=1..4 for TTDPatch 2.0 beta 1..4.

To detect versions from TTDPatch 2.5 rev419 and up correctly, check that var. 8B is 02500419 or higher, or replace 0419 with the actual required revision (using the revision number as hex digits). Because SVN revisions are shared with other patch branches, it is important to check the actual patch version as well as the SVN revision.

Y-Offset for train sprites (0E / 8E)

Since train sprites must normally have the same offsets on the map and in the depot view, they will appear either too low on the map or too high in the depot view. This variable moves all vehicles in the depot view down by this many pixels.

Supported by OpenTTD 1.0 (r16867)1.0 Not supported by TTDPatch Since OpenTTD r16867 this variable works per grf file, that is: It only affects trains defined in the same grf.

Rail track type cost factors (0F / 8F)

This variable is a collection of three bytes that are used as multipliers for track costs when the "trackcostdiff" switch is on. The value of 08 is the baseline value that is used by standard TTD.

The defaults are the following:

Values Track types Electrified railways setting
08, 10, 18 Regular, Monorail, Maglev off
08, 0D, 10 Regular, Electric, Monorail/Maglev on

Extra callback info (10 / -) and (18 / -)

These variables have callback specific meanings. They are described along the individual callbacks.

Additionally they are used outside of callbacks for these special purposes:

Feature Usage
Vehicles Used to distinguish drawing of vehicles in the GUI or on the map. See Action2.
Stations Used to compose station tiles with sprites from different Action-1-2-3 chains, or to draw custom foundations. See General station flags and AdvancedSpriteLayout.
Railtypes Used to distinguish between the type of tunnel portal or signal requested. See Railtype tunnel portal overlay or Railtype signal sprites for details, respectively.

Tile refresh offsets (13,14,15,16 / 93,94,95,96)

These four variables belong to an experimental TTDPatch feature. However, their definition is based on an incomplete understanding of the drawing algorithm in TTD, so they actually do not achieve what they were meant to do. Consider this historic content.

Not supported by OpenTTD Supported by TTDPatch 2.5 (2.0.1 alpha 39)2.5

These four offsets define the size and position of the rectangle refreshed when TTD decides to refresh a tile. The basis of the calculations is the pixel coordinate of the north corner of the tile.

After calculating it, TTD subtracts offset_left from it to get the x coordinate of the left edge, adds offset_right to get the x coordinate of the right edge, subtracts offset_up to get the y coordinate of the top edge and adds offset_down to get the y coordinate of the bottom edge. This results in refreshing (offset_left+offset_right)*(offset_up+offset_down) pixels. The default values of these variables are 31, 36, 122 and 32, respectively.

Reading these values is not too useful, but you can modify them using action D as well, so your sprites that would exceed the original limits can still be redrawn and animated properly. Please note that TTD uses these values for every tile, so specifying too high values may slow the game down. Please also note that these variables are specified as dwords for technical reasons, but only the bottom word will be used.

Since these values are global to the entire game, you shouldn't just overwrite them with an action D. Instead, you should first check if they're big enough for you by using action 7, and skip your action D if they are. This way, the variables will be set to the maximal value needed, not just the value needed for the last grf in the list.

Snow line height (- / 97)

This is only active if the tempsnowline switch is on. It defaults to FF (no snow) and 38 (GRF version < 8) resp. 07 (GRF version >= 8) in the temperate and arctic climates, respectively.

GRFv≤7 For GRF version 7 and below it must be set to a multiple of 8, which is one level of height difference.

GRFv≥8 For GRF version 8 and above the heightlevel is set directly as multiple of 1.

Global ID offset (- / 99)

Setting this variable will add the given value to all the relevant IDs in subsequent action 0, action 3 (except livery overrides), action 4 (except generic texts) and action A entries. This is a more convenient way of applying the result of a GRF resource request. Setting this variable applies only to the current .grf file only.

In detail, it affects the following elements:

Action Element modified
0 <Id> (i.e., not property numbers)
3 <Ids...> (i.e., not cargo types or cargo IDs, also not for livery overrides)
4 <Offset> (not for generic texts, though)
A <First-sprite>

Display options (1B / -)

The definition of variable 1B is slightly feature-dependent. For features that can be drawn transparently (stations, bridges, houses, industry tiles and objects) bit 4 is set if the current feature will be drawn normally, and clear if the current feature will be drawn transparently. For these purposes, airports are stations. For all other features, bit 4 is undefined.

Misc. GRF Features (1E / 9E)

This variable is a global bit mask of various patch features a grf file can enable. Please only set the bits using operation 08 (bitwise OR), or, if absolutely necessary, remove certain bits with operation 07 (bitwise AND). This ensures that you don't mess up the settings of other grf files.

Bit Value Version Feature
0 1 Not supported by OpenTTD Supported by TTDPatch 2.52.5 Allow trees and fields in the desert
1 2 Supported by OpenTTD 0.60.6 Supported by TTDPatch 2.52.5 Show pavement and lights in desert towns
2 4 Not supported by OpenTTD Supported by TTDPatch 2.52.5 Fields have a height, using a 3D bounding box
3 8 Supported by OpenTTD 0.60.6 Supported by TTDPatch 2.52.5 Display train vehicles with full width of 32 pixels in depot window (instead of 29 pixels)[1]
4 10 Supported by OpenTTD 1.2 (r23114)1.2 Supported by TTDPatch 2.6 (r821)2.6 Enable ambient sound effect callback 144
5 20 Not supported by OpenTTD Supported by TTDPatch 2.5/2.6 (r1439, will be in yet unreleased 2.5 beta 10)2.5/2.6 Enable catenaries over the third track type (only with electrifiedrailway on)
6 40 Supported by OpenTTD 1.5 (r27200)1.5 Not supported by TTDPatch Enable usage of the second rocky tile set. (sprites 4042 to 4061)
31 80000000 Not supported by OpenTTD Supported by TTDPatch 2.52.5 Only to be set by ttdpbase(w).grf for identification

Remarks:

  1. ↑ Since Supported by OpenTTD 1.0 (r16867)1.0 Not supported by TTDPatch this flag works per grf file, that is: It only affects trains defined in the same GRF.

Example code for setting bit 3: 

  24 * 9     0D 9E 08 9E FF 08 00 00 00

(Here, the first 08 indicates the bitwise OR operation, and 08 00 00 00 is the value to OR var.9E with.)

Locale-dependent settings (1F / 9F)

This variable is a doubleword in the format rrccmmll, where the meaning of the bytes is:

Byte Meaning
rr Reserved for future use, just put zero here for now
cc Default currency to be used when the game is first started. It can be larger than 5 to select one of the currencies added via morecurrencies. If this value is larger than 5 while morecurrencies is disabled, US dollars will be used instead.
mm Default measurement system to be used when the game is first started. 00h means the imperial system (miles), 01h means the metric system (kilometers), other values are forbidden.
ll Language ID. By setting this byte, you can override the default language ID and allow other GRFs to supply correctly localized texts. (The other GRF can check for this value in action 4s)

Reading this variable isn't reliable, so you must only write to it. Please also note that the cc and mm parts are considered only while loading the title screen for the first time, changing them later is ignored.

NOTE: This variable is reset after the initialization stage. Only changes during the activation stage are considered. This way, GRFs disabled in newgrf.cfg won't change the language and/or default settings. If you want to modify the cc or mm part, make sure the corresponding action D isn't skipped by an earlier action 7 or 9. In particular, if your GRF isn't available for the tropic climate, make sure you set variable 9F before the climate check, since the default title screen is tropic, and your climate check will fail on it.

OpenTTD Version (21 / A1)

Variable A1 has the following format: MmrSbbbb (though encoded in little endian as bb bb rS Mm). This variable has only a usefull meaning when variable 9D is 1 (OpenTTD). This variable can be used since OpenTTD r11330.

Format for OpenTTD ≤ 1.8

Supported by OpenTTD ≤1.8≤1.8

Element Meaning Value
M major First number of the OpenTTD version
m minor Second number of the OpenTTD version
r revision Third number of the OpenTTD version
S release Flag for stable release: 80000h
bbbb build SVN revision.

Format for OpenTTD 1.9 to 1.11

Supported by OpenTTD 1.9 - 1.111.9 - 1.11 Since OpenTTD 1.9 there is no longer any SVN revision. The lower bits are unused, and should be masked.

Element Meaning Value
M major First number of the OpenTTD version
m minor Second number of the OpenTTD version
r revision Third number of the OpenTTD version
S release Flag for stable release: 80000h
bbbb build Reserved; mask bits to ignore them.

Format for OpenTTD ≥ 12

Supported by OpenTTD ≥12≥12 The versioning of OpenTTD was changed, version 1.11 was followed by version 12. The upper bits Mm now specify the major version number.

Element Meaning Value
Mm major First number of the OpenTTD version plus 16
r revision Second number of the OpenTTD version
S release Flag for stable release: 80000h
bbbb build Reserved; mask bits to ignore them.

Notes

  • The presence of 80000h (bit 19 set) means that a release always has a higher version number than any builds leading to that release.
  • The offset "plus 16" in the version number since OpenTTD 12 ensures compatibility with the previous versioning schema. Version 0.11 is represented as 1Bh. The following version 12 is represented as (12 + 16) = 1Ch.

Examples

Version Variable A1 Elements
0.6.0 r11330 06002C42 M=0, m=6, r=0, S=0, bbbb=11330=0x2C42
0.6.0 (release) 06080000 M=0, m=6, r=0, S=8, bbbb=0
1.11.0 (release) 1B08xxxx M=1, m=11=0xB, r=0, S=8, bbbb=reserved
12.0 (release) 1C08xxxx Mm=16+12=0x1C, r=0, S=8, bbbb=reserved
14.0 (alpha/nightly) 1E00xxxx Mm=16+14=0x1E, r=0, S=0, bbbb=reserved
17.2 (release) 2128xxxx Mm=16+17=0x21, r=2, S=8, bbbb=reserved
Retrieved from ‘https://newgrf-specs.tt-wiki.net/index.php?title=GlobalVariables&oldid=4466’