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.

  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