Version: Current

# 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

``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

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.

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 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.

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 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.

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 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``