# Math Actions

`math.abs(number: any): number`

Calculates the absolute value of the given number. That is, the number without its sign.

The **first parameter** is a any and is the number that the absolute value should be calculated for.

#### Examples

`const _42 = math.abs(-42);`

`math.addVectors(...vectors: T[]): T`

Mathematically adds the given vectors to each other and returns the sum result.

A vector is a group of numbers which represents a specific point in 2D/3D/4D/etc. space.
For example, the vector `{ x: 1, y: 2, z: 3 }`

represents the point `(1, 2, 3)`

in 3D space where `x`

, `y`

, and `z`

are the names of the dimensions (or axes).

**Each parameter** is a T and are the vectors that should be added together.

#### Examples

`const result = math.addVectors(`

{ x: 1, y: 2, z: 3 },

{ x: 5, y: 6, z: 7 }

);

os.toast(result); // { x: 6, y: 8, z: 10 }

`const result = math.addVectors(`

{ salary: 1000, tax: 50 },

{ salary: 5000, tax: 250 },

{ salary: 750, tax: 37.5 },

);

os.toast(result); // { salary: 6750, tax: 337.5 }

`math.areClose(first: number, second: number): boolean`

Determines if the given numbers are within 2 decimal places of each other.

Because JavaScript numbers have limited precision, some calculations cannot be represented like they can in normal math.
For example, `1/3`

is `0.3333...`

but in JavaScript `1/3`

gives `0.33333333333333331483`

.
This inaccuracy can cause problems when many calculations are done, which can cause numbers that appear to be the same to actually be different.

The solution is to check the difference between two numbers to see if it is below some arbitrary threshold.
In this case, the threshold is `0.005`

.

The **first parameter** is a number and is the first number to check.

The **second parameter** is a number and is the second number to check.

#### Examples

`const first = 0.1 + 0.2;`

const second = 0.3;

const result = math.areClose(first, second);

const areEqual = first === second;

os.toast("Equal: " + areEqual + ", Close: " + result); // Equal: false, Close: true

`math.avg(list: any): number`

Calculates the arithmetic mean of the given list of values. That is, the sum of the values divided by the number of values.

The **first parameter** is a any and is the value that should be averaged.
If it is a list, then the result will be sum(list)/list.length.
If it is not a list, then the result will be the value converted to a number.

#### Examples

`const average = math.avg([4, 54.2, 31]);`

`const averageAge = math.avg(getBotTagValues('#age'));`

`math.degreesToRadians(degrees: number): number`

Converts the given number of degrees to radians and returns the result.

This operation is equivalent to `radians = degrees * (Math.PI / 180)`

.

The **first parameter** is a number and is the number of degrees that should be converted to radians.

#### Examples

`const radians = math.degreesToRadians(90);`

`math.getAnchorPointOffset(anchorPoint: BotAnchorPoint): Vector3`

Calculates the 3D position offset for the given anchor point and returns it.
This is essentially `experiment.getAnchorPointPosition(bot, dimension, anchorPoint)`

but without the bot's position/scale applied.

The **first parameter** is a BotAnchorPoint and is the anchor point that should be calculated. Can be any valid
`#anchorPoint`

value.

#### Examples

`const offset = math.getAnchorPointOffset("bottom");`

os.toast(offset);

`math.getForwardDirection(pointerRotation: (Rotation | object)): Vector3`

Gets the forward direction for the given rotation.

Useful for finding where a bot would be pointing if it has a custom rotation.

The **first parameter** is a (Rotation | object) and is the rotation that the pointer has represented in radians.

#### Examples

`const pointerRotation = os.getPointerRotation('mouse');`

const pointerDirection = math.getForwardDirection(pointerRotation);

os.toast(pointerDirection);

`math.getSeededRandomNumberGenerator(seed?: (string | number)): PseudoRandomNumberGenerator`

