DO - LOOP FUNCTION
RECEIVER

Calls a function trigger multiple times.( !?FU trigger)

EXTENDED DO RECEIVER SYNTAX. See below

!!DO#1/#2/#3/#4:XXXX; Calls a function trigger multiple times:
   #1 is number of function,
   #2 is start value
   #3 stop value
   #4 is step

OPTIONS

P$/$/$... 
up to
15#s.

Run function many times: P
To get access to parameters use x# (#=1...15) syntax.
They may be used anywhere (within the function) that standard variables are used.
When you call another function (see example), all parameters that are not set will be inherited.

Note: the :P parameter must be placed in the !!DO calling (even if no values are to be transfered to the loop) for the loop to work correctly.
Example:
!!DO1/1/15/1:P; is right
but !!DO1/1/15/1; is wrong command
All ERM commands (receivers, instructions) have to use at least one parameter in order to work correctly.

Comments:

The x16 variable (used in functions called with the DO Receiver), stores the current cycle number of the function. For example, if the function is being repeated 12 times (from 1 to 12), the first time through, x16 will equal 1, the second time 2 and so on. If you change the x16 variable, you can actually "speed up" or "slow down" a function loop, or even exit from it completely by setting x16 equal to the end value (or higher) that was specified in the DO receiver.
Now if you change x16 in the function you can speed up, slow down, repeat or end the cycle. Moreover, all parameters are only set when you first enter the function. Within the function, you may change them.

Example1:
!!DO1/2/10/2:P5;
...
!?FU1;
!!IF:M^Var x1=%X1 and x16=%X16^;
!!VRx1:+1; !!VRx16:+1;


It must show:
Var x1=5 and x16=2
Var x1=6 and x16=5
Var x1=7 and x16=8

 

Example2: Loop backwards, jumping 4 elements / loop (speeding up) , starting with 47

!!DO2/1/66/1:P47/11; [send  value 47 to the function's variable x1]

!?FU2;
!!VRv5:Sx1+1-x16; [do the loop backwards]
!!IF:M^the present value of x16 is %X16 and v5 is %V5^;
!!VRx16:+7; [set jump value to 8]

Instead of 66 loops you get only 9 loops, with these values:
x16:  1  9 17 25 33 41 49 57 65
v5:  47 39 31 23 15  7  -1 -9 -17

Other sugestions: The same can be done forwards. Also, the !!VRx16:+7; can be replaced (i.e.) with R7: "!!VRx16:R7";,  calculating a next random jump value up to 7, every jump, or (i.e.) with Rx2: "!!VRx16:Rx2", calculating  a random number up to x2, in this case x2 being 11 (!!DO2/1/66/1:P47/11;).

However, you have got to take care when asigning x16 a value, directly or through another variable. If this value is not within the loop extremes (in this case 1 and 66: !!DO2/1/66/1:P47/11;) the cycle breakes, meaning you end the loop prematurely.

Questions and answers:
Q: How is x16 effected by nested DOs?
A: Each DO loop keeps its own x16 value.

Q: Let's say I have the following code: (this would reflect, say, checking a 10x11 array for something)
!!DO1/1/10/1:P;

!?FU1;
!!DO2/20/30/1:P;
point A

!?FU2;
point B

My question is, at point B, will x16 have a value between 1 and 10, or between 20 and 30?

A:
20 and 30

Q: Also, at point A, will x16 have the value from DO1, or DO2?
A:
DO
1, because the line is inside FU1 function

A: (note) If you change the value of x16, that will change the loop. For example, if you set x16 to 999 (or even 50 in this case), that would end this loop as soon as it checks the x16 value (after it finishes one looping).

Q: I have a main loop covering all heroes (DO1/0/155/1), but for each hero I need to check through all creature slots (DO2/0/6/1). Would it work?
A:
That should work fine with a standard nested DO loop structure as far as I can tell.

NEW DO RECEIVER SYNTAX

FU and DO Receivers have extended syntax to provide return values.

  Now you may use "?var" syntax to return values from the call.
  You can use a v, y- or y variable to store the return value.
  Say:
!!FU...:Pv1/v2/v3/?v4;
  Now if you change x4 value inside of the function, say:
!!VRx4:Sx1;
  it will be copied to v4 after function return.

Comments:
  The value of the variable itself (v4) is not transferred to x4 at a function call. Instead the index of the var is transferred (so x4 will keep value 4).
  In DO loop the index value (4) will be passed at every iteration.
 So if you set it inside of the function body, it will be copied to the variable-receiver after the end of the iteration and restored to index value at the beginning of the next iteration.
  Also you may use "=var" syntax to set (parse) the value at every DO loop iteration (make no difference with standard "var" syntax for FU call).
  Say:
!!VRv35:S10;
!!DO...:P=v35;
  Now if you change the v35 inside of the loop body it will be passed to the next iteration taking account changes made for v35: !!VRv35:Sx1+1;
  So now it gives you x1 equal 10,11,12,13... at every iteration.
  If you use the standard syntax:
!!VRv35:S10;
!!DO...:Pv35;
  you will have x1 = 10,10,10,... at every iteration.

Comments:
  You may use any number of such variables in the call.
  You may use the same var (see example below) with ? and = syntax.
  Example 1:
!?FU2;
!!VRx2:Sx2+17;
!!VRx3:Sx1+17;

!?FU1;
!!FU2:P13/?y-1/?y-2;

!#IF:M^%Y-1,%Y-2^;
!#FU1:P;
!#IF:M^%Y-1,%Y-2^;

  You will see "0,0" and then "16,30".

  Example 2:
!?FU2;
!!VRx2:Sx1+17;
!!IF:M^x=%X1^;

!?FU1;
!!VRy-1:S33;
!!DO2/1/20/1:P=y-1/?y-1;

!#FU1:P;


You will see 33,50,67...