Web Engine Dev

Appearance

@web-engine-dev/math

@web-engine-dev/math / MathUtils

Variable: MathUtils ​

const MathUtils: object

Common mathematical utility functions for game development. Includes interpolation, clamping, angle conversions, and geometric utilities.

Type Declaration ​

DEG_TO_RAD ​

DEG_TO_RAD: number

Degrees to radians multiplier

EPSILON ​

EPSILON: number = 1e-6

Small epsilon for floating point comparisons

HALF_PI ​

HALF_PI: number

Half PI (90 degrees in radians)

PI ​

PI: number = Math.PI

PI constant

RAD_TO_DEG ​

RAD_TO_DEG: number

Radians to degrees multiplier

TWO_PI ​

TWO_PI: number

Two PI (full circle in radians)

angleDifference() ​

angleDifference(from, to): number

Returns the shortest angular distance between two angles (in radians). Result is in range [-PI, PI].

Parameters ​

from ​

number

to ​

number

Returns ​

number

approximately() ​

approximately(a, b, epsilon?): boolean

Checks if two numbers are approximately equal.

Parameters ​

a ​

number

b ​

number

epsilon? ​

number = 1e-6

Returns ​

boolean

barycentricCoords2D() ​

barycentricCoords2D(p, a, b, c): Vec3

Computes barycentric coordinates of a point relative to a triangle (2D).

Parameters ​

p ​

Vec2

Point to compute coordinates for

a ​

Vec2

Triangle vertex A

b ​

Vec2

Triangle vertex B

c ​

Vec2

Triangle vertex C

Returns ​

Vec3

Vec3 with barycentric coordinates (u, v, w) where p = ua + vb + w*c

barycentricCoords3D() ​

barycentricCoords3D(p, a, b, c): Vec3

Computes barycentric coordinates of a point relative to a triangle (3D).

Parameters ​

p ​

Vec3

Point to compute coordinates for

a ​

Vec3

Triangle vertex A

b ​

Vec3

Triangle vertex B

c ​

Vec3

Triangle vertex C

Returns ​

Vec3

Vec3 with barycentric coordinates (u, v, w) where p = ua + vb + w*c

barycentricInterpolate() ​

barycentricInterpolate(bary, valueA, valueB, valueC): number

Interpolates a value using barycentric coordinates.

Parameters ​

bary ​

Vec3

valueA ​

number

valueB ​

number

valueC ​

number

Returns ​

number

barycentricInterpolateVec3() ​

barycentricInterpolateVec3(bary, valueA, valueB, valueC): Vec3

Interpolates a Vec3 using barycentric coordinates.

Parameters ​

bary ​

Vec3

valueA ​

Vec3

valueB ​

Vec3

valueC ​

Vec3

Returns ​

Vec3

bezierCubic() ​

bezierCubic(p0, p1, p2, p3, t): number

Evaluates a cubic Bezier curve at parameter t.

Parameters ​

p0 ​

number

Start point

p1 ​

number

First control point

p2 ​

number

Second control point

p3 ​

number

End point

t ​

number

Parameter (0-1)

Returns ​

number

bezierCubicTangent() ​

bezierCubicTangent(p0, p1, p2, p3, t): number

Evaluates the tangent (derivative) of a cubic Bezier curve at t.

Parameters ​

p0 ​

number

p1 ​

number

p2 ​

number

p3 ​

number

t ​

number

Returns ​

number

bezierCubicTangentVec3() ​

bezierCubicTangentVec3(p0, p1, p2, p3, t): Vec3

Evaluates a cubic Bezier tangent for Vec3.

Parameters ​

p0 ​

Vec3

p1 ​

Vec3

p2 ​

Vec3

p3 ​

Vec3

t ​

number

Returns ​

Vec3

bezierCubicVec2() ​

bezierCubicVec2(p0, p1, p2, p3, t): Vec2

Evaluates a cubic Bezier curve for Vec2.

Parameters ​

p0 ​

Vec2

p1 ​

Vec2

p2 ​

Vec2

p3 ​

Vec2

t ​

number

Returns ​

Vec2

bezierCubicVec3() ​

bezierCubicVec3(p0, p1, p2, p3, t): Vec3

