Web Engine Dev

Appearance

@web-engine-dev/math

@web-engine-dev/math / Vec3

Class: Vec3 ​

A 3D vector class with x, y, and z components.

Default operations are immutable and return new instances. For performance-critical code paths (game loops, hot paths), use the mutable variants (suffix Mut) or static out-parameter methods (suffix Out) to avoid allocations.

Example ​

ts
// Immutable (allocates new Vec3)
const result = a.add(b);

// Mutable (modifies a in place, no allocation)
a.addMut(b);

// Out-parameter (writes to existing Vec3)
Vec3.addOut(a, b, result);

Constructors ​

Constructor ​

new Vec3(x?, y?, z?): Vec3

Parameters ​

x? ​

number = 0

y? ​

number = 0

z? ​

number = 0

Returns ​

Vec3

Properties ​

x ​

x: number

y ​

y: number

z ​

z: number

Methods ​

[iterator]() ​

[iterator](): Generator<number>

Returns ​

Generator<number>

abs() ​

abs(): Vec3

Returns ​

Vec3

add() ​

add(v): Vec3

Adds another vector to this vector.

Parameters ​

v ​

Vec3

Vector to add

Returns ​

Vec3

New vector with the sum

addMut() ​

addMut(v): this

Adds another vector to this vector in place.

Parameters ​

v ​

Vec3

Vector to add

Returns ​

this

this for chaining

angle() ​

angle(v): number

Returns the angle between this vector and another (in radians).

Parameters ​

v ​

Vec3

Returns ​

number

ceil() ​

ceil(): Vec3

Returns ​

Vec3

clamp() ​

clamp(min, max): Vec3

Parameters ​

min ​

Vec3

max ​

Vec3

Returns ​

Vec3

copyMut() ​

copyMut(v): this

Copies components from another vector.

Parameters ​

v ​

Vec3

Source vector

Returns ​

this

this for chaining

copyToArray() ​

copyToArray(arr, offset?): void

Parameters ​

arr ​

number[] | Float32Array<ArrayBufferLike>

offset? ​

number = 0

Returns ​

void

cross() ​

cross(v): Vec3

Computes the cross product with another vector. The result is perpendicular to both input vectors.

Parameters ​

v ​

Vec3

Other vector

Returns ​

Vec3

New vector perpendicular to both inputs

Example ​

ts
const right = Vec3.right();    // (1, 0, 0)
const up = Vec3.up();          // (0, 1, 0)
const forward = right.cross(up); // (0, 0, -1) in right-handed system

crossMut() ​

crossMut(v): this

Computes the cross product with another vector in place.

Parameters ​

v ​

Vec3

Other vector

Returns ​

this

this for chaining

distance() ​

distance(v): number

Computes the distance to another vector.

Parameters ​

v ​

Vec3

Other vector

Returns ​

number

Distance

distanceSq() ​

distanceSq(v): number

Computes the squared distance to another vector.

Parameters ​

v ​

Vec3

Other vector

Returns ​

number

Squared distance

div() ​

div(s): Vec3

Divides this vector by a scalar. Returns zero vector if divisor is zero to avoid Infinity/NaN.

Parameters ​

s ​

number

Scalar divisor

Returns ​

Vec3

New divided vector

divVec() ​

divVec(v): Vec3

Component-wise division by another vector. Uses 0 for components where divisor is 0 to avoid Infinity/NaN.

Parameters ​

v ​

Vec3

Vector to divide by

Returns ​

Vec3

New vector with component-wise quotients

dot() ​

dot(v): number

Computes the dot product with another vector.

Parameters ​

v ​

Vec3

Other vector

Returns ​

number

Scalar dot product

equals() ​

equals(v, epsilon?): boolean

Parameters ​

v ​

Vec3

epsilon? ​

number = 0

Returns ​

boolean

floor() ​

floor(): Vec3

Returns ​

Vec3

length() ​

length(): number

Returns the length (magnitude) of this vector.

Returns ​

number

lengthSq() ​

lengthSq(): number

