# Vec2

Class · category: Math

Source: https://github.com/playcanvas/engine/blob/970d89f6d3bc6667f4e1f88153abd6e7e82ed52c/src/core/math/vec2.js#L29

A 2-dimensional vector. Vec2 is commonly used to represent 2D positions, directions, texture
coordinates (UVs) or any pair of related numeric values.

Operations follow one convention throughout the math classes: a method that modifies the vector
it is called on returns it, so calls can be chained and nothing is allocated, while queries such
as [distance](https://api.playcanvas.com/engine/classes/Vec2.md#distance) and [dot](https://api.playcanvas.com/engine/classes/Vec2.md#dot) return a number. Two-operand forms such as [add2](https://api.playcanvas.com/engine/classes/Vec2.md#add2) and
[sub2](https://api.playcanvas.com/engine/classes/Vec2.md#sub2) write the result of `lhs op rhs` into `this`, and it is safe for `this` to also be
one of the operands. Use [clone](https://api.playcanvas.com/engine/classes/Vec2.md#clone) for an independent copy and [copy](https://api.playcanvas.com/engine/classes/Vec2.md#copy) to overwrite one
vector with another.

The static constants such as [ZERO](https://api.playcanvas.com/engine/classes/Vec2.md#zero) and [UP](https://api.playcanvas.com/engine/classes/Vec2.md#up) are frozen shared instances: read them
freely, but writing to one throws. Copy a constant before modifying it.

**Example**

```ts
// Scroll a texture offset each frame without allocating
const offset = new Vec2(0, 0);
const speed = new Vec2(0.1, 0);
offset.addScaled(speed, dt);
```

**Example**

```ts
// Chain mutating operations; each returns the vector it was called on
const toTarget = new Vec2().sub2(target, position).normalize();
const distance = target.distance(position);
```

## Constructors

### constructor

```ts
new Vec2(x?: number, y?: number)
```

Creates a new Vec2 instance.

**Parameters**

- `x` (`number`, optional): The x value. Defaults to 0.
- `y` (`number`, optional): The y value. Defaults to 0.

**Example**

```ts
const v1 = new Vec2(); // defaults to 0, 0
const v2 = new Vec2(1, 2);
```

```ts
new Vec2(arr: number[])
```

Creates a new Vec2 instance.

**Parameters**

- `arr` (`number[]`): The array to set the vector values from.

**Example**

```ts
const v = new Vec2([1, 2]);
```

## Properties

### x

```ts
x: number
```

The first component of the vector.

### y

```ts
y: number
```

The second component of the vector.

### DOWN

```ts
static readonly DOWN: Vec2
```

A constant vector set to [0, -1].

### HALF

```ts
static readonly HALF: Vec2
```

A constant vector set to [0.5, 0.5].

### LEFT

```ts
static readonly LEFT: Vec2
```

A constant vector set to [-1, 0].

### ONE

```ts
static readonly ONE: Vec2
```

A constant vector set to [1, 1].

### RIGHT

```ts
static readonly RIGHT: Vec2
```

A constant vector set to [1, 0].

### UP

```ts
static readonly UP: Vec2
```

A constant vector set to [0, 1].

### ZERO

```ts
static readonly ZERO: Vec2
```

A constant vector set to [0, 0].

## Methods

### add

```ts
add(rhs: Vec2): Vec2
```

Adds a 2-dimensional vector to another in place.

**Parameters**

- `rhs` ([`Vec2`](https://api.playcanvas.com/engine/classes/Vec2.md)): The vector to add to the specified vector.

**Returns** [`Vec2`](https://api.playcanvas.com/engine/classes/Vec2.md): Self for chaining.

**Example**

```ts
const a = new Vec2(10, 10);
const b = new Vec2(20, 20);

a.add(b);

// Outputs [30, 30]
console.log("The result of the addition is: " + a.toString());
```

### add2

```ts
add2(lhs: Vec2, rhs: Vec2): Vec2
```

Adds two 2-dimensional vectors together and returns the result.

**Parameters**

- `lhs` ([`Vec2`](https://api.playcanvas.com/engine/classes/Vec2.md)): The first vector operand for the addition.
- `rhs` ([`Vec2`](https://api.playcanvas.com/engine/classes/Vec2.md)): The second vector operand for the addition.

**Returns** [`Vec2`](https://api.playcanvas.com/engine/classes/Vec2.md): Self for chaining.

**Example**

```ts
const a = new Vec2(10, 10);
const b = new Vec2(20, 20);
const r = new Vec2();

r.add2(a, b);
// Outputs [30, 30]

console.log("The result of the addition is: " + r.toString());
```

### addScalar

```ts
addScalar(scalar: number): Vec2
```

Adds a number to each element of a vector.

**Parameters**

- `scalar` (`number`): The number to add.

**Returns** [`Vec2`](https://api.playcanvas.com/engine/classes/Vec2.md): Self for chaining.

**Example**

```ts
const vec = new Vec2(3, 4);

vec.addScalar(2);

// Outputs [5, 6]
console.log("The result of the addition is: " + vec.toString());
```

### addScaled

```ts
addScaled(rhs: Vec2, scalar: number): Vec2
```

Adds a 2-dimensional vector scaled by scalar value. Does not modify the vector being added.

**Parameters**

- `rhs` ([`Vec2`](https://api.playcanvas.com/engine/classes/Vec2.md)): The vector to add to the specified vector.
- `scalar` (`number`): The number to multiply the added vector with.

**Returns** [`Vec2`](https://api.playcanvas.com/engine/classes/Vec2.md): Self for chaining.

**Example**

```ts
const vec = new Vec2(1, 2);

vec.addScaled(Vec2.UP, 2);

// Outputs [1, 4]
console.log("The result of the addition is: " + vec.toString());
```

### angle

```ts
angle(): number
```

Returns the angle in degrees of the specified 2-dimensional vector.

**Returns** `number`: The angle in degrees of the specified 2-dimensional vector.

**Example**

```ts
const v = new Vec2(6, 0);
const angle = v.angle();
// Outputs 90..
console.log("The angle of the vector is: " + angle);
```

### angleTo

```ts
angleTo(rhs: Vec2): number
```

Returns the shortest Euler angle between two 2-dimensional vectors.

**Parameters**

- `rhs` ([`Vec2`](https://api.playcanvas.com/engine/classes/Vec2.md)): The 2-dimensional vector to calculate angle to.

**Returns** `number`: The shortest angle in degrees between two 2-dimensional vectors.

**Example**

```ts
const a = new Vec2(0, 10); // up
const b = new Vec2(1, -1); // down-right
const angle = a.angleTo(b);
// Outputs 135..
console.log("The angle between vectors a and b: " + angle);
```

### ceil

```ts
ceil(src?: Vec2): Vec2
```

Each element is rounded up to the next largest integer.

**Parameters**

- `src` ([`Vec2`](https://api.playcanvas.com/engine/classes/Vec2.md), optional): The vector to ceil. If not set, the operation is done in place.

**Returns** [`Vec2`](https://api.playcanvas.com/engine/classes/Vec2.md): Self for chaining.

**Example**

```ts
const v = new Vec2(1.2, 3.1);
v.ceil();
// v is now [2, 4]
```

### clone

```ts
clone(): Vec2
```

Returns an identical copy of the specified 2-dimensional vector.

**Returns** [`Vec2`](https://api.playcanvas.com/engine/classes/Vec2.md): A 2-dimensional vector containing the result of the cloning.

**Example**

```ts
const v = new Vec2(10, 20);
const vclone = v.clone();
console.log("The result of the cloning is: " + vclone.toString());
```

### copy

```ts
copy(rhs: Vec2): Vec2
```

Copies the contents of a source 2-dimensional vector to a destination 2-dimensional vector.

**Parameters**

- `rhs` ([`Vec2`](https://api.playcanvas.com/engine/classes/Vec2.md)): A vector to copy to the specified vector.

**Returns** [`Vec2`](https://api.playcanvas.com/engine/classes/Vec2.md): Self for chaining.

**Example**

```ts
const src = new Vec2(10, 20);
const dst = new Vec2();

dst.copy(src);

console.log("The two vectors are " + (dst.equals(src) ? "equal" : "different"));
```

### cross

```ts
cross(rhs: Vec2): number
```

Returns the result of a cross product operation performed on the two specified 2-dimensional
vectors.

**Parameters**

- `rhs` ([`Vec2`](https://api.playcanvas.com/engine/classes/Vec2.md)): The second 2-dimensional vector operand of the cross product.

**Returns** `number`: The cross product of the two vectors.

**Example**

```ts
const right = new Vec2(1, 0);
const up = new Vec2(0, 1);
const crossProduct = right.cross(up);

// Prints 1
console.log("The result of the cross product is: " + crossProduct);
```

### distance

```ts
distance(rhs: Vec2): number
```

Returns the distance between the two specified 2-dimensional vectors.

**Parameters**

- `rhs` ([`Vec2`](https://api.playcanvas.com/engine/classes/Vec2.md)): The second 2-dimensional vector to test.

**Returns** `number`: The distance between the two vectors.

**Example**

```ts
const v1 = new Vec2(5, 10);
const v2 = new Vec2(10, 20);
const d = v1.distance(v2);
console.log("The distance between v1 and v2 is: " + d);
```

### distanceSq

```ts
distanceSq(rhs: Vec2): number
```

Returns the squared distance between the two specified 2-dimensional vectors.

**Parameters**

- `rhs` ([`Vec2`](https://api.playcanvas.com/engine/classes/Vec2.md)): The second 2-dimensional vector to test.

**Returns** `number`: The squared distance between the two vectors.

**Example**

```ts
const v1 = new Vec2(5, 10);
const v2 = new Vec2(10, 20);
const d = v1.distanceSq(v2);
console.log("The squared distance between v1 and v2 is: " + d);
```

### div

```ts
div(rhs: Vec2): Vec2
```

Divides a 2-dimensional vector by another in place.

**Parameters**

- `rhs` ([`Vec2`](https://api.playcanvas.com/engine/classes/Vec2.md)): The vector to divide the specified vector by.

**Returns** [`Vec2`](https://api.playcanvas.com/engine/classes/Vec2.md): Self for chaining.

**Example**

```ts
const a = new Vec2(4, 9);
const b = new Vec2(2, 3);

a.div(b);

// Outputs [2, 3]
console.log("The result of the division is: " + a.toString());
```

### div2

```ts
div2(lhs: Vec2, rhs: Vec2): Vec2
```

Divides one 2-dimensional vector by another and writes the result to the specified vector.

**Parameters**

- `lhs` ([`Vec2`](https://api.playcanvas.com/engine/classes/Vec2.md)): The dividend vector (the vector being divided).
- `rhs` ([`Vec2`](https://api.playcanvas.com/engine/classes/Vec2.md)): The divisor vector (the vector dividing the dividend).

**Returns** [`Vec2`](https://api.playcanvas.com/engine/classes/Vec2.md): Self for chaining.

**Example**

```ts
const a = new Vec2(4, 9);
const b = new Vec2(2, 3);
const r = new Vec2();

r.div2(a, b);

// Outputs [2, 3]
console.log("The result of the division is: " + r.toString());
```

### divScalar

```ts
divScalar(scalar: number): Vec2
```

Divides each element of a vector by a number.

**Parameters**

- `scalar` (`number`): The number to divide by.

**Returns** [`Vec2`](https://api.playcanvas.com/engine/classes/Vec2.md): Self for chaining.

**Example**

```ts
const vec = new Vec2(3, 6);

vec.divScalar(3);

// Outputs [1, 2]
console.log("The result of the division is: " + vec.toString());
```

### dot

```ts
dot(rhs: Vec2): number
```

Returns the result of a dot product operation performed on the two specified 2-dimensional
vectors.

**Parameters**

- `rhs` ([`Vec2`](https://api.playcanvas.com/engine/classes/Vec2.md)): The second 2-dimensional vector operand of the dot product.

**Returns** `number`: The result of the dot product operation.

**Example**

```ts
const v1 = new Vec2(5, 10);
const v2 = new Vec2(10, 20);
const v1dotv2 = v1.dot(v2);
console.log("The result of the dot product is: " + v1dotv2);
```

### equals

```ts
equals(rhs: Vec2): boolean
```

Reports whether two vectors are equal.

**Parameters**

- `rhs` ([`Vec2`](https://api.playcanvas.com/engine/classes/Vec2.md)): The vector to compare to the specified vector.

**Returns** `boolean`: True if the vectors are equal and false otherwise.

**Example**

```ts
const a = new Vec2(1, 2);
const b = new Vec2(4, 5);
console.log("The two vectors are " + (a.equals(b) ? "equal" : "different"));
```

### equalsApprox

```ts
equalsApprox(rhs: Vec2, epsilon?: number): boolean
```

Reports whether two vectors are equal using an absolute error tolerance.

**Parameters**

- `rhs` ([`Vec2`](https://api.playcanvas.com/engine/classes/Vec2.md)): The vector to be compared against.
- `epsilon` (`number`, optional, default `1e-6`): The maximum difference between each component of the two
  vectors. Defaults to 1e-6.

**Returns** `boolean`: True if the vectors are equal and false otherwise.

**Example**

```ts
const a = new Vec2();
const b = new Vec2();
console.log("The two vectors are approximately " + (a.equalsApprox(b, 1e-9) ? "equal" : "different"));
```

### floor

```ts
floor(src?: Vec2): Vec2
```

Each element is set to the largest integer less than or equal to its value.

**Parameters**

- `src` ([`Vec2`](https://api.playcanvas.com/engine/classes/Vec2.md), optional): The vector to floor. If not set, the operation is done in place.

**Returns** [`Vec2`](https://api.playcanvas.com/engine/classes/Vec2.md): Self for chaining.

**Example**

```ts
const v = new Vec2(1.2, 3.9);
v.floor();
// v is now [1, 3]
```

### fromArray

```ts
fromArray(arr: number[] | ArrayBufferView<ArrayBufferLike>, offset?: number): Vec2
```

Set the values of the vector from an array.

**Parameters**

- `arr` (`number[] | ArrayBufferView<ArrayBufferLike>`): The array to set the vector values from.
- `offset` (`number`, optional, default `0`): The zero-based index at which to start copying elements from the
  array. Default is 0.

**Returns** [`Vec2`](https://api.playcanvas.com/engine/classes/Vec2.md): Self for chaining.

**Example**

```ts
const v = new Vec2();
v.fromArray([20, 10]);
// v is set to [20, 10]
```

### length

```ts
length(): number
```

Returns the magnitude of the specified 2-dimensional vector.

**Returns** `number`: The magnitude of the specified 2-dimensional vector.

**Example**

```ts
const vec = new Vec2(3, 4);
const len = vec.length();
// Outputs 5
console.log("The length of the vector is: " + len);
```

### lengthSq

```ts
lengthSq(): number
```

Returns the magnitude squared of the specified 2-dimensional vector.

**Returns** `number`: The magnitude squared of the specified 2-dimensional vector.

**Example**

```ts
const vec = new Vec2(3, 4);
const len = vec.lengthSq();
// Outputs 25
console.log("The length squared of the vector is: " + len);
```

### lerp

```ts
lerp(lhs: Vec2, rhs: Vec2, alpha: number): Vec2
```

Returns the result of a linear interpolation between two specified 2-dimensional vectors.

**Parameters**

- `lhs` ([`Vec2`](https://api.playcanvas.com/engine/classes/Vec2.md)): The 2-dimensional vector to interpolate from.
- `rhs` ([`Vec2`](https://api.playcanvas.com/engine/classes/Vec2.md)): The 2-dimensional vector to interpolate to.
- `alpha` (`number`): The value controlling the point of interpolation. Between 0 and 1,
  the linear interpolant will occur on a straight line between lhs and rhs. Outside of this
  range, the linear interpolant will occur on a ray extrapolated from this line.

**Returns** [`Vec2`](https://api.playcanvas.com/engine/classes/Vec2.md): Self for chaining.

**Example**

```ts
const a = new Vec2(0, 0);
const b = new Vec2(10, 10);
const r = new Vec2();

r.lerp(a, b, 0);   // r is equal to a
r.lerp(a, b, 0.5); // r is 5, 5
r.lerp(a, b, 1);   // r is equal to b
```

### max

```ts
max(rhs: Vec2): Vec2
```

Each element is assigned a value from rhs parameter if it is larger.

**Parameters**

- `rhs` ([`Vec2`](https://api.playcanvas.com/engine/classes/Vec2.md)): The 2-dimensional vector used as the source of elements to compare to.

**Returns** [`Vec2`](https://api.playcanvas.com/engine/classes/Vec2.md): Self for chaining.

**Example**

```ts
const a = new Vec2(5, 1);
const b = new Vec2(2, 8);
a.max(b);
// a is now [5, 8]
```

### min

```ts
min(rhs: Vec2): Vec2
```

Each element is assigned a value from rhs parameter if it is smaller.

**Parameters**

- `rhs` ([`Vec2`](https://api.playcanvas.com/engine/classes/Vec2.md)): The 2-dimensional vector used as the source of elements to compare to.

**Returns** [`Vec2`](https://api.playcanvas.com/engine/classes/Vec2.md): Self for chaining.

**Example**

```ts
const a = new Vec2(5, 1);
const b = new Vec2(2, 8);
a.min(b);
// a is now [2, 1]
```

### mul

```ts
mul(rhs: Vec2): Vec2
```

Multiplies a 2-dimensional vector to another in place.

**Parameters**

- `rhs` ([`Vec2`](https://api.playcanvas.com/engine/classes/Vec2.md)): The 2-dimensional vector used as the second multiplicand of the operation.

**Returns** [`Vec2`](https://api.playcanvas.com/engine/classes/Vec2.md): Self for chaining.

**Example**

```ts
const a = new Vec2(2, 3);
const b = new Vec2(4, 5);

a.mul(b);

// Outputs 8, 15
console.log("The result of the multiplication is: " + a.toString());
```

### mul2

```ts
mul2(lhs: Vec2, rhs: Vec2): Vec2
```

Returns the result of multiplying the specified 2-dimensional vectors together.

**Parameters**

- `lhs` ([`Vec2`](https://api.playcanvas.com/engine/classes/Vec2.md)): The 2-dimensional vector used as the first multiplicand of the operation.
- `rhs` ([`Vec2`](https://api.playcanvas.com/engine/classes/Vec2.md)): The 2-dimensional vector used as the second multiplicand of the operation.

**Returns** [`Vec2`](https://api.playcanvas.com/engine/classes/Vec2.md): Self for chaining.

**Example**

```ts
const a = new Vec2(2, 3);
const b = new Vec2(4, 5);
const r = new Vec2();

r.mul2(a, b);

// Outputs 8, 15
console.log("The result of the multiplication is: " + r.toString());
```

### mulScalar

```ts
mulScalar(scalar: number): Vec2
```

Multiplies each element of a vector by a number.

**Parameters**

- `scalar` (`number`): The number to multiply by.

**Returns** [`Vec2`](https://api.playcanvas.com/engine/classes/Vec2.md): Self for chaining.

**Example**

```ts
const vec = new Vec2(3, 6);

vec.mulScalar(3);

// Outputs [9, 18]
console.log("The result of the multiplication is: " + vec.toString());
```

### normalize

```ts
normalize(src?: Vec2): Vec2
```

Returns this 2-dimensional vector converted to a unit vector in place. If the vector has a
length of zero, the vector's elements will be set to zero.

**Parameters**

- `src` ([`Vec2`](https://api.playcanvas.com/engine/classes/Vec2.md), optional): The vector to normalize. If not set, the operation is done in place.

**Returns** [`Vec2`](https://api.playcanvas.com/engine/classes/Vec2.md): Self for chaining.

**Example**

```ts
const v = new Vec2(25, 0);

v.normalize();

// Outputs 1, 0
console.log("The result of the vector normalization is: " + v.toString());
```

### rotate

```ts
rotate(degrees: number): Vec2
```

Rotate a vector by an angle in degrees.

**Parameters**

- `degrees` (`number`): The number to degrees to rotate the vector by.

**Returns** [`Vec2`](https://api.playcanvas.com/engine/classes/Vec2.md): Self for chaining.

**Example**

```ts
const v = new Vec2(0, 10);

v.rotate(45); // rotates by 45 degrees

// Outputs [7.071068.., 7.071068..]
console.log("Vector after rotation is: " + v.toString());
```

### round

```ts
round(src?: Vec2): Vec2
```

Each element is rounded up or down to the nearest integer.

**Parameters**

- `src` ([`Vec2`](https://api.playcanvas.com/engine/classes/Vec2.md), optional): The vector to round. If not set, the operation is done in place.

**Returns** [`Vec2`](https://api.playcanvas.com/engine/classes/Vec2.md): Self for chaining.

**Example**

```ts
const v = new Vec2(1.4, 3.6);
v.round();
// v is now [1, 4]
```

### set

```ts
set(x: number, y: number): Vec2
```

Sets the specified 2-dimensional vector to the supplied numerical values.

**Parameters**

- `x` (`number`): The value to set on the first component of the vector.
- `y` (`number`): The value to set on the second component of the vector.

**Returns** [`Vec2`](https://api.playcanvas.com/engine/classes/Vec2.md): Self for chaining.

**Example**

```ts
const v = new Vec2();
v.set(5, 10);

// Outputs 5, 10
console.log("The result of the vector set is: " + v.toString());
```

### sub

```ts
sub(rhs: Vec2): Vec2
```

Subtracts a 2-dimensional vector from another in place.

**Parameters**

- `rhs` ([`Vec2`](https://api.playcanvas.com/engine/classes/Vec2.md)): The vector to subtract from the specified vector.

**Returns** [`Vec2`](https://api.playcanvas.com/engine/classes/Vec2.md): Self for chaining.

**Example**

```ts
const a = new Vec2(10, 10);
const b = new Vec2(20, 20);

a.sub(b);

// Outputs [-10, -10]
console.log("The result of the subtraction is: " + a.toString());
```

### sub2

```ts
sub2(lhs: Vec2, rhs: Vec2): Vec2
```

Subtracts two 2-dimensional vectors from one another and returns the result.

**Parameters**

- `lhs` ([`Vec2`](https://api.playcanvas.com/engine/classes/Vec2.md)): The first vector operand for the subtraction.
- `rhs` ([`Vec2`](https://api.playcanvas.com/engine/classes/Vec2.md)): The second vector operand for the subtraction.

**Returns** [`Vec2`](https://api.playcanvas.com/engine/classes/Vec2.md): Self for chaining.

**Example**

```ts
const a = new Vec2(10, 10);
const b = new Vec2(20, 20);
const r = new Vec2();

r.sub2(a, b);

// Outputs [-10, -10]
console.log("The result of the subtraction is: " + r.toString());
```

### subScalar

```ts
subScalar(scalar: number): Vec2
```

Subtracts a number from each element of a vector.

**Parameters**

- `scalar` (`number`): The number to subtract.

**Returns** [`Vec2`](https://api.playcanvas.com/engine/classes/Vec2.md): Self for chaining.

**Example**

```ts
const vec = new Vec2(3, 4);

vec.subScalar(2);

// Outputs [1, 2]
console.log("The result of the subtraction is: " + vec.toString());
```

### toArray

```ts
toArray(arr?: number[], offset?: number): number[]
```

**Parameters**

- `arr` (`number[]`, optional): The array to populate with the vector's number
  components. If not specified, a new array is created.
- `offset` (`number`, optional): The zero-based index at which to start copying elements to the
  array. Default is 0.

**Returns** `number[]`: The vector as an array.

```ts
toArray(arr: ArrayBufferView, offset?: number): ArrayBufferView
```

**Parameters**

- `arr` (`ArrayBufferView`): The array to populate with the vector's number
  components. If not specified, a new array is created.
- `offset` (`number`, optional): The zero-based index at which to start copying elements to the
  array. Default is 0.

**Returns** `ArrayBufferView`: The vector as an array.

### toString

```ts
toString(): string
```

Converts the vector to string form.

**Returns** `string`: The vector in string form.

**Example**

```ts
const v = new Vec2(20, 10);
// Outputs [20, 10]
console.log(v.toString());
```