VariationalAction2

From GRFSpecs
Jump to: navigation, search

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 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 feature that you wish to change. Set it to:

Value Feature
00 Trains
01 Road Vehicles
02 Ships
03 Aircraft
04 Stations
05 Canals/Rivers
06 Bridges
07 Houses
09 Industry Tiles
0A Industries
0B Cargos (no feature specific variables)
0C Sound Effects (no feature specific variables)
0D Airports
0E Signals
0F Objects
10 Railtypes
11 Airport Tiles
12 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
Access lowest byte
Supported by OpenTTD 0.60.6 Supported by TTDPatch 2.52.5 W
Access lowest word
Supported by OpenTTD 0.60.6 Supported by TTDPatch 2.52.5 D
Access lowest doubleword
Access general variable or
variable of the primary object
81 85 89
Access variable of "related" object 82 86 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.

Feature Related object
00-03 Vehicles First vehicle of consist
04 Stations Town to which station belongs
05 Canals/Rivers N/A
06 Bridges Town of bridge
07 Houses Town of house
09 Industry Tiles Industry containing tile
0A Industries Town of industry
0B Cargos N/A
0C Sound Effects N/A
0D Airports N/A
0E Signals N/A
0F Objects Town of object
10 Railtypes N/A
11 Airport Tiles N/A
12 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 Size Version Meaning
00-3F See global variables page.
40+x D specially calculated feature-specific variable, see following feature-specific pages
5F D Supported by OpenTTD 0.70.7 Supported by TTDPatch 2.6 (r1928)2.6 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 - Supported by OpenTTD 1.1 (r21604)1.1 Supported by TTDPatch 2.6 (r2359)2.6 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.

Supported by OpenTTD 1.2 (r23138)1.2 Not supported by TTDPatch 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 Supported by OpenTTD 0.60.6 Supported by TTDPatch 2.6 (r1315)2.6 A special 60+x variable used to access values stored in the registers of persistent storage.
7D D Supported by OpenTTD 0.60.6 Supported by TTDPatch 2.6 (r1246)2.6 A special 60+x variable used to access values stored in the registers of temporary storage. Available in the purchase list.
7E D Supported by OpenTTD 0.60.6 Supported by TTDPatch 2.52.5 A special 60+x variable indicating a procedure call. Available in the purchase list.
7F D Supported by OpenTTD 0.60.6 Supported by TTDPatch 2.52.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 savegame internals page.

varadjust

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

  <shift-num> <and-mask> [<add-val> <divide-val>/<modulo-val>]
Element 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 Supported by OpenTTD 0.60.6 Supported by TTDPatch 2.02.0 number of bits to right shift <variable>
5 20 Supported by OpenTTD 0.60.6 Supported by TTDPatch 2.52.5 This is an advanced VarAction2
6 40 Supported by OpenTTD 0.60.6 Supported by TTDPatch 2.52.5 This is a shift-and-add-divide adjustment.
7 80 Supported by OpenTTD 0.60.6 Supported by TTDPatch 2.52.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).

Supported by OpenTTD 0.60.6 Supported by TTDPatch 2.5 (2.0.1 alpha 57)2.5 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 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 the discussion of escape sequences for further information.

default

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

Example

 -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