Returns the squared length (magnitude) of this vector.

Returns ​

number

lerp() ​

lerp(v, t): Vec3

Linear interpolation between this vector and another.

Parameters ​

v ​

Vec3

Target vector

t ​

number

Interpolation factor (0 = this, 1 = v)

Returns ​

Vec3

New interpolated vector

Example ​

ts
const start = new Vec3(0, 0, 0);
const end = new Vec3(10, 0, 0);
const mid = start.lerp(end, 0.5);  // Vec3(5, 0, 0)

lerpMut() ​

lerpMut(v, t): this

Linearly interpolates this vector towards another in place.

Parameters ​

v ​

Vec3

Target vector

t ​

number

Interpolation factor (0 = this, 1 = v)

Returns ​

this

this for chaining

max() ​

max(v): Vec3

Parameters ​

v ​

Vec3

Returns ​

Vec3

min() ​

min(v): Vec3

Parameters ​

v ​

Vec3

Returns ​

Vec3

mul() ​

mul(s): Vec3

Multiplies this vector by a scalar.

Parameters ​

s ​

number

Scalar value

Returns ​

Vec3

New scaled vector

mulVec() ​

mulVec(v): Vec3

Component-wise multiplication with another vector.

Parameters ​

v ​

Vec3

Vector to multiply with

Returns ​

Vec3

New vector with component-wise products

negate() ​

negate(): Vec3

Returns the negated vector (-x, -y, -z).

Returns ​

Vec3

negateMut() ​

negateMut(): this

Negates this vector in place.

Returns ​

this

this for chaining

normalize() ​

normalize(): Vec3

Returns a normalized (unit length) version of this vector.

Returns ​

Vec3

New unit vector, or zero vector if length is zero

normalizeFast() ​

normalizeFast(): Vec3

Fast normalization with minimal overhead. Returns zero vector if length is near-zero to prevent NaN propagation.

Returns ​

Vec3

New unit vector, or zero vector if length < epsilon

normalizeFastMut() ​

normalizeFastMut(): this

Fast in-place normalization with minimal overhead. Sets to zero vector if length is near-zero to prevent NaN propagation.

Returns ​

this

normalizeMut() ​

normalizeMut(): this

Normalizes this vector in place.

Returns ​

this

this for chaining

project() ​

project(onto): Vec3

Projects this vector onto another vector.

Parameters ​

onto ​

Vec3

Returns ​

Vec3

reflect() ​

reflect(normal): Vec3

Reflects the vector across a normal.

Parameters ​

normal ​

Vec3

The surface normal to reflect across (should be normalized)

Returns ​

Vec3

New reflected vector

Example ​

ts
const incident = new Vec3(1, -1, 0).normalize();
const normal = Vec3.up();  // (0, 1, 0)
const reflected = incident.reflect(normal);  // bounces off horizontal surface

round() ​

round(): Vec3

Returns ​

Vec3

scaleMut() ​

scaleMut(s): this

Multiplies this vector by a scalar in place.

Parameters ​

s ​

number

Scalar value

Returns ​

this

this for chaining

setMut() ​

setMut(x, y, z): this

Sets the components of this vector directly.

Parameters ​

x ​

number

X component

y ​

number

Y component

z ​

number

Z component

Returns ​

this

this for chaining

slerp() ​

slerp(v, t): Vec3

Spherical linear interpolation. Assumes both vectors are normalized. Falls back to linear interpolation for nearly parallel vectors.

Parameters ​

v ​

Vec3

t ​

number

Returns ​

Vec3

sub() ​

sub(v): Vec3

Subtracts another vector from this vector.

Parameters ​

v ​

Vec3

Vector to subtract

Returns ​

Vec3

New vector with the difference

subMut() ​

subMut(v): this

Subtracts another vector from this vector in place.

Parameters ​

v ​

Vec3

Vector to subtract

Returns ​

this

this for chaining

toArray() ​

toArray(): [number, number, number]

Returns ​

[number, number, number]

toFloat32Array() ​

toFloat32Array(): Float32Array

Returns ​

