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.