# Vec2

Interface representing a 2D vector. A 2D vector is represented by (x, y) coordinates, and can
represent a point in a plane, a directional vector, or other types of data with three ordered
dimensions. Vec2 objects are created with the `ecs.math.vec2`

Vec2Factory, or through operations
on other Vec2 objects.

## Code Example

`const {vec2} = ecs.math `

const a = vec2.xy(1, 2)

const b = vec2.scale(3) // b is 3, 3

const c = a.plus(b).times(vec2.xy(5, 4)).normalize() // c is (1, 1)

## Source

The Vec2Source interface represents any object that has x and y properties and hence can be used
as a data source to create a Vec2. In addition, Vec2Source can be used as an argument to Vec2
algorithms, meaning that any object with `{x: number, y: number}`

properties can be used.

Vec2Source has the following enumerable properties:

`readonly x: number`

Access the x component of the vector.

`readonly y: number`

Access the y component of the vector.

## Factory

Vec2 objects are created with the `ecs.math.vec2`

Vec2Factory, with the following methods:

### vec2.from()

`vec2.from({x, y}: {x: number, y: number}) => Vec2`

Create a Vec2 from a Vec2, or other object with x, y properties.

### vec2.one()

`vec2.one: () => Vec2`

Create a Vec2 with all elements set to one. This is equivalent to `vec2.from({x: 1, y: 1})`

.

### vec2.scale()

`vec2.scale: (s: number) => Vec2`

Create a Vec2 with all elements set to the scale value s. This is equivalent to
`vec2.from({x: s, y: s})`

.

### vec2.xy()

`vec2.xy: (x: number, y: number) => Vec2`

Create a Vec2 from x, y values. This is equivalent to `vec2.from({x, y})`

.

### vec2.zero()

`vec2.zero: () => Vec2`

Create a Vec2 with all components set to zero. This is equivalent to `vec2.from({x: 0, y: 0})`

.

## Properties

Vec2 has the following enumerable properties:

`readonly x: number`

Access the x component of the vector.

`readonly y: number`

Access the y component of the vector.

## Immutable API

The following methods perform computations based on the current value of a Vec2, but do not modify its contents. Methods that return Vec2 types return new objects. Immutable APIs are typically safer, more readable, and less error-prone than mutable APIs, but may be inefficient in situations where thousands of objects are allocated each frame. In cases where object garbage collection is a performance concern, prefer the Mutable API (below).

### .clone()

`clone: () => Vec2`

Create a new vector with the same components as this vector.

### .cross()

`cross: (v: Vec2Source) => Vec2`

Compute the cross product of this vector and another vector. For 2D vectors, the cross product is the magnitude of the z component of the 3D cross product of the two vectors with 0 as the z component.

### .distanceTo()

`distanceTo: (v: Vec2Source) => number`

Compute the euclidean distance between this vector and another vector.

### .divide()

`divide: (v: Vec2Source) => Vec2`

Element-wise vector division.

### .dot()

`dot: (v: Vec2Source) => number`

Compute the dot product of this vector and another vector.

### .equals()

`equals: (v: Vec2Source, tolerance: number) => boolean`

Check whether two vectors are equal, with a specified floating point tolerance.

### .length()

`length: () => number`

Length of the vector.

### .minus()

`minus: (v: Vec2Source) => Vec2`

Subtract a vector from this vector.

### .mix()

`mix: (v: Vec2Source, t: number) => Vec2`

Compute a linear interpolation between this vector and another vector v with a factor t such that
the result is `thisVec * (1 - t) + v * t`

. The factor t should be between 0 and 1.

### .normalize()

`normalize: () => Vec2`

Return a new vector with the same direction as this vector, but with a length of 1.

### .plus()

`plus: (v: Vec2Source) => Vec2`

Add two vectors together.

### .scale()

`scale: (s: number) => Vec2`

Multiply the vector by a scalar.

### .times()

`times: (v: Vec2Source) => Vec2`

Element-wise vector multiplication.

## Mutable API

The following methods perform computations based on the current value of a Vec2, and modify its contents in place. They are parallel to methods in the mutable API above. Methods that return Vec2 types return a reference to the current object for convenient method chaining. Mutable APIs can be more performant than Immutable APIs, but are typically less safe, less readable, and more error-prone. In cases where a section of code will likely not be called many times on a given frame, consider using the Immutable API (above).

This next example is equivalent to the Immutable API example above, but allocates two Vec2 objects instead of six:

`const {vec2} = ecs.math `

const a = vec2.xy(1, 2)

const b = vec2.scale(3) // b is 3, 3

a.setPlus(b).setTimes(b.setXy(5, 4)).setNormalize() // a is (1, 1, 1) and b is (5, 4)

### .setDivide()

`setDivide: (v: Vec2Source) => Vec2`

Element-wise vector division. Store the result in this Vec2 and return this Vec2 for chaining.

### .setMinus()

`setMinus: (v: Vec2Source) => Vec2`

Subtract a vector from this vector. Store the result in this Vec2 and return this Vec2 for chaining.

### .setMix()

`setMix: (v: Vec2Source, t: number) => Vec2`

Compute a linear interpolation between this vector and another vector v with a factor t such that the result is thisVec * (1 - t) + v * t. The factor t should be between 0 and 1. Store the result in this Vec2 and return this Vec2 for chaining.

### .setNormalize()

`setNormalize: () => Vec2`

Set the vector to be a version of itself with the same direction, but with length 1. Store the result in this Vec2 and return this Vec2 for chaining.

### .setPlus()

`setPlus: (v: Vec2Source) => Vec2`

Add two vectors together. Store the result in this Vec2 and return this Vec2 for chaining.

### .setScale()

`setScale: (s: number) => Vec2`

Multiply the vector by a scalar. Store the result in this Vec2 and return this Vec2 for chaining.

### .setTimes()

`setTimes: (v: Vec2Source) => Vec2`

Element-wise vector multiplication. Store the result in this Vec2 and return this Vec2 for chaining.

### .setX()

`setX: (v: number) => Vec2`

Set the Vec2's x component. Store the result in this Vec2 and return this Vec2 for chaining.

### .setY()

`setY: (v: number) => Vec2`

Set the Vec2's y component. Store the result in this Vec2 and return this Vec2 for chaining.

## Set API

The following methods set the value of the current Vec2 object without regard to its current content, replacing whatever was there before.

### .makeOne()

`makeOne: () => Vec2`

Set the Vec2 to be all ones. Store the result in this Vec2 and return this Vec2 for chaining.

### .makeScale()

`makeScale: (s: number) => Vec2`

Set the Vec2 to have all components set to the scale value s. Store the result in this Vec2 and return this Vec2 for chaining.

### .makeZero()

`makeZero: () => Vec2`

Set the Vec2 to be all zeros. Store the result in this Vec2 and return this Vec2 for chaining.

### .setFrom()

`setFrom: (source: Vec2Source) => Vec2`

Set this Vec2 to have the same value as another Vec2 or other object with x and y properties. Store the result in this Vec2 and return this Vec2 for chaining.

### .setXy()

`setXy: (x: number, y: number) => Vec2`

Set the Vec2's x and y components. Store the result in this Vec2 and return this Vec2 for chaining.