Evaluates a cubic Bezier curve for Vec3.

Parameters ​

p0 ​

Vec3

p1 ​

Vec3

p2 ​

Vec3

p3 ​

Vec3

t ​

number

Returns ​

Vec3

bezierQuadratic() ​

bezierQuadratic(p0, p1, p2, t): number

Evaluates a quadratic Bezier curve at parameter t.

Parameters ​

p0 ​

number

Start point

p1 ​

number

Control point

p2 ​

number

End point

t ​

number

Parameter (0-1)

Returns ​

number

bezierQuadraticTangent() ​

bezierQuadraticTangent(p0, p1, p2, t): number

Evaluates the tangent (derivative) of a quadratic Bezier curve at t.

Parameters ​

p0 ​

number

p1 ​

number

p2 ​

number

t ​

number

Returns ​

number

bezierQuadraticVec2() ​

bezierQuadraticVec2(p0, p1, p2, t): Vec2

Evaluates a quadratic Bezier curve for Vec2.

Parameters ​

p0 ​

Vec2

p1 ​

Vec2

p2 ​

Vec2

t ​

number

Returns ​

Vec2

bezierQuadraticVec3() ​

bezierQuadraticVec3(p0, p1, p2, t): Vec3

Evaluates a quadratic Bezier curve for Vec3.

Parameters ​

p0 ​

Vec3

p1 ​

Vec3

p2 ​

Vec3

t ​

number

Returns ​

Vec3

catmullRom() ​

catmullRom(p0, p1, p2, p3, t, alpha?): number

Evaluates a Catmull-Rom spline at parameter t.

Parameters ​

p0 ​

number

Point before segment start

p1 ​

number

Segment start point

p2 ​

number

Segment end point

p3 ​

number

Point after segment end

t ​

number

Parameter (0-1) within the p1-p2 segment

alpha? ​

number = 0.5

Tension parameter (0.5 = centripetal, 0 = uniform, 1 = chordal)

Returns ​

number

catmullRomVec3() ​

catmullRomVec3(p0, p1, p2, p3, t, tension?): Vec3

Evaluates a Catmull-Rom spline for Vec3.

Parameters ​

p0 ​

Vec3

p1 ​

Vec3

p2 ​

Vec3

p3 ​

Vec3

t ​

number

tension? ​

number = 0.5

Returns ​

Vec3

clamp() ​

clamp(value, min, max): number

Clamps a value between min and max.

Parameters ​

value ​

number

min ​

number

max ​

number

Returns ​

number

clamp01() ​

clamp01(value): number

Clamps a value to [0, 1].

Parameters ​

value ​

number

Returns ​

number

closestPointOnLineSegment() ​

closestPointOnLineSegment(point, segStart, segEnd): Vec3

Computes the closest point on a line segment to a point.

Parameters ​

point ​

Vec3

segStart ​

Vec3

segEnd ​

Vec3

Returns ​

Vec3

damp() ​

damp(current, target, decay, deltaTime): number

Exponential decay interpolation (frame-rate independent smoothing).

Parameters ​

current ​

number

Current value

target ​

number

Target value

decay ​

number

Decay rate (higher = faster, typical range 1-25)

deltaTime ​

number

Time step

Returns ​

number

Example ​

ts
// Smooth camera follow (frame-rate independent)
camera.x = MathUtils.damp(camera.x, target.x, 10, deltaTime);

degToRad() ​

degToRad(degrees): number

Converts degrees to radians.

Parameters ​

degrees ​

number

Returns ​

number

distanceToLineSegment() ​

distanceToLineSegment(point, segStart, segEnd): number

Computes the distance from a point to a line segment.

Parameters ​

point ​

Vec3

segStart ​

Vec3

segEnd ​

Vec3

Returns ​

number

easeInCubic() ​

easeInCubic(t): number

Cubic ease-in.

Parameters ​

t ​

number

Returns ​

number

easeInExpo() ​

easeInExpo(t): number

Exponential ease-in.

Parameters ​

t ​

number

Returns ​

number

easeInOutCubic() ​

easeInOutCubic(t): number

Cubic ease-in-out.

Parameters ​

t ​

number

Returns ​

number

easeInOutQuad() ​

