VariationalAction2

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	Roadtypes
13	Tramtypes
14	Road Stops

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	0.6 2.5 W Access lowest word	0.6 2.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	Roadtypes	N/A
13	Tramtypes	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	0.7 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	-	1.1 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. 1.2  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	0.6 2.6	A special 60+x variable used to access values stored in the registers of persistent storage.
7D	D	0.6 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	0.6 2.5	A special 60+x variable indicating a procedure call. Available in the purchase list.
7F	D	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 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	0.6 2.0	number of bits to right shift <variable>
5	20	0.6 2.5	This is an advanced VarAction2
6	40	0.6 2.5	This is a shift-and-add-divide adjustment.
7	80	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).

0.6 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