Skip to main content
Version: Current

Vectors

  • Vector2​

    Defines a class that represents a 2D point in space.

    Members​

    • x number​

      The X value of this vector.

    • y number​

      The Y value of this vector.

    • constructor(x: number, y: number): Vector2​

      Constructs a new 2D vector with the given X and Y values.

      The first parameter is a number and is the X value of the vector.

      The second parameter is a number and is the Y value of the vector.

      Examples
      Create a new Vector2 object with the position (2, 3).
      let myVector = new Vector2(2, 3);

      os.toast(`X: ${myVector.x}, Y: ${myVector.y}`);
      Move this bot to (10, 15) in the home dimension.
      tags.homePosition = new Vector2(10, 15);

    • add(other: Vector2): Vector2​

      Adds this vector with the other vector and returns the result.

      The first parameter is a Vector2 and is the other vector to add with this vector.

      Examples
      Add two vectors together.
      const first = new Vector2(1, 2);
      const second = new Vector2(3, 4);
      const added = first.add(second);

      os.toast(added); // Prints (4, 6)

    • dot(other: Vector2): number​

      Calculates the dot product of this vector compared to the given other vector. Returns a number that is positive if the vectors point in the same direction, negative if they point in opposite directions, and zero if they are perpendicular. For normalized vectors, this value is clamped to 1 and -1.

      The first parameter is a Vector2 and is the other vector to calculate the dot product with.

      Examples
      Determine how two vectors are pointing towards/away from the same direction.
      const first = new Vector2(1, 2);
      const second = new Vector2(3, 4);

      const dot = first.dot(second);
      if (dot < 0) {
          os.toast("Vectors are pointing away from each other!");
      } else if (dot === 0) {
          os.toast("Vectors 90 degrees away from each other!");
      } else {
          os.toast("Vectors are pointing towards from each other!");
      }

    • equals(other: Vector2): boolean​

      Determines if this vector equals the other vector.

      The first parameter is a Vector2 and is the other vector.

      Examples
      Determine if two vectors represent the same value.
      const first = new Vector2(1, 2);
      const second = new Vector2(3, 4);
      const third = new Vector2(1, 2);

      os.toast(`first == second: ${first.equals(second)}; first == third: ${first.equals(third)}`)

    • length(): number​

      Calculates the length of this vector and returns the result.

      Examples
      Get the length of the vector.
      const myVector = new Vector2(1, 2);
      const length = myVector.length();

      os.toast(`Vector is ${length} units long`);

    • multiply(other: Vector2): Vector2​

      Multiplies this vector by the given other vector and returns the result.

      The first parameter is a Vector2 and is the other vector to multiply with this vector.

      Examples
      Multiply two vectors together.
      const first = new Vector2(1, 2);
      const second = new Vector2(3, 4);
      const multiplied = first.multiply(second);

      os.toast(multiplied); // Prints (3, 8)

    • multiplyScalar(scale: number): Vector2​

      Multiplies each component of this vector by the given value and returns the result.

      The first parameter is a number and is the scale that should be applied to this vector.

      Examples
      Scale a vector by 10.
      const myVector = new Vector2(1, 1);
      const scaled = myVector.multiplyScalar(10);
      os.toast(scaled); // Prints (10, 10)

    • negate(): Vector2​

      Negates each component of this vector and returns a new vector that contains the result.

      Examples
      Negate a vector.
      const myVector = new Vector2(1, 2);
      const negated = myVector.negate();

      os.toast(`Vector: ${myVector}, Negated: ${negated}`);

    • normalize(): Vector2​

      Calculates the normalized version of this vector and returns it. A normalized vector is a vector whose length equals 1.

      Normalizing a vector preserves its directionality while making the length (i.e. scale) of it 1.

      Examples
      Normalize a vector.
      const myVector = new Vector2(1, 2);
      const normalized = myVector.normalize();

      os.toast(`Vector: ${myVector}, Normalized: ${normalized}`);

    • squareLength(): number​

      Calculates the square length of this vector and returns the result. This is equivalent to length^2, but it is faster to calculate than length because it doesn't require calculating a square root.

      Examples
      Get the square length of the vector.
      const myVector = new Vector2(1, 2);
      const length = myVector.squareLength();

      os.toast(`Vector is ${length}^2 units long`);

    • subtract(other: Vector2): Vector2​

      Subtracts the other vector from this vector and returns the result.

      The first parameter is a Vector2 and is the other vector that should be subtracted from this vector.

      Examples
      Subtract two vectors.
      const first = new Vector2(1, 2);
      const second = new Vector2(3, 4);
      const subtracted = first.subtract(second);
      os.toast(subtracted);
      Find the direction from one vector to another.
      const first = new Vector2(1, 2);
      const second = new Vector2(3, 4);

      const directionFromFirstToSecond = second.subtract(first);
      const directionFromSecondToFirst = first.subtract(second);

      os.toast(`first -> second = ${directionFromFirstToSecond}; second -> first = ${directionFromSecondToFirst}`);

    • toString(): string​

      Converts this vector to a human-readable string representation.

      Examples
      Get a string of a vector.
      const myVector = new Vector2(1, 2);
      const vectorString = myVector.toString();

      os.toast('My Vector: ' + vectorString);

    • static angleBetween(first: Vector2, second: Vector2): number​

      Calculates the angle between the two given vectors and returns the result in radians.

      The first parameter is a Vector2 and is the first vector that should be used for comparision.

      The second parameter is a Vector2 and is the second vector that should be used for comparision.

      Examples
      Find the angle between two vectors.
      const first = new Vector2(
          Math.cos(Math.PI / 3),
          Math.sin(Math.PI / 3)
      ); // 60 degrees
      const second = new Vector2(
          Math.cos(Math.PI / 2),
          Math.sin(Math.PI / 2)
      ); // 90 degrees

      const angle = Vector2.angleBetween(first, second);
      os.toast(angle);

    • static createNormalized(x: number, y: number): Vector2​

      Creates a 2D vector with the given X and Y values that is normalized immediately upon creation.

      The first parameter is a number and is the X value of the vector.

      The second parameter is a number and is the Y value of the vector.

      Examples
      Create a normalized vector
      const vector = Vector2.createNormalized(1, 2);

    • static distanceBetween(first: Vector2, second: Vector2): number​

      Calculates the distance between the two given vectors and returns the result.

      The first parameter is a Vector2 and is the first vector that should be used for comparision.

      The second parameter is a Vector2 and is the second vector that should be used for comparision.

      Examples
      Find the distance between two vectors.
      const first = new Vector2(5, 10);
      const second = new Vector2(9, 2);
      const distance = Vector2.distanceBetween(first, second);

      os.toast(`Distance: ${distance}`);

    • static interpolateDirection(start: Vector2, finish: Vector2, amount: number): Vector2​

      Constructs a new vector that is the directional linear interpolation between the given start and end positions. The degree that the result is interpolated is determined by the given amount parameter.

      This function works similarly to interpolatePosition(), except the result is always a normalized vector.

      The first parameter is a Vector2 and is the start position.

      The second parameter is a Vector2 and is the end position.

      The third parameter is a number and is the amount that the resulting position should be interpolated between the start and end positions. Values near 0 indicate rotations close to the first and values near 1 indicate rotations close to the second.

      Examples
      Find the direction that points halfway between the two vectors.
      const start = new Vector2(5, 10);
      const finish = new Vector2(9, 2);
      const halfway = Vector2.interpolatePosition(start, finish, 0.5);

      os.toast(halfway);

    • static interpolatePosition(start: Vector2, finish: Vector2, amount: number): Vector2​

      Constructs a new vector that is the linear interpolation between the given start and end positions. The degree that the result is interpolated is determined by the given amount parameter.

      The first parameter is a Vector2 and is the start position.

      The second parameter is a Vector2 and is the end position.

      The third parameter is a number and is the amount that the resulting position should be interpolated between the start and end positions. Values near 0 indicate rotations close to the first and values near 1 indicate rotations close to the second.

      Examples
      Find the position that is halfway between two vectors.
      const start = new Vector2(5, 10);
      const finish = new Vector2(9, 2);
      const halfway = Vector2.interpolatePosition(start, finish, 0.5);

      os.toast(halfway);
      Find the position that is 1/4 between two vectors.
      const start = new Vector2(5, 10);
      const finish = new Vector2(9, 2);
      const halfway = Vector2.interpolatePosition(start, finish, 0.25);

      os.toast(halfway);

  • Vector3​

    Defines a class that represents a 3D point in space.

    Members​

    • x number​

      The X value of this vector.

    • y number​

      The Y value of this vector.

    • z number​

      The Z value of this vector.

    • xy Vector2​

    • xz Vector2​

    • yz Vector2​

    • constructor(x: number, y: number, z: number): Vector3​

      Constructs a new 3D vector with the given X and Y values.

      The first parameter is a number and is the X value of the vector.

      The second parameter is a number and is the Y value of the vector.

      The third parameter is a number and is the Z value of the vector.

      Examples
      Create a new Vector3 object with the position (2, 3, 4).
      let myVector = new Vector3(2, 3, 4);

      os.toast(`X: ${myVector.x}, Y: ${myVector.y}, Z: ${myVector.z}`);
      Move this bot to (1, 2, 3) in the home dimension.
      tags.homePosition = new Vector3(1, 2, 3);

    • add(other: Vector3): Vector3​

      Adds this vector with the other vector and returns the result.

      The first parameter is a Vector3 and is the other vector to add with this vector.

      Examples
      Add two vectors together.
      const first = new Vector3(1, 2, 3);
      const second = new Vector3(3, 4, 5);
      const added = first.add(second);

      os.toast(added); // Prints (4, 6, 8)

    • cross(other: Vector3): Vector3​

      Calculates the cross product of this vector with the given other vector. Returns a new vector that is perpendicular to both vectors. Note that the order of the vectors greatly matters. For example, (1, 0, 0).cross(0, 1, 0) === (0, 0, 1) but (0, 1, 0).cross(1, 0, 0) === (0, 0, -1).

      The first parameter is a Vector3 and is the other vector to calculate the cross product with.

      Examples
      Calculate a vector that is perpendicular to two vectors.
      const first = new Vector3(1, 0, 0);
      const second = new Vector3(0, 1, 0);

      const result = first.cross(second);
      os.toast(`Result: ${result}`); // Prints (0, 0, 1)

    • dot(other: Vector3): number​

      Calculates the dot product of this vector compared to the given other vector. Returns a number that is positive if the vectors point in the same direction, negative if they point in opposite directions, and zero if they are perpendicular. For normalized vectors, this value is clamped to 1 and -1.

      The first parameter is a Vector3 and is the other vector to calculate the dot product with.

      Examples
      Determine how two vectors are pointing towards/away from the same direction.
      const first = new Vector3(1, 2, 3);
      const second = new Vector3(3, 4, 5);

      const dot = first.dot(second);
      if (dot < 0) {
          os.toast("Vectors are pointing away from each other!");
      } else if (dot === 0) {
          os.toast("Vectors 90 degrees away from each other!");
      } else {
          os.toast("Vectors are pointing towards from each other!");
      }

    • equals(other: Vector3): boolean​

      Determines if this vector equals the other vector.

      The first parameter is a Vector3 and is the other value to compare to.

      Examples
      Determine if two vectors represent the same value.
      const first = new Vector3(1, 2, 3);
      const second = new Vector3(3, 4, 5);
      const third = new Vector3(1, 2, 3);

      os.toast(`first == second: ${first.equals(second)}; first == third: ${first.equals(third)}`)

    • length(): number​

      Calculates the length of this vector and returns the result.

      Examples
      Get the length of the vector.
      const myVector = new Vector3(1, 2, 3);
      const length = myVector.length();

      os.toast(`Vector is ${length} units long`);

    • multiply(other: Vector3): Vector3​

      Multiplies this vector by the given other vector and returns the result.

      The first parameter is a Vector3 and is the other vector to multiply with this vector.

      Examples
      Multiply two vectors together.
      const first = new Vector3(1, 2, 3);
      const second = new Vector3(3, 4, 5);
      const multiplied = first.multiply(second);

      os.toast(multiplied); // Prints (3, 8, 15)

    • multiplyScalar(scale: number): Vector3​

      Multiplies each component of this vector by the given value and returns the result.

      The first parameter is a number and is the scale that should be applied to this vector.

      Examples
      Scale a vector by 10.
      const myVector = new Vector3(1, 1, 1);
      const scaled = myVector.multiplyScalar(10);
      os.toast(scaled); // Prints (10, 10, 10)

    • negate(): Vector3​

      Negates each component of this vector and returns a new vector that contains the result.

      Examples
      Negate a vector.
      const myVector = new Vector3(1, 2, 3);
      const negated = myVector.negate();

      os.toast(`Vector: ${myVector}, Negated: ${negated}`);

    • normalize(): Vector3​

      Calculates the normalized version of this vector and returns it. A normalized vector is a vector whose length equals 1.

      Normalizing a vector preserves its directionality while making the length (i.e. scale) of it 1.

      Examples
      Normalize a vector.
      const myVector = new Vector3(1, 2, 3);
      const normalized = myVector.normalize();

      os.toast(`Vector: ${myVector}, Normalized: ${normalized}`);

    • squareLength(): number​

      Calculates the square length of this vector and returns the result. This is equivalent to length^2, but it is faster to calculate than length because it doesn't require calculating a square root.

      Examples
      Get the square length of the vector.
      const myVector = new Vector3(1, 2, 3);
      const length = myVector.squareLength();

      os.toast(`Vector is ${length}^2 units long`);

    • subtract(other: Vector3): Vector3​

      Subtracts the other vector from this vector and returns the result.

      The first parameter is a Vector3 and is the other vector that should be subtracted from this vector.

      Examples
      Subtract two vectors.
      const first = new Vector3(1, 2, 3);
      const second = new Vector3(3, 4, 5);
      const subtracted = first.subtract(second);
      os.toast(subtracted);
      Find the direction from one vector to another.
      const first = new Vector3(1, 2, 3);
      const second = new Vector3(3, 4, 5);

      const directionFromFirstToSecond = second.subtract(first);
      const directionFromSecondToFirst = first.subtract(second);

      os.toast(`first -> second = ${directionFromFirstToSecond}; second -> first = ${directionFromSecondToFirst}`);

    • toString(): string​

      Converts this vector to a human-readable string representation.

      Examples
      Get a string of a vector.
      const myVector = new Vector3(1, 2, 3);
      const vectorString = myVector.toString();

      os.toast('My Vector: ' + vectorString);

    • static angleBetween(first: Vector3, second: Vector3): number​

      Calculates the angle between the two given vectors and returns the result in radians.

      The first parameter is a Vector3 and is the first vector that should be used for comparision.

      The second parameter is a Vector3 and is the second vector that should be used for comparision.

      Examples
      Find the angle between two vectors.
      const first = new Vector3(
          Math.cos(Math.PI / 3),
          Math.sin(Math.PI / 3),
          0,
      ); // 60 degrees
      const second = new Vector3(
          Math.cos(Math.PI / 2),
          Math.sin(Math.PI / 2),
          0
      ); // 90 degrees

      const angle = Vector3.angleBetween(first, second);
      os.toast(angle);

    • static createNormalized(x: number, y: number, z: number): Vector3​

      Creates a 3D vector with the given X and Y values that is normalized immediately upon creation.

      The first parameter is a number and is the X value of the vector.

      The second parameter is a number and is the Y value of the vector.

      The third parameter is a number and is the Z value of the vector.

      Examples
      Create a normalized vector
      const vector = Vector3.createNormalized(1, 2, 3);

    • static distanceBetween(first: Vector3, second: Vector3): number​

      Calculates the distance between the two given vectors and returns the result.

      The first parameter is a Vector3 and is the first vector that should be used for comparision.

      The second parameter is a Vector3 and is the second vector that should be used for comparision.

      Examples
      Find the distance between two vectors.
      const first = new Vector3(5, 10, 3);
      const second = new Vector3(9, 2, 6);
      const distance = Vector3.distanceBetween(first, second);

      os.toast(`Distance: ${distance}`);

    • static interpolateDirection(start: Vector3, finish: Vector3, amount: number): Vector3​

      Constructs a new vector that is the directional linear interpolation between the given start and end positions. The degree that the result is interpolated is determined by the given amount parameter.

      This function works similarly to interpolatePosition(), except the result is always a normalized vector.

      The first parameter is a Vector3 and is the start position.

      The second parameter is a Vector3 and is the end position.

      The third parameter is a number and is the amount that the resulting position should be interpolated between the start and end positions. Values near 0 indicate rotations close to the first and values near 1 indicate rotations close to the second.

      Examples
      Find the direction that points halfway between the two vectors.
      const start = new Vector3(5, 10, 16);
      const finish = new Vector3(9, 2, 6);
      const halfway = Vector3.interpolatePosition(start, finish, 0.5);

      os.toast(halfway);

    • static interpolatePosition(start: Vector3, finish: Vector3, amount: number): Vector3​

      Constructs a new vector that is the linear interpolation between the given start and end positions. The degree that the result is interpolated is determined by the given amount parameter.

      The first parameter is a Vector3 and is the start position.

      The second parameter is a Vector3 and is the end position.

      The third parameter is a number and is the amount that the resulting position should be interpolated between the start and end positions. Values near 0 indicate rotations close to the first and values near 1 indicate rotations close to the second.

      Examples
      Find the position that is halfway between two vectors.
      const start = new Vector3(5, 10, 15);
      const finish = new Vector3(9, 2, 6);
      const halfway = Vector3.interpolatePosition(start, finish, 0.5);

      os.toast(halfway);
      Find the position that is 1/4 between two vectors.
      const start = new Vector3(5, 10, 15);
      const finish = new Vector3(9, 2, 6);
      const halfway = Vector3.interpolatePosition(start, finish, 0.25);

      os.toast(halfway);