easeInOutQuad(t): number

Quadratic ease-in-out.

Parameters ​

t ​

number

Returns ​

number

easeInOutSine() ​

easeInOutSine(t): number

Sine ease-in-out.

Parameters ​

t ​

number

Returns ​

number

easeInQuad() ​

easeInQuad(t): number

Quadratic ease-in.

Parameters ​

t ​

number

Returns ​

number

easeInSine() ​

easeInSine(t): number

Sine ease-in.

Parameters ​

t ​

number

Returns ​

number

easeOutBounce() ​

easeOutBounce(t): number

Bounce ease-out.

Parameters ​

t ​

number

Returns ​

number

easeOutCubic() ​

easeOutCubic(t): number

Cubic ease-out.

Parameters ​

t ​

number

Returns ​

number

easeOutElastic() ​

easeOutElastic(t): number

Elastic ease-out (bounce at end).

Parameters ​

t ​

number

Returns ​

number

easeOutExpo() ​

easeOutExpo(t): number

Exponential ease-out.

Parameters ​

t ​

number

Returns ​

number

easeOutQuad() ​

easeOutQuad(t): number

Quadratic ease-out.

Parameters ​

t ​

number

Returns ​

number

easeOutSine() ​

easeOutSine(t): number

Sine ease-out.

Parameters ​

t ​

number

Returns ​

number

fract() ​

fract(value): number

Returns the fractional part of a number.

Parameters ​

value ​

number

Returns ​

number

inverseLerp() ​

inverseLerp(a, b, value): number

Inverse linear interpolation: returns t such that lerp(a, b, t) = value.

Parameters ​

a ​

number

b ​

number

value ​

number

Returns ​

number

isInsideTriangle() ​

isInsideTriangle(bary): boolean

Checks if barycentric coordinates represent a point inside the triangle.

Parameters ​

bary ​

Vec3

Returns ​

boolean

isNegative() ​

isNegative(value, epsilon?): boolean

Checks if a number is negative (less than -epsilon).

Parameters ​

value ​

number

epsilon? ​

number = 1e-6

Returns ​

boolean

isPositive() ​

isPositive(value, epsilon?): boolean

Checks if a number is positive (greater than epsilon).

Parameters ​

value ​

number

epsilon? ​

number = 1e-6

Returns ​

boolean

isZero() ​

isZero(value, epsilon?): boolean

Checks if a number is approximately zero.

Parameters ​

value ​

number

epsilon? ​

number = 1e-6

Returns ​

boolean

lerp() ​

lerp(a, b, t): number

Linear interpolation between two values.

Parameters ​

a ​

number

b ​

number

t ​

number

Returns ​

number

lerpAngle() ​

lerpAngle(from, to, t): number

Linear interpolation of angles, taking the shortest path.

Parameters ​

from ​

number

to ​

number

t ​

number

Returns ​

number

linearStep() ​

linearStep(edge0, edge1, x): number

Linear step function: returns 0 below edge0, 1 above edge1, linear in between.

Parameters ​

edge0 ​

number

edge1 ​

number

x ​

number

Returns ​

number

moveTowards() ​

moveTowards(current, target, maxDelta): number

Moves a value towards a target by a maximum delta.

Parameters ​

current ​

number

target ​

number

maxDelta ​

number

Returns ​

number

normalizeAngle() ​

normalizeAngle(angle): number

Normalizes an angle to the range [-PI, PI].

Parameters ​

angle ​

number

Returns ​

number

normalizeAnglePositive() ​

normalizeAnglePositive(angle): number

Normalizes an angle to the range [0, 2*PI].

Parameters ​

angle ​

number

Returns ​

number

projectPointOnLine() ​

projectPointOnLine(point, lineStart, lineEnd): Vec3

Projects a 3D point onto a line defined by two points.

Parameters ​

point ​

Vec3

lineStart ​

Vec3

lineEnd ​

Vec3

Returns ​

Vec3

radToDeg() ​

radToDeg(radians): number

Converts radians to degrees.

Parameters ​

radians ​

number

Returns ​

number

randomInsideUnitCircle() ​

randomInsideUnitCircle(rng?): Vec2

Returns a random point inside a unit circle (2D).

Parameters ​

rng? ​

