# Vectors

## Introduction​

In CasualOS, Vectors are useful objects that represent 2D/3D positions and directions. They are called vectors because in Math it is common to call an ordered list of numbers a "vector".

Additionally, they are useful because we can use vectors to represent X, Y, and Z positions and perform common operations on them like adding them together or finding the distance between them. When saved to tags, vectors are stored as vector tags.

There are two classes that provide vector functionality:

## Vector2​

`Vector2` is a class that is able to represent 2D positions and directions. It has two properties: `x`, and `y` which contain their respective coordinates.

### `x: number`​

The X value of this vector.

### `y: number`​

The Y value of this vector.

### `new Vector2(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

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

#### 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 degreesconst second = new Vector2(    Math.cos(Math.PI / 2),    Math.sin(Math.PI / 2)); // 90 degreesconst 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.

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​

`Vector3` is a class that is able to represent 3D positions and directions. It has three properties: `x`, `y`, and `z` which contain their respective coordinates.

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

Gets a new Vector2 that contains this vector's X and Y components.

### `xz: Vector2`​

Gets a new Vector2 that contains this vector's X and Z components.

### `yz: Vector2`​

Gets a new Vector2 that contains this vector's Y and Z components.

### `new Vector3(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

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

#### 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 degreesconst second = new Vector3(    Math.cos(Math.PI / 2),    Math.sin(Math.PI / 2),    0); // 90 degreesconst 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.

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