typed-vector
v1.3.1
Published
2D Vectors in typescript
Downloads
37
Readme
typed-vector
It's a 2d vector library written in typescript. It includes lots of methods to simplify vector calculations in game development. It has zero dependencies and has unit tests.
How to use
This module exports a Vector
class and IVector
interface.
import { Vector, IVector } from 'typed-vector';
const vector = new Vector(1, 2);
const vectorLike: IVector = { x: 5, y: 8 };
vector.add(vectorLike);
API
IVector
const vectorLike: IVector = { x: 5, y: 8 };
Vector(x: number, y: number)
const a = new Vector(1, 2); // x: 1, y: 2
const b = new Vector(); // x: 0, y: 0
Static methods
Vector.angleBetween(a: Vector, b: Vector): number
Computes the angle between vectors.
const a = new Vector(-5, 4);
const b = new Vector(1, 4);
Vector.angleBetween(a, b); // 1.14103
Vector.angleBetweenSigned(a: Vector, b: Vector): number
Computes the angle between vectors with a sign.
const a = new Vector(-5, 4);
const b = new Vector(1, 4);
Vector.angleBetweenSigned(a, b); // -1.14103
Vector.distance(a: IVector, b: IVector): number
Computes the distance of two vector-likes.
const a = Vector.distance({ x: -10, y: 0}, { x: 10, y: 0}); // 20
Vector.distanceSq(a: IVector, b: IVector): number
Computes the squared distance of two vector-likes.
const a = Vector.distanceSq({ x: -1, y: 0}, { x: 1, y: 0}); // 4
Vector.distanceToSegment(coordinate: Vector, segmentStart: Vector, segmentEnd: Vector): number
Computes the distance of a coordinate to a segment defined by 2 coordinates.
const segmentStart = new Vector(0, 0);
const segmentEnd = new Vector(5, 0);
const coordinate = new Vector(2, 7);
Vector.distanceToSegment(coordinate, segmentStart, segmentEnd); // 7
Vector.distanceToSegmentSq(coordinate: Vector, segmentStart: Vector, segmentEnd: Vector): number
Computes the squared distance of a coordinate to a segment defined by 2 coordinates.
const segmentStart = new Vector(0, 0);
const segmentEnd = new Vector(5, 0);
const coordinate = new Vector(2, 7);
Vector.distanceToSegmentSq(coordinate, segmentStart, segmentEnd); // 49
Vector.fromArray([number, number]): Vector
Creates a vector from values provided as array.
const a = Vector.fromArray([5, 6]); // x: 5, y: 6
Vector.fromCoordinate(vector: IVector): Vector
Creates a vector from a coordinate.
Vector.fromCoordinate({ x: 4, y: 5 }); // x: 4, y: 5
Vector.fromCoordinates(start: IVector, end: IVector): Vector
Creates a vector from start and end coordinates.
Vector.fromCoordinates({ x: 1, y: 1}, { x: 4, y: 5 }); // x: 3, y: 4
Vector.fromNormal(vector: IVector): Vector
Creates a vector from other vector's normal.
Vector.fromNormal({ x: 5, y: 4 }); // x: 4, y: 5
Vector.fromPolar(length: number, angle: number): Vector
Creates a vector from polar coordinates. The angle is in radians.
Vector.fromPolar(10, Math.PI); // x: -10, y: 0
Vector.fromRandom(): Vector
Creates a unit vector with random angle.
Vector.fromRandom();
Methods
add(a: IVector [, b: IVector] [, c: IVector]): self
Mutates self by adding other vector(s).
const a = new Vector(1, 2);
const b = new Vector(5, 5);
a.add(b); // x: 6, y: 7
addLength(length: number): number
Increments or decrements the magnitude of the vector by given length. If negative value is passed the vector magnitude is shortened to a minimum of 0 length.
new Vector(15, 0).addLength(20); // x: 35, y: 0
new Vector(0, 10).addLength(-20); // x: 0, y: 0
addX(x: number): self
Mutates self by adding x.
new Vector(2, 5).addX(1); // x: 3, y: 5
addY(y: number): self
Mutates self by adding y.
new Vector(2, 5).addY(1); // x: 2, y: 6
alignWith(vector: Vector): self
Rotates the vector to be aligned with other vector.
const a = new Vector(20, 4);
const b = new Vector(1, -30);
a.alignWith(b); // x: 0.67949, y: -20.384
clampAngle(angle: number, maxDiff: number): self
Clamps vectors angle to be within given diff. The diff is for both directions so maxDiff
of Math.PI
will effectively disable clamping effect.
new Vector(1, 0)
.rotate(0.2 + Math.PI * 2)
.clampAngle(0, 0.1)
.getAngle(); // 0.1
clampLength(a: number, b: number): self
Clamps vectors length to be between min and max lengths. The boundaries can be set in any order e.g. (min, max) and (max, min).
new Vector(2, 0).clampLength(5, 10); // x: 5, y: 0
clone(): Vector
Creates a new Vector with identical values.
const a = new Vector(5, 4);
const b = a.clone();
a === b; // false
copy(vector: IVector): self
Mutates self copying x and y from other vector-like.
new Vector(5, 4).copy({ x: 2, y: 3 }); // x: 2, y: 3
cross(vector: IVector): number
A cross product of self and other vector.
const a = new Vector(5, 3);
const b = new Vector(2, 4);
a.cross(b); // 14
crossSign(vector: IVector): number
The sign of the cross product of self and other vector. Equal vector's sign is 1;
const a = new Vector(1, 0);
const b = new Vector(0, 1);
a.crossSign(b); // 1
dot(vector: IVector): number
A dot product of self and other vector.
const a = new Vector(1, 2);
const b = new Vector(3, 4);
a.dot(b); // 11
getAngle(): number
Gets the angle of the vector.
new Vector(5, 4).getAngle(); // 0.67474094
getLength(): number
Gets the magnitude of the vector.
new Vector(5, 4).getLength(); // 6.40312423
getLengthSq(): number
Gets the magnitude of the vector squared.
new Vector(1, 2).getLengthSq(); // 5
isEqual(vector: IVector): boolean
Checks if given vector-like is equal.
new Vector(20, 4).isEqual({ 20, 4 }); // true
new Vector(20, 4).isEqual({ 21, 4 }); // false
lerpAlignWith(rotation: number, vector: Vector): self
Rotates towards a given vector for a given increment angle. If increment angle is greter than the difference of the vectors' angles the vectors will be aligned.
const a = Vector.fromPolar(10, 0.5);
const b = Vector.fromPolar(10, 1.5);
a.lerpAlignWidth(0.2, b).getAngle(); // 0.7
applyMaxLength(maxLength: number): self
Limits the length of the vector.
new Vector(-10, 0).applyMaxLength(2); // x: -2, y: 0
applyMinLength(minLength: number): self
Makes vector to be minimum of given length. Zero vector will be ignored.
new Vector(-1, 0).applyMixLength(3); // x: -3, y: 0
mirror(): self
Mirrors the vector.
new Vector(5, 4).mirror(); // x: -5, y: -4
normalize(): self
Normalizes the vector i.e. sets the length to 1.
new Vector(100, 53).normalize().getLength(); // 1
randomizeAngle(maxRotation?: number): self
Randomizes the angle. The max range of randomization from current angle can be provided as an argument.
new Vector(20, 4).randomizeAngle();
rotate(angle: number): self
Rotates vector by given radians.
new Vector(10, 0).scale(Math.PI); // x: -10, y: 0
scale(multiplier: number): self
Mutates self by multiplying x and y.
new Vector(1, 2).scale(5); // x: 5, y: 10
scaledAdd(multiplier: number, ...vectors: IVector[]): self
Mutates self by adding other vector multiplied by given multiplier.
const a = new Vector(1, 1);
const b = new Vector(3, 3);
a.scaledAdd(2, b); // x: 7, y: 7
set(x: number, y: number): self
Mutates self by setting x and y values.
new Vector(5, 4).set(2, 3); // x: 2, y: 3
setAngle(): number
Sets the angle of the vector.
new Vector(15, 0).setAngle(Math.PI); // x: -15, y: 0
setLength(): number
Sets the magnitude of the vector.
new Vector(15, 0).setLength(20); // x: 20, y: 0
setX(x: number): self
Sets x.
new Vector(2, 5).setX(1); // x: 1, y: 5
setY(y: number): self
Sets y.
new Vector(2, 5).addY(1); // x: 2, y: 1
subtract(a: IVector [, b: IVector] [, c: IVector]): self
Mutates self by subtracting other vector(s).
const a = new Vector(5, 4);
const b = new Vector(3, 2);
a.subtract(b); // x: 2, y: 2
zero(): self
Sets vector's length to 0.
new Vector(5, 4).zero(); // x: 0, y: 0