GlobalVariables

From GRFSpecs
Revision as of 21:31, 22 July 2011 by Planetmaker (talk | contribs) (Add more variable descriptions and rework table slightly)
Jump to navigationJump to search

Overview

Variable Size variables Description
81 B 2,7,9 Supported by OpenTTD 0.70.7 game load year(4); TTDPatch: current year (count from 1920, max. 2175 even with eternalgame)
83 B 2,7,9 Current climate: 00 = temp, 01 = arctic, 02 = trop, 03 = toyland
84 D 7,9 GRF loading stage, see below
85 B 7,9 TTDPatch flags: only for bit tests
86 B 2,7,9 Road traffic side: bit 4 clear=left, set=right
88 4*B 7,9 Checks specified GRFID (see condition-types below)
8B D 2,7,9 TTDPatch version, see below
8D B 2,7,9 TTD version, 0=DOS, 1=Windows
8E B 2,7,9,D Y-Offset for train sprites
8F 3*B 2,7,9,D Rail track type cost factors
92 B 2,7,9 Game mode, 0 in title screen, 1 in game and 2 in editor
93 W 7,9,D Not supported by OpenTTDTile refresh offset to left
94 W 7,9,D Not supported by OpenTTDTile refresh offset to right
95 W 7,9,D Not supported by OpenTTDTile refresh offset upwards
96 W 7,9,D Not supported by OpenTTDTile refresh offset downwards
97 B 2,D Snow line height
99 D D Global ID offset
9A D 2,7,9 Has always all bits set; you can use this to make unconditional jumps
9D D 2,7,9 TTD Platform, 0=TTDPatch, 1=OpenTTD
9E D 2,D Misc. GRF Features
9F D D TTDPatch only, writable only: Locale-dependent settings
A1 D 2,7,9 OpenTTD version, see below.
A2 D 2,7,9 Difficulty level: 00= easy, 01=medium, 02=hard, 03=custom, since r12449 for OpenTTD and r1857 for TTDPatch
A3 D 2,7,9 OpenTTD (since r13376): game load date long format(4); TTDPatch (since r2048): Current date long format
A4 D 2,7,9 OpenTTD (since r13376): game load year zero based(4); TTDPach (since r2048) current year zero based

Note: those variables which can be written in an ActionD are indicated by a bold D within the table

Note 1: All other parameter values greater than 80 (hexadecimal) are reserved and must not be used in action 7 or 9.

Note 2: The value of variable 88 can only be tested with the GRFID tests.

Note 3: The tile refresh offsets are available from TTDPatch 2.0.1 alpha 39. See Action D for more details on their use.

Note 4: OpenTTD doesn't report the current date and year 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.

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 Meaning
0 Set after the "Initialization" stage completes
1..7 Always clear
8 Set during the "Reserve" stage only
9 Set during the "Activate" stage only
10 Set during the "Test" stage only

TTDPatch Version (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*
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*, bbbb=4*10=0028
2.0 final 02070046 MM=02, m=0, r=7*, bbbb=70=0046
2.0 rev 1 02070050 MM=02, m=0, r=7*, bbbb=80=0050
2.0.1 alpha 3 020A001E MM=02, m=0, r=10*, 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

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

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

Tile refresh offsets (93, 94, 95, 96)

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 in the temperate and arctic climates, respectively. It must be set to a multiple of 8, which is one level of height difference.

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>

Misc. GRF Features (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 Feature Min. version
0 1 Allow trees and fields in the desert
1 2 Show pavement and lights in desert towns
2 4 Fields have a height, using a 3D bounding box
3 8 Display train vehicles with full width of 32 pixels in depot window (instead of 29 pixels) (a)
4 10 Enable ambient sound effect callback 144 TTDPatch 2.6 r821
5 20 Enable catenaries over the third track type (only with electrifiedrailway on) TTDPatch 2.6 r826, TTDPatch 2.5 r1439 (beta 10)
31 80000000 Only to be set by ttdpbase(w).grf for identification

(a) Since OpenTTD r16867 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 (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 (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.

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
bbbbb build Subversion revision of a build leading towards a release. When a final release is done 80000h is set.

The presence of 80000h (bit 19 set) means that a release always has a higher version number than any builds leading to that release.