Creates a new random number generator from the given seed and returns it. Because of how random number generators work, generators created with the same seed will return the same sequence of random numbers.

The **first parameter** is optional and is a (string | number) and is the number or string that should be used as the seed value for the random number generator.
If omitted, then a seed will be chosen in a somewhat unpredictable manner.

#### Examples

`let random1 = math.getSeededRandomNumberGenerator(123);`

let random2 = math.getSeededRandomNumberGenerator(123);

os.toast(random1.randomInt(0, 10) + ' == ' + random2.randomInt(0, 10) + ' == 9');

`let randomNumberGenerator = math.getSeededRandomNumberGenerator(123);`

// Store it in the bot variables so it can be used in other scripts.

bot.vars.randomNumberGenerator = randomNumberGenerator;

`math.intersectPlane(origin: object, direction: object, planeNormal?: object, planeOrigin?: object): Vector3`

Calculates the 3D point that a ray starting at the given origin point and traveling in the given direction intersects the grid portal ground plane. Returns null if the ray does not intersect the ground plane.

Useful for calculating where on the ground something is pointing.

The **first parameter** is a object and is the 3D point that the ray should start at.

The **second parameter** is a object and is the direction that the ray is traveling along.

The **third parameter** is optional and is a object and is the normal vector that the plane should use.
For 2D planes, the normal vector is the 3D direction that is perpendicular to the the surface of the plane.
For example, a plane that covers the entire XY surface has a normal vector equal to
`➡️0,0,1`

, while a plane that covers the YZ surface has a normal vector equal to
`➡️1,0,0`

.
This parameter defaults to
`➡️0,0,1`

.

The **fourth parameter** is optional and is a object and is the 3D position that the center of the plane should travel through. Defaults to
`➡️0,0,0`

.

#### Examples

`const pointerPosition = os.getPointerPosition('mouse');`

const pointerRotation = os.getPointerRotation('mouse');

const pointerDirection = math.getForwardDirection(pointerRotation);

const groundPoint = math.intersectPlane(pointerPosition, pointerDirection);

os.toast(groundPoint);

`math.negateVector(vector: T): T`

Mathematically negates the given vector and returns the result.

A vector is a group of numbers which represents a specific point in 2D/3D/4D/etc. space.
For example, the vector `{ x: 1, y: 2, z: 3 }`

represents the point `(1, 2, 3)`

in 3D space where `x`

, `y`

, and `z`

are the names of the dimensions (or axes).

The **first parameter** is a T and is the vector that should be negated.

#### Examples

`const result = math.negateVector(`

{ x: 5, y: 6, z: 7 }

);

os.toast(result); // { x: -5, y: -6, z: -7 }

`math.normalizeVector(vector: T): T`

Normalizes the given vector. The result is a vector that has the same direction as the given vector but has a length/magnitude of 1.

Mathemematically, this is the same as finding the `math.vectorLength(vector)`

and dividing each component in the vector by it.

A vector is a group of numbers which represents a specific point in 2D/3D/4D/etc. space.
For example, the vector `{ x: 1, y: 2, z: 3 }`

represents the point `(1, 2, 3)`

in 3D space where `x`

, `y`

, and `z`

are the names of the dimensions (or axes).

The **first parameter** is a T and is the vector that should be normalized.

#### Examples

`const result = math.normalizeVector(`

{ x: 1, y: 2, z: 3 }

);

os.toast(result);

// x: 0.2672612419124244

// y: 0.5345224838248488

// z: 0.8017837257372732

`math.radiansToDegrees(radians: number): number`

Converts the given number of radians to degrees and returns the result.

This operation is equivalent to `degrees = radians * (180 / Math.PI)`

.

The **first parameter** is a number and is the number of radians that should be converted to degrees.

#### Examples

`const degrees = math.radiansToDegrees(Math.PI / 2);`

`math.random(min: number, max?: number): number`

Generates a random number between the given minimum and maximum values.

