@web-engine-dev/math

High-performance vector, matrix, and quaternion math library for game engines. Provides a three-tier API: immutable (safe), mutable (fast), and out-parameter (zero-allocation hot paths).

Layer 0 · Foundation (zero dependencies)

Features

• Vectors: Vec2, Vec3, Vec4 for 2D/3D/4D operations
• Matrices: Mat3, Mat4 for transformations
• Quaternions: Quat for rotation representation
• Transforms: Combined position, rotation, scale
• Geometry: AABB, Plane, Frustum, Ray, Sphere for spatial calculations
• Color: Color class with HSL/RGB/hex conversions and color spaces
• Three-Tier API: Immutable (safe), mutable (.addSelf()), out-parameter (Vec3.addOut(a, b, out))
• SIMD-Ready Layout: Float32Array-backed storage for GPU upload compatibility
• BatchMath: Vectorized operations on typed arrays (SOA layout)
• MathPool: Per-frame temp allocator — grab temporaries, release at frame end

Installation

npm install @web-engine-dev/math
# or
pnpm add @web-engine-dev/math

Quick Start

import { Vec3, Mat4, Quat, Transform } from '@web-engine-dev/math';

// Vectors
const position = new Vec3(0, 1, 0);
const velocity = new Vec3(1, 0, 0);
const newPosition = position.add(velocity.scale(deltaTime));

// Matrices
const projection = Mat4.perspective(Math.PI / 4, aspect, 0.1, 1000);
const view = Mat4.lookAt(eye, target, up);
const mvp = projection.multiply(view).multiply(model);

// Quaternions
const rotation = Quat.fromAxisAngle(Vec3.UP, Math.PI / 2);
const rotated = rotation.mulVec3(forward);

// Transforms
const transform = new Transform(position, rotation, Vec3.ONE);
const worldMatrix = transform.toMat4();

API Overview

Vectors

// Vec2
const v2 = new Vec2(x, y);
v2.add(other); // Vector addition
v2.sub(other); // Vector subtraction
v2.scale(s); // Scalar multiplication
v2.dot(other); // Dot product
v2.length(); // Magnitude
v2.normalize(); // Unit vector

// Vec3
const v3 = new Vec3(x, y, z);
v3.cross(other); // Cross product
Vec3.lerp(a, b, t); // Linear interpolation

// Vec4
const v4 = new Vec4(x, y, z, w);

Matrices

// Mat4
Mat4.identity();
Mat4.translation(x, y, z);
Mat4.rotation(quat);
Mat4.scale(x, y, z);
Mat4.perspective(fov, aspect, near, far);
Mat4.orthographic(left, right, bottom, top, near, far);
Mat4.lookAt(eye, target, up);

mat.multiply(other);
mat.invert();
mat.transpose();
mat.transformPoint(vec3);
mat.transformVector(vec3);

Quaternions

Quat.identity();
Quat.fromAxisAngle(axis, angle);
Quat.fromEuler(x, y, z);
Quat.slerp(a, b, t);

quat.multiply(other);
quat.conjugate();
quat.mulVec3(vec);
quat.toMat4();

Geometry

// AABB (Axis-Aligned Bounding Box)
const aabb = new AABB(min, max);
aabb.contains(point);
aabb.intersects(other);
aabb.expand(point);

// Plane
const plane = new Plane(normal, distance);
plane.distanceToPoint(point);

// Frustum
const frustum = new Frustum(planes);
frustum.containsPoint(point);
frustum.intersectsAABB(aabb);

Three-Tier API

Choose the right tier for your use case:

// Tier 1: Immutable (safe, readable — general gameplay code)
const c = a.add(b); // Returns new Vec3

// Tier 2: Mutable (faster — systems with many operations)
a.addSelf(b); // Mutates `a` in place

// Tier 3: Out-parameter (zero allocation — hot inner loops)
Vec3.addOut(a, b, out); // Writes result into `out`

BatchMath & MathPool

import { BatchMath, MathPool } from '@web-engine-dev/math';

// BatchMath: operate on typed arrays (SOA layout)
BatchMath.addVec3(positionsA, positionsB, result, count);

// MathPool: per-frame temp allocator
const tmp = MathPool.vec3(); // Grab a temporary
// ... use tmp ...
MathPool.release(); // Release all temporaries at frame end