VarAction2Advanced

Advanced features of Variational Action 2

Advanced features of Variational Action 2

Using advanced calculations instead of simple variable access

-=Introduction=-

A regular action 2 can access one variable and perform limited modifications on it (shift, and, add, divide/modulo). Using an advanced action 2, it is possible to do a nearly unlimited number of many different operations on several variables.

In addition, using procedure calls (with variable 7E), it is possible to reuse variational action 2 blocks in several places on the NFO code.

-=Format=-

An advanced variational action 2 looks as follows:

 -+<Sprite-number> * <Length> 02 <feature> <set-id> <type> <variable> <varadjust> '''<nowiki>[<operator> <variable> <varadjust>]</nowiki>...''' <nvar> (<set-id> <low-range> <high-range>){n} <default>+-

The new elements are the <operator> (a byte), followed by another <variable> and <varadjust> pair.  This sequence may be repeated as often as necessary, by setting the appropriate bit in the previous <varadjust> (see below).

varadjust

<varadjust> itself has the same format as a regular var. action 2, however to perform a calculation, bit 5 in <shift-num> has to be set:

||Bit(s)|value|meaning

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

5|20|an <operator> <variable> <varadjust> triple follows this <varadjust>

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

7|80|This is a shift-and-add-modulo adjustment.||

Bit 5 needs to be set for each <shift-num>, except the last one that isn't going to be followed by another calculation (i.e., <operator> <variable> <varadjust> set). Bit 5 clear terminates the calculation and uses the resulting value for checking the ranges determining the set-id to use (or, if nvar=0, as a callback result).

operator

This field, and the following variable/varadjust pair, exist only if the previous shift-num had bit 5 set. This field has escape sequences for each of its valid values, as shown in the table below. See the discussion of escape sequences for further information on escape sequences in general. Can have the following values:

||Value|Escape|Effect|Notes

00|\2+|result = val1 + val2|

01|\2-|result = val1 - val2|

02|\2<|result = min(val1, val2)|val1 and val2 are both considered signed

03|\2>|result = max(val1, val2)|val1 and val2 are both considered signed

04,05|\2u<, \2u>|

-"-

|Same as 02/03, but operands are considered unsigned

06|\2/|result = val1 / val2|val1 and val2 are both considered signed

07|\2%|result = val1 mod val2|val1 and val2 are both considered signed

08,09|\2u/, \2u%|

-"-

|Same as 06/07, but operands are considered unsigned

0A|\2*|result = val1 * val2|result will be truncated to B/W/D (that makes it the same for signed/unsigned operands)

0B|\2&|result = val1 & val2|bitwise AND

0C|\2<nowiki>|</nowiki>|result = val1 <nowiki>|</nowiki> val2|bitwise OR

0D|\2<nowiki><pre></nowiki>|result = val1 <nowiki></pre></nowiki> val2|bitwise XOR

0E|\2s or \2sto (a)|var7D<nowiki>[val2]</nowiki> = val1, result = val1|Store result, available since 2.6 r1246. val2 must not exceed FF (before r1301) or 10F (starting from r1301) (*)

0F|\2r or \2rst (a)|result = val2|Available since 2.6 r1246

10|\2psto (c)|var7C<nowiki>[val2]</nowiki> = val1, result = val1|Store result into persistent storage, available since 2.6 r1315 (**)

11|\2ror or \2rot (b)|result = val1 rotate right val2|Always a 32-bit rotation. Available since 2.6 r1651

12|\2cmp (c)|see notes|Result is 0 if val1<val2, 1 if val1=val2 and 2 if val1>val2. Both values are considered signed. Available since 2.6 r1698 (***)

13|\2ucmp (c)|see notes|The same as 12, but operands are considered unsigned. Available since 2.6 r1698 (***)

14|\2<< (c)|result = val1 << val2|shift left; val2 should be in the range 0 to 31. Available since OpenTTD r20332 and TTDPatch r2335.

15|\2u>> (c)|result = val1 >> val2|shift right (unsigned); val2 should be in the range 0 to 31. Available since OpenTTD r20332 and TTDPatch r2335.

16|\2>> (c)|result = val1 >> val2|shift right (signed); val2 should be in the range 0 to 31. Available since OpenTTD r20332 and TTDPatch r2335.||

