VariationalAction2

Variational Action 2

Variational Action 2

Defining a choice between several action 2 entries

-=Introduction=-

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

A variational action 2 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 variational action 2, 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||

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.

-=Filling in the terms=-

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:

00 for trains

01 for road vehicles

02 for ships

03 for planes

04 for stations

05 for canals

06 for bridges

07 for houses

09 for industry tiles

0A for industries

0B for cargos

0E for signals

0F for objects

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

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.

Use 81/85/89 to decide upon a general variable, or a variable of the object in question.

Use 82/86/8A to refer to the "related" object:

||Feature|Related object

Vehicles (00-03)|First vehicle of consist

Stations (04)|Town to which station belongs

Canals (05)|N/A

Bridges (06)|Town of bridge

Houses (07)|Town of building

Generic (08)|(no action 2 support)

Industry tiles (09)|Industry containing tile

Industries (0A)|Town to which industry belongs

Cargos (0B)|N/A

Sounds (0C)|(no action 2 support)

Airports (0D)|Town of airport

Signals (0E)|N/A

Objects (0F)|N/A||

This number also tells what size the checked variable is:

For 81/82, the lowest byte of the value is accessed

For 85/86, the lowest word is accessed

For 89/8A, the lowest doubleword is accessed.

If the accessed variable is smaller than the size given here, the extra bits may contain junk, and should probably be <and-masked> out.

On this page, the size B/W/D means the field is byte-sized for types 81 and 82, word-sized for types 85 and 86, and doubleword-sized for types 89 and 8A.

Variable

Which variable to use for this decision. The following variables are always available:

||Number|Size|Meaning

00|W|current date (counted as days from 1920)

01|B|current year (count from 1920, max. 2175 even with eternalgame)

02|B/D|current month (0-11) in bits 0-7; the higher bytes contain unusable junk. Since OTTD 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|B|current climate, 0=temp, 1=arctic, 2=trop, 3=toyland

09|W|date fraction, incremented by 0x375 every engine tick

0A|W|animation counter, incremented every tick

0C|W|current callback ID (feature-specific), set to 00 when not in a callback

10|D|extra callback info 1, as described in the callback specs

11|B|current rail tool type (for station callbacks)

12|B|Game mode, 0 in title screen, 1 in game and 2 in editor

18|D|extra callback info 2, as described in the callback specs

1A|D|always -1 (that is, all bits are set). Useful to create constants (see VarAction2Advanced)

1B|B|display options; bit 0=town names, 1=station names, 2=signs, 3=animation, 4=transparency, 5=full detail

1C|D|result from most recent variational action 2

20|B|snow line height, FFh if snow isn't present at all

23|D|current date; long format, since OpenTTD r13376, 2.6 r2049

24|D|current year; long format, year zero based since OpenTTD r13376, 2.6 r2049

25|D|GrfID of the grf that contains the corresponding Action3. Useful when accessing the "related" object. Currently only supported for vehicles (OpenTTD r15739)

40+x|D|specially calculated feature-specific variable, see following feature-specific pages

5F|D|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. (2.5 r1927, 2.6 r1928)

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.

7C|D|A special 60+x variable that contains persistent data written by operator 10, for the features that support it. (The list of supported features can be found on that page.) Available since 2.6 r1315. Should not be read if the current feature doesn't support it. If the given slot hasn't been written yet, it contains zero.

7D|D|A special 60+x variable that contains up to 256 values stored by operator 0E. Available since 2.6 r1246. Available in the purchase list. These values are undefined unless written by a var2 earlier in the same chain.

7E|D|A special 60+x variable indicating a procedure call. Available in the purchase list.

7F|D|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||

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.

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 internals page.

{toc}

varadjust

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

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

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

0..4|0..1F|number of bits to right shift <variable>

5|20|This is an advanced var.action 2

6|40|This is a shift-and-add-divide adjustment.

7|80|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).

Since 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=-

Something to go here