====== Multiple return values ======

Some ACSUtils functions return multiple values (e.g. [[math#vector_math|vector math functions]], but also some non-math functions). ACS doesn't support returning multiple values from a function.

ACSUtils uses a convention to fake returning multiple values from a function. The convention is as follows: there are 8 global variables with names ''r1'' through ''r8''. If a function returns multiple values, it actually returns no value and writes the first "returned" value to ''r1'', the second one to ''r2'', and so on.

Here's an example, ''RotateVector'' returns X and Y:

<code>
RotateVector(x, y, angle);
int newX = r1;
int newY = r2;
</code>

<note warning>
You should retrieve the return values **as soon as possible**, or else they may get overwritten by other functions that return multiple values.

Don't do this:
<code>
SomeFunctionWithMultipleReturnValues(...);
SomeOtherFunction(r1);
int b = r2;
</code>
Because ''SomeOtherFunction'' may call functions that **overwrite ''r2''**! Instead, strictly follow this style:

<code>
SomeFunctionWithMultipleReturnValues(...);
int a = r1;
int b = r2;

SomeOtherFunction(a);
</code>
</note>

<note important>Another shortcoming is that ''r1''..''r8'' are declared ''raw'' in BCC to be able to accomodate any type of return value, and thus bypass [[strict typing]], even if it's enabled.

<code>
ParseFixed("1.0", 10);
int error = r1;
int result = r2; // no compiler error, despite assigning a fixed to int
</code>

</note>

But overwriting argument variables immediately after calling the function is valid:
<code>
RotateVector(x, y, angle);
x = r1;
y = r2;
</code>

An example of a function returning three values:
<code>
normalize3d(x, y, z);
int newX = r1;
int newY = r2;
int newZ = r3;
</code>