Float32Array

toString() ​

toString(): string

Returns ​

string

addOut() ​

static addOut(a, b, out): Vec3

Adds two vectors and writes the result to out.

Parameters ​

a ​

Vec3

First vector

b ​

Vec3

Second vector

out ​

Vec3

Output vector

Returns ​

Vec3

out for chaining

back() ​

static back(): Vec3

Creates a back vector (0, 0, 1) in right-handed Y-up coordinate system.

Returns ​

Vec3

crossOut() ​

static crossOut(a, b, out): Vec3

Computes the cross product of two vectors and writes the result to out.

Parameters ​

a ​

Vec3

First vector

b ​

Vec3

Second vector

out ​

Vec3

Output vector

Returns ​

Vec3

out for chaining

down() ​

static down(): Vec3

Creates a down vector (0, -1, 0) in Y-up coordinate system.

Returns ​

Vec3

forward() ​

static forward(): Vec3

Creates a forward vector (0, 0, -1) in right-handed Y-up coordinate system.

Returns ​

Vec3

fromArray() ​

static fromArray(arr, offset?): Vec3

Creates a Vec3 from an array.

Parameters ​

arr ​

ArrayLike<number>

Source array

offset? ​

number = 0

Starting index in the array (default: 0)

Returns ​

Vec3

Throws ​

RangeError if array is too short

Example ​

ts
const arr = [1, 2, 3, 4, 5, 6];
const v1 = Vec3.fromArray(arr);       // Vec3(1, 2, 3)
const v2 = Vec3.fromArray(arr, 3);    // Vec3(4, 5, 6)

left() ​

static left(): Vec3

Creates a left vector (-1, 0, 0) in right-handed coordinate system.

Returns ​

Vec3

lerpOut() ​

static lerpOut(a, b, t, out): Vec3

Linearly interpolates between two vectors and writes the result to out.

Parameters ​

a ​

Vec3

Start vector

b ​

Vec3

End vector

t ​

number

Interpolation factor (0 = a, 1 = b)

out ​

Vec3

Output vector

Returns ​

Vec3

out for chaining

negateOut() ​

static negateOut(v, out): Vec3

Negates a vector and writes the result to out.

Parameters ​

v ​

Vec3

Vector to negate

out ​

Vec3

Output vector

Returns ​

Vec3

out for chaining

normalizeOut() ​

static normalizeOut(v, out): Vec3

Normalizes a vector and writes the result to out.

Parameters ​

v ​

Vec3

Vector to normalize

out ​

Vec3

Output vector

Returns ​

Vec3

out for chaining

one() ​

static one(): Vec3

Creates a unit vector (1, 1, 1).

Returns ​

Vec3

static right(): Vec3

Creates a right vector (1, 0, 0) in right-handed coordinate system.

Returns ​

Vec3

scaleOut() ​

static scaleOut(v, s, out): Vec3

Scales a vector and writes the result to out.

Parameters ​

v ​

Vec3

Vector to scale

s ​

number

Scalar value

out ​

Vec3

Output vector

Returns ​

Vec3

out for chaining

subOut() ​

static subOut(a, b, out): Vec3

Subtracts b from a and writes the result to out.

Parameters ​

a ​

Vec3

First vector

b ​

Vec3

Second vector

out ​

Vec3

Output vector

Returns ​

Vec3

out for chaining

unitX() ​

static unitX(): Vec3

Creates a unit X vector (1, 0, 0).

Returns ​

Vec3

unitY() ​

static unitY(): Vec3

Creates a unit Y vector (0, 1, 0).

Returns ​

Vec3

unitZ() ​

static unitZ(): Vec3

Creates a unit Z vector (0, 0, 1).

Returns ​

Vec3

up() ​

static up(): Vec3

Creates an up vector (0, 1, 0) in Y-up coordinate system.

Returns ​

Vec3

zero() ​

static zero(): Vec3

Creates a zero vector (0, 0, 0).

Returns ​

Vec3

Proprietary software. All rights reserved.

Copyright 2025-present Web Engine Dev