The **first parameter** is a number and is the smallest allowed value.

The **second parameter** is optional and is a number and is the largest allowed value.

#### Examples

`const number = math.random(0, Math.PI);`

`math.randomInt(min: number, max?: number): number`

Generates a random integer number between the given minimum and maximum values.

The **first parameter** is a number and is the smallest allowed value.

The **second parameter** is optional and is a number and is the largest allowed value.

#### Examples

`const number = math.randomInt(5, 10);`

`math.scaleVector(vector: T, scale: number): T`

Multiplies each property of the given vector by the given scale and returns the result.

`{ x: 1, y: 2, z: 3 }`

represents the point `(1, 2, 3)`

in 3D space where `x`

, `y`

, and `z`

are the names of the dimensions (or axes).

The **first parameter** is a T and is the vector that should be scaled.

The **second parameter** is a number and is the number that the vector should be multiplied by.

#### Examples

`const result = math.scaleVector(`

{ x: 5, y: 6, z: 7 },

5

);

os.toast(result); // { x: 25, y: 30, z: 35 }

`math.setRandomSeed(seed: (string | number)): void`

Sets the seed that should be used for the random numbers generated with `math.randomInt(min, max)`

and `math.random(min, max)`

.

The **first parameter** is a (string | number) and is the number or string that should be used as the seed value for the internal random number generator.
If null is provided, then a seed will be chosen in a somewhat unpredictable manner.

#### Examples

`math.setRandomSeed(123);`

expect(math.randomInt(0, 10)).toBe(9);

expect(math.random()).toBe(0.36078753814001446);

`math.setRandomSeed(null);`

`math.sqrt(value: any): number`

Calculates the square root of the given value.

The **first parameter** is a any and is the value that the square root should be calculated for.

#### Examples

`const rootOf4 = math.sqrt(4);`

`math.stdDev(list: any): number`

Calculates the [standard deviation](https://en.wikipedia.org/wiki/Standard_deviation for the given list of values.

The **first parameter** is a any and is the list of values that the standard deviation should be calculated for.

#### Examples

`const standardDeviation = math.stdDev([2, 97, 745]);`

`const ageDeviation = math.stdDev(getBotTagValues('#age'));`

`math.subtractVectors(...vectors: T[]): T`

Mathematically subtracts the given vectors from each other and returns the result.

`{ x: 1, y: 2, z: 3 }`

represents the point `(1, 2, 3)`

in 3D space where `x`

, `y`

, and `z`

are the names of the dimensions (or axes).

**Each parameter** is a T and are the vectors that should be subtracted from each other.

#### Examples

`const result = math.addVectors(`

{ x: 5, y: 6, z: 7 },

{ x: 1, y: 2, z: 3 },

);

os.toast(result); // { x: 4, y: 4, z: 4 }

`math.sum(list: any): number`

Calculates the numerical sum of the given values.

If any value in the list is not a number, it will be converted to one. If the given value is not an array, then it will be converted to a number and returned.

The **first parameter** is a any and is the list of values that should be summed up. If any value in the list is not a number, it will be converted to one.
If the list is not actually a list, then it will be converted to a number and returned.

#### Examples

`const total = math.sum([92, 123, 21]);`

`const totalAge = math.sum(getBotTagValues('#age'));`

`math.vectorLength(vector: T): number`

Calculates the length (i.e. magnitude) of the given vector.

Mathemematically, this is equivalent to `length = sqrt(sum(components.map(c => c * c)))`

. As a consequence, vectors that are normalized always have a length of 1.

`{ x: 1, y: 2, z: 3 }`

represents the point `(1, 2, 3)`

in 3D space where `x`

, `y`

, and `z`

are the names of the dimensions (or axes).

The **first parameter** is a T and is the vector to calculate the length of.

#### Examples

`const result = math.vectorLength(`

{ x: 1, y: 2, z: 3 }

);

os.toast(result); // 3.7416573867739413