typed-vector v1.3.1

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