# 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

Calculate the absolute value for the number -42.`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

Add two 3D points together.`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 }Add arbitrary numbers together.`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

Determine 0.1 + 0.2 is close to 0.3.`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

Calculate the average of a list of numbers.`const average = math.avg([4, 54.2, 31]);`

Calculate the average #age of all the bots.`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

Get the number of radians for a 90 degree angle`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

Calculate the anchor point offset for "bottom".`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

Get the direction that a pointer is pointing.`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

Create two random number generators with the same seed.`let random1 = math.getSeededRandomNumberGenerator(123);`

let random2 = math.getSeededRandomNumberGenerator(123);

os.toast(random1.randomInt(0, 10) + ' == ' + random2.randomInt(0, 10) + ' == 9');Create a random number generator and store it for later`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

Get the spot on the ground that a pointer is pointing at.`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

Negate a 3D point.`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

Normalize a 3D point.`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

Get the number of degrees for a Math.PI / 2 angle`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

Generate a random number between 0 and Math.PI.`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

Generate a random number between 5 and 10.`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

Scale a 3D point by 5.`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

Set the random seed for math.random() and math.randomInt().`math.setRandomSeed(123);`

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

expect(math.random()).toBe(0.36078753814001446);Clear the random seed.`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

Calculate the square root of 4.`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

Calculate the standard deviation of a list of numbers.`const standardDeviation = math.stdDev([2, 97, 745]);`

Calculate the standard deviation of the #age of all the bots.`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

Subtract two 3D points from each other.`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

Calculate the sum of a list of numbers.`const total = math.sum([92, 123, 21]);`

Calculate the total #age of all the bots.`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

Calculate the length of a 3D point`const result = math.vectorLength(`

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

);

os.toast(result); // 3.7416573867739413