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

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

`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

`let myVector = new Vector2(2, 3);`

os.toast(`X: ${myVector.x}, Y: ${myVector.y}`);

`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

`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

`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

`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

`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

`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

`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

`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

`const first = new Vector2(1, 2);`

const second = new Vector2(3, 4);

const subtracted = first.subtract(second);

os.toast(subtracted);

`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

`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

`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

`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

`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

`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

`const start = new Vector2(5, 10);`

const finish = new Vector2(9, 2);

const halfway = Vector2.interpolatePosition(start, finish, 0.5);

os.toast(halfway);

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

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

`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

`let myVector = new Vector3(2, 3, 4);`

os.toast(`X: ${myVector.x}, Y: ${myVector.y}, Z: ${myVector.z}`);

`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

`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

`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

`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

`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

`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

`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

`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

`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

`const first = new Vector3(1, 2, 3);`

const second = new Vector3(3, 4, 5);

const subtracted = first.subtract(second);

os.toast(subtracted);

`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

`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

`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

`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

`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

`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

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

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