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 provides 2D vectors.
• Vector3 provides 3D vectors.

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

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

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.

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.

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