@fimbul-works/vec
Version:
A comprehensive TypeScript vector math library providing 2D, 3D, and 4D vector operations with a focus on performance and type safety.
532 lines (531 loc) • 18 kB
TypeScript
/**
* Represents a 2D vector with various operations.
*/
export declare class Vec2 {
#private;
/**
* Creates a new Vec2 instance.
* @param x - The x-coordinate of the vector.
* @param y - The y-coordinate of the vector.
*/
constructor(x?: number, y?: number);
/**
* Adds two vectors.
* @param v - The first vector.
* @param w - The second vector.
* @returns A new Vec2 instance representing the sum.
*/
static add(v: Vec2, w: Vec2): Vec2;
/**
* Subtracts one vector from another.
* @param v - The vector to subtract from.
* @param w - The vector to subtract.
* @returns A new Vec2 instance representing the difference.
*/
static subtract(v: Vec2, w: Vec2): Vec2;
/**
* Multiplies one vector with another.
* @param v - The first vector.
* @param w - The second vector.
* @returns A new Vec2 instance representing the multiplied value.
*/
static multiply(v: Vec2, w: Vec2): Vec2;
/**
* Divides one vector with another.
* @param v - Divident.
* @param w - Divisor.
* @returns A new Vec2 instance representing the divided value.
*/
static divide(v: Vec2, w: Vec2): Vec2;
/**
* Calculates the angle between two vectors.
* @param v - The first vector.
* @param w - The second vector.
* @returns The angle between the vectors in radians.
*/
static angleBetween(v: Vec2, w: Vec2): number;
/**
* Calculates the Euclidean distance between two vectors.
* @param v - The first vector.
* @param w - The second vector.
* @returns The distance between the vectors.
*/
static distance(v: Vec2, w: Vec2): number;
/**
* Calculates the Chebyshev distance between two vectors.
* @param v - The first vector.
* @param w - The second vector.
* @returns The Chebyshev distance between the vectors.
*/
static distanceChebyshev(v: Vec2, w: Vec2): number;
/**
* Calculates the Manhattan distance between two vectors.
* @param v - The first vector.
* @param w - The second vector.
* @returns The Manhattan distance between the vectors.
*/
static distanceManhattan(v: Vec2, w: Vec2): number;
/**
* Calculates the Minkowski distance between two vectors.
* @param v - The first vector.
* @param w - The second vector.
* @param p - The order of the Minkowski distance.
* @returns The Minkowski distance between the vectors.
*/
static distanceMinkowski(v: Vec2, w: Vec2, p: number): number;
/**
* Calculates the squared Euclidean distance between two vectors.
* @param v - The first vector.
* @param w - The second vector.
* @returns The squared distance between the vectors.
*/
static distanceSq(v: Vec2, w: Vec2): number;
/**
* Calculates the dot product of two vectors.
* @param v - The first vector.
* @param w - The second vector.
* @returns The dot product of the vectors.
*/
static dot(v: Vec2, w: Vec2): number;
/**
* Calculates the cross product of two vectors.
* @param v - The first vector.
* @param w - The second vector.
* @returns The cross product scalar value.
*/
static cross(v: Vec2, w: Vec2): number;
/**
* Reflects the vector across a normal vector.
* @param v - The vector to reflect.
* @param normal - The normal vector to reflect across (must be normalized).
* @returns A new Vec2 instance representing the reflected vector.
*/
static reflect(v: Vec2, normal: Vec2): Vec2;
/**
* Creates a Vec2 instance from polar coordinates.
* @param r - The radius.
* @param theta - The angle in radians.
* @returns A new Vec2 instance.
*/
static fromPolarCoords(r: number, theta: number): Vec2;
/**
* Creates an immutable Vec2-like object.
* @param x - The x-coordinate of the vector.
* @param y - The y-coordinate of the vector.
* @returns An immutable object with Vec2-like properties.
*/
static immutable(x?: number, y?: number): Readonly<{
angleX: number;
angleY: number;
isInfinite: boolean;
isNaN: boolean;
isZero: boolean;
magnitude: number;
magnitudeSq: number;
x: number;
xy: readonly number[];
y: number;
}>;
/**
* Checks if a vector has infinite components.
* @param v - The vector to check.
* @returns True if the vector has infinite components, false otherwise.
*/
static isInfinite(v: Vec2): boolean;
/**
* Checks if a vector has NaN components.
* @param v - The vector to check.
* @returns True if the vector has NaN components, false otherwise.
*/
static isNaN(v: Vec2): boolean;
/**
* Checks if a vector is zero.
* @param v - The vector to check.
* @returns True if the vector is zero, false otherwise.
*/
static isZero(v: Vec2): boolean;
/**
* Performs linear interpolation between two vectors.
* @param v - The first vector.
* @param w - The second vector.
* @param t - The interpolation parameter (0 to 1).
* @returns A new Vec2 instance representing the interpolated vector.
*/
static lerp(v: Vec2, w: Vec2, t: number): Vec2;
/**
* Negates a vector.
* @param v - The vector to negate.
* @returns A new Vec2 instance representing the negated vector.
*/
static negate(v: Vec2): Vec2;
/**
* Normalizes a vector.
* @param v - The vector to normalize.
* @returns A new Vec2 instance representing the normalized vector.
*/
static normalize(v: Vec2): Vec2;
/**
* Projects one vector onto another.
* @param v - The vector to project.
* @param w - The vector to project onto.
* @returns A new Vec2 instance representing the projected vector.
*/
static project(v: Vec2, w: Vec2): Vec2;
/**
* Creates a random unit vector.
* @param random - A function that returns a random number between 0 and 1.
* @returns A new Vec2 instance representing a random unit vector.
*/
static random(random?: () => number): Vec2;
/**
* Checks if two vectors are equal.
* @param v - The first vector.
* @param w - The second vector.
* @returns True if the vectors are equal, false otherwise.
*/
static satisfyEquality(v: Vec2, w: Vec2): boolean;
/**
* Checks if two vectors are opposite.
* @param v - The first vector.
* @param w - The second vector.
* @returns True if the vectors are opposite, false otherwise.
*/
static satisfyOpposition(v: Vec2, w: Vec2): boolean;
/**
* Compares a vector with another vector using an epsilon value for floating-point comparison.
* @param v - The first vector.
* @param w - The second vector.
* @param epsilon - The maximum difference between components to consider them equal.
* @returns True if the vectors are equal within epsilon, false otherwise.
*/
static equals(v: Vec2, w: Vec2, epsilon?: number): boolean;
/**
* Scales a vector by a scalar value.
* @param v - The vector to scale.
* @param c - The scalar value.
* @returns A new Vec2 instance representing the scaled vector.
*/
static scale(v: Vec2, c: number): Vec2;
/**
* Creates a zero vector.
* @returns A new Vec2 instance representing a zero vector.
*/
static zero(): Vec2;
/**
* Creates a vector with all components set to 1.0.
* @returns A new Vec2 instance representing a vector with all components set to 1.0.
*/
static one(): Vec2;
/**
* Creates a Vec2 from an array.
* @returns A new Vec2 instance.
*/
static fromArray(arr: [number, number] | number[]): Vec2;
/**
* Creates a Vec2 from an object with x and y properties.
* @returns A new Vec2 instance.
*/
static fromObject(obj: {
x: number;
y: number;
}): Vec2;
/**
* Creates a Vec2 instance from a JSON-parsed object.
* @param json - The JSON-parsed object containing x and y properties.
* @returns A new Vec2 instance.
*/
static fromJSON(json: {
x: number;
y: number;
}): Vec2;
/**
* Gets the x-component of the vector.
* @returns The x-component.
*/
get x(): number;
/**
* Sets the x-component of the vector.
* @param x - The new x-component.
*/
set x(x: number);
/**
* Gets the y-component of the vector.
* @returns The y-component.
*/
get y(): number;
/**
* Sets the y-component of the vector.
* @param y - The new y-component.
*/
set y(y: number);
/**
* Gets a copy of the vector's components as an array.
* @returns An array containing the x and y components of the vector.
*/
get xy(): [number, number];
/**
* Sets both components of the vector at once.
* @param xy - An array containing the new x and y components.
*/
set xy(xy: [number, number] | number[]);
/**
* Gets the angle between the vector and the positive x-axis in radians.
* @returns The angle in radians, always in the range [0, 2π).
*/
get angleX(): number;
/**
* Sets the angle between the vector and the positive x-axis, maintaining the vector's magnitude.
* @param phi - The new angle in radians.
*/
set angleX(phi: number);
/**
* Gets the angle between the vector and the positive y-axis in radians.
* @returns The angle in radians, always in the range [0, 2π).
*/
get angleY(): number;
/**
* Sets the angle between the vector and the positive y-axis, maintaining the vector's magnitude.
* @param phi - The new angle in radians.
*/
set angleY(phi: number);
/**
* Gets the magnitude (length) of the vector.
* @returns The magnitude of the vector.
*/
get magnitude(): number;
/**
* Sets the magnitude (length) of the vector, maintaining its direction.
* @param m - The new magnitude.
*/
set magnitude(m: number);
/**
* Gets the squared magnitude of the vector.
* This is faster to compute than the actual magnitude and is useful for comparisons.
* @returns The squared magnitude of the vector.
*/
get magnitudeSq(): number;
/**
* Adds another vector to this vector.
* @param v - The vector to add.
* @returns This Vec2 instance for method chaining.
*/
add(v: Vec2): this;
/**
* Subtracts another vector from this vector.
* @param v - The vector to subtract.
* @returns This Vec2 instance for method chaining.
*/
subtract(v: Vec2): this;
/**
* Multiplies this vector with another vector.
* @param v - The vector to multiply with.
* @returns This Vec2 instance for method chaining.
*/
multiply(v: Vec2): this;
/**
* Divides this vector with another vector.
* @param v - The vector to divide with.
* @returns This Vec2 instance for method chaining.
*/
divide(v: Vec2): this;
/**
* Calculates the angle between this vector and another vector.
* @param v - The other vector.
* @returns The angle between the vectors in radians.
*/
angleBetween(v: Vec2): number;
/**
* Clamps the magnitude of this vector between a minimum and maximum value.
* @param min - The minimum magnitude.
* @param max - The maximum magnitude.
* @returns This Vec2 instance for method chaining.
*/
clamp(min: number, max: number): this;
/**
* Creates a copy of this vector.
* @returns A new Vec2 instance with the same components.
*/
clone(): Vec2;
/**
* Copies the components of another vector to this vector.
* @param v - The vector to copy from.
* @returns This Vec2 instance for method chaining.
*/
copy(v: Vec2): this;
/**
* Calculates the distance between this vector and another vector.
* @param v - The other vector.
* @returns The distance between the vectors.
*/
distance(v: Vec2): number;
/**
* Calculates the Chebyshev distance between this vector and another vector.
* @param v - The other vector.
* @returns The Chebyshev distance between the vectors.
*/
distanceChebyshev(v: Vec2): number;
/**
* Calculates the Manhattan distance between this vector and another vector.
* @param v - The other vector.
* @returns The Manhattan distance between the vectors.
*/
distanceManhattan(v: Vec2): number;
/**
* Calculates the Minkowski distance between this vector and another vector.
* @param v - The other vector.
* @param p - The order of the Minkowski distance.
* @returns The Minkowski distance between the vectors.
*/
distanceMinkowski(v: Vec2, p: number): number;
/**
* Calculates the squared distance between this vector and another vector.
* @param v - The other vector.
* @returns The squared distance between the vectors.
*/
distanceSq(v: Vec2): number;
/**
* Calculates the dot product of this vector with another vector.
* @param v - The other vector.
* @returns The dot product of the vectors.
*/
dot(v: Vec2): number;
/**
* Calculates the cross product of this vector with another vector.
* @param v - The other vector.
* @returns The cross product of the vectors.
*/
cross(v: Vec2): number;
/**
* Reflects this vector across a normal vector.
* @param normal - The normal vector to reflect across (must be normalized).
* @returns A new Vec2 instance representing the reflected vector.
*/
reflect(normal: Vec2): Vec2;
/**
* Checks if this vector has infinite components.
* @returns True if the vector has infinite components, false otherwise.
*/
isInfinite(): boolean;
/**
* Checks if this vector has NaN components.
* @returns True if the vector has NaN components, false otherwise.
*/
isNaN(): boolean;
/**
* Checks if this vector is zero.
* @returns True if the vector is zero, false otherwise.
*/
isZero(): boolean;
/**
* Limits the maximum magnitude of this vector.
* @param max - The maximum magnitude.
* @returns This Vec2 instance for method chaining.
*/
limitMax(max: number): this;
/**
* Limits the minimum magnitude of this vector.
* @param min - The minimum magnitude.
* @returns This Vec2 instance for method chaining.
*/
limitMin(min: number): this;
/**
* Sets this vector to point towards another vector.
* @param v - The vector to look at.
* @returns This Vec2 instance for method chaining.
*/
lookAt(v: Vec2): this;
/**
* Negates this vector.
* @returns This Vec2 instance for method chaining.
*/
negate(): this;
/**
* Normalizes this vector.
* @returns This Vec2 instance for method chaining.
*/
normalize(): this;
/**
* Projects this vector onto another vector.
* @param v - The vector to project onto.
* @returns This Vec2 instance for method chaining.
*/
project(v: Vec2): this;
/**
* Sets this vector to a random direction with the same magnitude.
* @param random - A function that returns a random number between 0 and 1.
* @returns This Vec2 instance for method chaining.
*/
random(random?: () => number): this;
/**
* Rotates this vector around the Z-axis.
* @param phi - The angle of rotation in radians.
* @returns This Vec2 instance for method chaining.
*/
rotateZ(phi: number): this;
/**
* Checks if this vector is equal to another vector.
* @param v - The other vector.
* @returns True if the vectors are equal, false otherwise.
*/
satisfyEquality(v: Vec2): boolean;
/**
* Checks if this vector is opposite to another vector.
* @param v - The other vector.
* @returns True if the vectors are opposite, false otherwise.
*/
satisfyOpposition(v: Vec2): boolean;
/**
* Compares this vector with another vector using an epsilon value for floating-point comparison.
* @param v - The vector to compare with.
* @param epsilon - The maximum difference between components to consider them equal.
* @returns True if the vectors are equal within epsilon, false otherwise.
*/
equals(v: Vec2, epsilon?: number): boolean;
/**
* Scales this vector by a scalar value.
* @param c - The scalar value.
* @returns This Vec2 instance for method chaining.
*/
scale(c: number): this;
/**
* Rotates this vector 90 degrees to the left.
* @returns This Vec2 instance for method chaining.
*/
turnLeft(): this;
/**
* Rotates this vector 90 degrees to the right.
* @returns This Vec2 instance for method chaining.
*/
turnRight(): this;
/**
* Sets this vector to zero.
* @returns This Vec2 instance for method chaining.
*/
zero(): this;
/**
* Makes the Vec2 instance iterable.
* @yields The x and y components of the vector.
*/
[Symbol.iterator](): IterableIterator<number>;
/**
* Returns a string representation of the vector.
* @returns A string in the format "Vec2(x, y)".
*/
toString(): string;
/**
* Converts the vector to a plain object.
* @returns An object with x and y properties.
*/
toObject(): {
x: number;
y: number;
};
/**
* Serializes the vector to a JSON-friendly format.
* @returns A JSON-friendly object representation of the vector.
*/
toJSON(): {
x: number;
y: number;
};
}