Optional seeded RNG for deterministic output

next ​

Returns ​

Vec2

randomInsideUnitSphere() ​

randomInsideUnitSphere(rng?): Vec3

Returns a random point inside a unit sphere.

Parameters ​

rng? ​

Optional seeded RNG for deterministic output

next ​

Returns ​

Vec3

randomInt() ​

randomInt(min, max, rng?): number

Returns a random integer in the range [min, max].

Parameters ​

min ​

number

Minimum value (inclusive)

max ​

number

Maximum value (inclusive)

rng? ​

Optional seeded RNG for deterministic output

next ​

Returns ​

number

randomRange() ​

randomRange(min, max, rng?): number

Returns a random float in the range [min, max).

Parameters ​

min ​

number

Minimum value (inclusive)

max ​

number

Maximum value (exclusive)

rng? ​

Optional seeded RNG for deterministic output

next ​

Returns ​

number

randomUnitVec2() ​

randomUnitVec2(rng?): Vec2

Returns a random unit Vec2.

Parameters ​

rng? ​

Optional seeded RNG for deterministic output

next ​

Returns ​

Vec2

randomUnitVec3() ​

randomUnitVec3(rng?): Vec3

Returns a random unit Vec3 (uniformly distributed on unit sphere).

Parameters ​

rng? ​

Optional seeded RNG for deterministic output

next ​

Returns ​

Vec3

randomVec2() ​

randomVec2(rng?): Vec2

Returns a random Vec2 with components in the range [-1, 1].

Parameters ​

rng? ​

Optional seeded RNG for deterministic output

next ​

Returns ​

Vec2

randomVec3() ​

randomVec3(rng?): Vec3

Returns a random Vec3 with components in the range [-1, 1].

Parameters ​

rng? ​

Optional seeded RNG for deterministic output

next ​

Returns ​

Vec3

remap() ​

remap(value, inMin, inMax, outMin, outMax): number

Remaps a value from one range to another.

Parameters ​

value ​

number

inMin ​

number

inMax ​

number

outMin ​

number

outMax ​

number

Returns ​

number

sign() ​

sign(value): number

Returns the sign of a number (-1, 0, or 1).

Parameters ​

value ​

number

Returns ​

number

smootherStep() ​

smootherStep(edge0, edge1, x): number

Smoother step interpolation (Ken Perlin's improved smoothstep).

Parameters ​

edge0 ​

number

edge1 ​

number

x ​

number

Returns ​

number

smoothStep() ​

smoothStep(edge0, edge1, x): number

Smooth step interpolation (Hermite interpolation). Returns 0 for x <= edge0, 1 for x >= edge1, smooth curve in between.

Parameters ​

edge0 ​

number

edge1 ​

number

x ​

number

Returns ​

number

Example ​

ts
// Fade in over distance 5-15
const alpha = MathUtils.smoothStep(5, 15, distance);

triangleArea2D() ​

triangleArea2D(a, b, c): number

Computes the area of a triangle given three 2D points.

Parameters ​

a ​

Vec2

b ​

Vec2

c ​

Vec2

Returns ​

number

triangleArea3D() ​

triangleArea3D(a, b, c): number

Computes the area of a triangle given three 3D points.

Parameters ​

a ​

Vec3

b ​

Vec3

c ​

Vec3

Returns ​

number

triangleCentroid() ​

triangleCentroid(a, b, c): Vec3

Computes the centroid of a triangle.

Parameters ​

a ​

Vec3

b ​

Vec3

c ​

Vec3

Returns ​

Vec3

triangleNormal() ​

triangleNormal(a, b, c): Vec3

Computes the normal of a triangle.

Parameters ​

a ​

Vec3

b ​

Vec3

c ​

Vec3

Returns ​

Vec3

Example ​

ts
// Angle conversion
const radians = MathUtils.degToRad(90);  // π/2

// Interpolation
const mid = MathUtils.lerp(0, 100, 0.5);  // 50
const smooth = MathUtils.smoothStep(0, 1, 0.5);  // Smooth curve

// Clamping
const clamped = MathUtils.clamp(150, 0, 100);  // 100

Proprietary software. All rights reserved.

Copyright 2025-present Web Engine Dev