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

#### 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)#### 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.*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);