where val1 is the value resulting from the current variable/varadjust pair (or the result of the previous calculations if this isn't the first pair) and val2 is the value resulting from the following variable/varadjust pair. By setting bit 5 of shift-num repeatedly, you can combine several variables together before making your decision.

(a) Supported since grfcodec and nforenum r1265 (1.0.0 and 3.4.4, respectively.)

(b) Supported since grfcodec and nforenum r1655 (1.0.0 and 3.4.6, respectively.)

(c) Supported since grfcodec 1.0.0 and nforenum 4.0.0.

<nowiki>*</nowiki> Registers above FFh are write-only because you can't give a value bigger than FFh to var 7D. These registers are special; they allow passing extra data to some 4x and 6x variables, as well as returning extra data from callbacks.

<nowiki>**</nowiki> Currently only feature A (industries) is supported, you have 16 4-byte slots per industry. This storage can be reached from industry tiles as well by using var. action 2 type 82/86/8A. This operation shouldn't be used when the industry structure isn't available.

<nowiki>***</nowiki> Operations 12 and 13 should be preferred over operation 01 (subtraction) when only the relation of the two values is needed and the difference itself is irrelevant. This is because operation 01 can overflow and give the wrong sign if the difference is too big, but comparisons work correctly for all values.

Registers (temporary and persistent alike) always have the size of 4 bytes. If you're writing them using smaller sizes (anything but type 89/8A), the given value will be sign-extended to 4 bytes. Therefore, be careful when you read a register using a bigger size than it was written with. This also applies to registers read by TTDPatch; if not indicated specifically, TTDPatch reads all 4 bytes of the register.

Note that a bitwise NOT can be done by XORing with variable 1A. Similarly, you can specify literal values (i.e. plain numbers instead of variables), by using variable 1A and an and-mask of the value you want. For example, to specify a literal 26, use variable=1A, shift-num=00 (or the higher bits set if you need further calculations), and and-mask=26. This works with B, W or D sized literals if you use the right and-mask size for the given type of action 2. The appropriate \b, \w, or \d escape sequence can be useful for specifying literals. See the discussion of escape sequences for further information.

Operator 0F is only useful when using variable 7B, or immediately after operators 0E or 10, to store the result of a calculation, and then discard that result and start fresh.

Using types 81/82 (etc) simultaneously

Since 2.0.1 alpha 59, it is possible to access variables using both var.action 2 type 81 and 82 (and their W/D cousins) indirectly through the new variable 1C.

This variable stores the result of the current var.action 2 and makes it available to the next var.action 2 in the chain.  Therefore, to access, for instance when drawing a house, both house variables (type 81) and town variables (type 82), you would read the house variables in one var. action 2, type 81, and then chain to the next var.action 2, type 82.  There, you now have access to the house variable value stored in variable 1C as well as the town variables in the regular variables. Since 2.6 r1246, you may also store values in the 7D array, where they will persist for the life of the action 2 chain, unless overwritten.

Note that to chain to the next var.action 2, you must not use nvar=0, because that returns the result value as a callback result.  Instead, you need to use nvar=1, and specify the chained var.action 2 in both the <set-id> and <default> positions.

Using procedures

When the variable in a var.action 2 is 7E, the procedure given by the 60+x parameter is invoked. This means that the byte following the variable number (7E) specifies a variational or random action 2 ID to call, similarly to how a regular var.action 2 branches to other action 2 entries. However, instead of branching, it is a subroutine call, with the value calculated by the called entry being used as variable value.

The called action 2 must return a callback result. If the chain ends in a regular action 2 instead of returning a callback result, the variable 7E value is undefined.  Because callback results are limited to 15 bits, to access the full 32 bit result you can read variable 1C instead (e.g. by anding the 7E result with 0 and then adding var. 1C).

In TTDPatch 2.5 beta 9 and earlier and in TTDPatch 2.6 prior to r846, var.action 2s that attempt to perform multiple sequential (as opposed to nested) procedure calls will have undefined results.

The feature of this called action 2 is ignored, and all variables accessed use the same feature as the calling var.action 2. It is however valid to use any type of var.action 2, e.g. types 81 and 82 and the various byte/word/dword sizes may be mixed. It is also valid to use nvar=00 to return the computed value as callback result, instead of specifying ranges, although this way the return value is still limited to 15 bits. When using a random action 2 in the called chain, random triggers are processed in the same way as in "normal" chains.