ACSUtils Wiki

Since some functions need to return a vector or a pair of angles, they use the ACSUtils multiple return values convention.

Functions returning one value:

• fixed VectorLength3D(fixed x, fixed y, fixed z) – a 3D version of VectorLength. Shorthand for VectorLength(z, VectorLength(x, y)).
• fixed SqVectorLength(fixed x, fixed y) – squared length of 2D vector.
• fixed SqVectorLength3D(fixed x, fixed y, fixed z) – squared length of 3D vector.
• fixed dot2(fixed x1, fixed y1, fixed x2, fixed y2) – dot product of two 2D vectors.
• fixed dot3(fixed x1, fixed y1, fixed z1, fixed x2, fixed y2, fixed z2) – dot product of two 3D vectors.

Functions returning two values:

• fixed, fixed normalize2d(fixed x, fixed y) – returns normalized 2D vector (same direction, but length 1.0)
• fixed, fixed VectorToAngles(fixed x, fixed y, fixed z) – converts vector to a pair of angles (angle and pitch)
• fixed, fixed RotateVector(fixed x, fixed y, fixed angle) – returns vector rotated by angle
• fixed, fixed RotateVectorCS(fixed x, fixed y, fixed rx, fixed ry) – returns vector rotated by another vector's angle. Result is multipled by the second vector's length. If the second vector is normalized, it's a (cos(angle), sin(angle)) vector of rotation angle.
• fixed, fixed RotatePoint(fixed x, fixed y, fixed originX, fixed originY, fixed angle) – returns 2D point rotated by angle around the origin.

Functions returning three values:

• fixed, fixed, fixed normalize3d(fixed x, fixed y, fixed z) – returns normalized 3D vector.
• fixed, fixed, fixed AnglesToVector(fixed angle, fixed pitch) – converts a pair of angles to a vector of length 1.

num mod(num x, num period) – just like x % period, but performs “true” modulo division, without negative results or mirrorings. It's as if you began at 0 in space [0, period) with wraparound, and moved X steps to the right.

Example of practical use of mod that wouldn't work with %:

int NUM_MENU_ITEMS = 10;
int selected_item = 0;

if (KeyPressed(BT_FORWARD))
    selected_item--;
if (KeyPressed(BT_BACK))
    selected_item++;
    
// wrap around
selected_item = mod(selected_item, NUM_MENU_ITEMS);

fixed lerp(fixed a, fixed b, fixed alpha)

Performs linear interpolation (or extrapolation) between two numbers and returns the result.

Simple animation of movement between two points:

for (int time = 0; time < 1.0; time += 0.05)
{
    int x = lerp(x1, x2, time); 
    int y = lerp(y1, y2, time);
    DrawSomething(x, y);
    Delay(1);
}