# ACSUtils Wiki

An ACS library for ZDoom-based ports

### Site Tools

new:math
• `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 