VarAction2Advanced

Introduction

A regular action 2 can access one variable and perform limited modifications on it (shift, and, add, divide/modulo) instead of a simple variable access. 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 VarAction2 blocks in several places on the NFO code.

Format

An advanced VarAction2 looks as follows:

<Sprite-number> * <Length> 02 <feature> <set-id> <type> <variable> <varadjust> [<operator> <variable> <varadjust>]... <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	Version	Notes
00	\2+	result = val1 + val2	0.6 2.5
01	\2-	result = val1 - val2	0.6 2.5
02	\2<	result = min(val1, val2)	0.6 2.5	val1 and val2 are both considered signed
03	\2>	result = max(val1, val2)	0.6 2.5
04	\2u<	result = min(val1, val2)	0.6 2.5	val1 and val2 are both considered unsigned
05	\2u>	result = max(val1, val2)	0.6 2.5
06	\2/	result = val1 / val2	0.6 2.5	val1 and val2 are both considered signed
07	\2%	result = val1 mod val2	0.6 2.5
08	\2u/	result = val1 / val2	0.6 2.5	val1 and val2 are both considered unsigned
09	\2u%	result = val1 mod val2	0.6 2.5
0A	\2*	result = val1 * val2	0.6 2.5	result will be truncated to B/W/D (that makes it the same for signed/unsigned operands)
0B	\2&	result = val1 & val2	0.6 2.5	bitwise AND
0C	\2|	result = val1 | val2	0.6 2.5	bitwise OR
0D	\2^	result = val1 ^ val2	0.6 2.5	bitwise XOR
0E	\2s or \2sto	var7D[val2] = val1, result = val1	0.6 2.6	Store result. See Temporary storage.
0F	\2r or \2rst	result = val2	0.6 2.6
10	\2psto	var7C[val2] = val1, result = val1	0.6 2.6	Store result into persistent storage. See Persistent storage.
11	\2ror or \2rot	result = val1 rotate right val2	0.6 2.6	Always a 32-bit rotation.
12	\2cmp	see notes	0.6 2.6	Result is 0 if val1<val2, 1 if val1=val2 and 2 if val1>val2. Both values are considered signed.
13	\2ucmp	see notes	0.6 2.6	The same as 12, but operands are considered unsigned.
14	\2<<	result = val1 << val2	1.1 2.6	shift left; val2 should be in the range 0 to 31.
15	\2u>>	result = val1 >> val2	1.1 2.6	shift right (unsigned); val2 should be in the range 0 to 31.
16	\2>>	result = val1 >> val2	1.1 2.6	shift right (signed); val2 should be in the range 0 to 31.

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.

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.

Using types 81/82 (etc) simultaneously

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

This variable stores the result of the current VarAction2 and makes it available to the next VarAction2 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 VarAction2, 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 TTDPatch 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 VarAction2, 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 VarAction2 in both the <set-id> and <default> positions.

Using procedures

When the variable in a VarAction2 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 VarAction2 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, VarAction2s 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 VarAction2. It is however valid to use any type of VarAction2, 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.