fixed AngleDiff(fixed a, fixed b) – returns the shortest signed rotation angle needed to go from angle A to angle B. Result is always in [-0.5, 0.5]. Both A and B may be outside [0.0, 1.0].

num gcf(num a, num b) – returns the greatest common factor of two numbers.

Vector math

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

ZDoom GetActorPitch returns actor pitch with the wrong sign (multiplied by -1). Make sure to fix the sign before using actor pitch in the below vector functions.

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.

Other useful functions

mod

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);