mathlib Reference

Module defined in lua/common/mathlib.lua. Core math library providing vec3 and quat types with operator overloading, plus extensive geometry utilities (ray intersections, OBB tests, splines, etc.). All types are FFI-backed for performance.

Exports

All exports are global functions and types (no module table).

vec3 - 3D Vector

`vec3(x, y, z)` / `vec3(table)` / `vec3(vec3)`

Constructor. Accepts numbers, tables with x/y/z or [1]/[2]/[3] keys, or another vec3.

Returns: vec3

Operators: +, -, * (scalar or component), / (scalar), ==, unary -

Core Methods:

v:set(x, y, z) / v:set(other) - Set components
v:xyz() → x, y, z - Unpack components
v:copy() → vec3 - Clone
v:length() → number / v:squaredLength() → number
v:normalize() - In-place normalize / v:normalized() → vec3
v:resize(len) - In-place resize / v:resized(len) → vec3
v:dot(other) → number / v:cross(other) → vec3
v:distance(other) → number / v:squaredDistance(other) → number
v:cosAngle(other) → number - Cosine of angle between vectors
v:slerp(b, t) → vec3 - Spherical interpolation

Geometry Methods:

v:distanceToLine(a, b) / v:distanceToLineSegment(a, b) → number
v:squaredDistanceToLineSegment(a, b) → number
v:xnormOnLine(a, b) → number - Normalized position along line
v:xnormDistanceToLineSegment(a, b) → xnorm, dist
v:triangleClosestPoint(a, b, c) → vec3, u, v
v:triangleBarycentricNorm(a, b, c) → u, v (barycentric coords)
v:inPolygon(...) → boolean - Point-in-polygon test
v:projectToOriginPlane(pnorm) → vec3
v:xnormPlaneWithLine(pnorm, a, b) → number - Ray-plane intersection
v:xnormsSphereWithLine(radius, a, b) → xnorm1, xnorm2
v:basisCoordinates(c1, c2, c3) → vec3 - Transform to basis

Mutation Methods: v:setAdd(a), v:setSub(a), v:setScaled(s), v:setMin(a), v:setMax(a), v:setLerp(a, b, t), v:setAdd2(a, b), v:componentMul(b)

Conversion: v:toTable(), v:toDict(), v:setFromTable(t), v:fromString(s), v:__tostring()

quat - Quaternion

`quat(x, y, z, w)` / `quat(table)` / `quat()`

Constructor. No-args returns identity quat(1, 0, 0, 0). Table form accepts {x,y,z,w} (array) or {x=,y=,z=,w=} (dict).

Returns: quat
Note: Uses Torque3D convention where -w represents the rotation angle component

Operators: * (quat×quat or quat×vec3), +, -, /

Core Methods:

q:set(x, y, z, w) - Set components
q:xyzw() → x, y, z, w
q:dot(other) → number / q:distance(other) → number
q:nlerp(a, t) → quat - Normalized linear interpolation
q:slerp(a, t) → quat - Spherical interpolation
q:conjugated() → quat
q:normalize() - In-place / q:normalized() → quat

Construction:

q:setFromAxisAngle(axle, angleRad) / quatFromAxisAngle(axle, angleRad) → quat
q:setRotationFromTo(fromV, toV) - Rotation from one direction to another
q:setFromEuler(x, y, z) / quatFromEuler(x, y, z) → quat - Radians
q:setFromDir(dir, up) / quatFromDir(dir, up) → quat

Conversion:

q:toEulerYXZ() → vec3 - Euler angles as a vec3 (not three separate values)
q:toTorqueQuat() → QuatF - Engine QuatF
q:toDirUp() → dir, up - Forward and up vectors

Scalar Math Functions

`sign(x)` → -1, 0, or 1

`sign2(x)` → -1 or 1 (no zero)

`clamp(x, min, max)` → number

`square(a)` → number

`round(a)` → number

`roundNear(x, m)` → number - Round to nearest multiple

`isnan(a)` / `isinf(a)` / `isnaninf(a)` → boolean

`lerp(from, to, t)` → number

`inverseLerp(from, to, value)` → number

`linearScale(v, minV, maxV, minO, maxO)` → number - Clamped remap

`rescale(v, minV, maxV, minO, maxO)` → number - Unclamped remap

`smoothstep(x)` / `smootherstep(x)` / `smootheststep(x)` → number

`smoothmin(a, b, k)` / `smoothmax(a, b, k)` → number

`biasFun(x, k)` / `biasGainFun(x, t, s)` → number

`sigmoid1(x, a)` → number

`bumpFun(x, peakLeftX, peakRightX, leftSlope, rightSlope, leftY, peakY, rightY, roundness)` → number

Spline Functions

`catmullRom(p0, p1, p2, p3, t, s)` → vec3

`catmullRomChordal(p0, p1, p2, p3, t, s)` → vec3

`catmullRomCentripetal(p0, p1, p2, p3, t, s)` → vec3

`cardinalSpline(p0, p1, p2, p3, t, s, d1, d2, d3)` → vec3

`monotonicSteffen(y0..y3, x0..x3, x)` → number

`quadraticBezier(p1, p2, p3, t)` → vec3

`conicBezier(p1, p2, p3, t, w)` → vec3

`biQuadratic(p0, p1, p2, p3, t)` → vec3

Geometry / Intersection Functions

`overlapsOBB_OBB(c1, x1, y1, z1, c2, x2, y2, z2)` → boolean

`containsOBB_OBB(c1, x1, y1, z1, c2, x2, y2, z2)` → boolean

`containsOBB_Sphere(c1, x1, y1, z1, c2, r2)` / `containsSphere_OBB(...)` / `containsOBB_point(...)` → boolean

`containsEllipsoid_Point(c1, x1, y1, z1, p)` → boolean

`overlapsOBB_Sphere(c1, x1, y1, z1, c2, r2)` / `overlapsOBB_Plane(...)` → boolean

`intersectsRay_Plane(rpos, rdir, plpos, pln)` → number - signed distance along ray (clamped to `math.huge`, never nil)

`intersectsRay_OBB(rpos, rdir, c1, x1, y1, z1)` → minhit, maxhit - hit when `minhit <= maxhit and maxhit > 0`; returns `math.huge` on miss

`intersectsRay_Sphere(rpos, rdir, cpos, cr)` → minhit, maxhit - two intersection distances; returns `math.huge, math.huge` on miss

`intersectsRay_Ellipsoid(rpos, rdir, c1, x1, y1, z1)` → minhit, maxhit - two intersection distances; returns `math.huge, math.huge` on miss

`intersectsRay_Cylinder(rpos, rdir, cposa, cposb, cR)` → minhit, maxhit - capped cylinder intersection; returns `math.huge` on miss

`intersectsRay_Capsule(rpos, rdir, cposa, cposb, cR)` → number - first hit distance; returns `math.huge` on miss (single return value)

`intersectsRay_Triangle(rpos, rdir, a, b, c)` → dist, baryU, baryV - hit distance and barycentric coords; returns `math.huge, -1, -1` on miss

`OBBsquaredDistance(c1, x1, y1, z1, p)` → number

Bounding Box Utilities

`pointBB2d(x, y, radius)` → xmin, ymin, xmax, ymax

`lineBB2d(x1, y1, x2, y2, radius)` → xmin, ymin, xmax, ymax

`median3(a,b,c)` / `median4(...)` / `median5(...)` → number

vec3 Operator Overloads

`vec3 + vec3` (`__add`)

Component-wise addition. Returns a new vec3.

`vec3 - vec3` (`__sub`)

Component-wise subtraction. Returns a new vec3.

`-vec3` (`__unm`)

Negation. Returns a new vec3 with all components negated.

`vec3 * scalar` / `scalar * vec3` (`__mul`)

Scalar multiplication. Returns a new vec3.

`vec3 / scalar` (`__div`)

Scalar division. Returns a new vec3.

`vec3 == vec3` (`__eq`)

Component-wise equality check. Returns boolean.

vec3 Aliases

`vec3.toPoint3F`

Alias for vec3.toFloat3.

`vec3.lenSquared`

Alias for vec3.squaredLength.

`vec3.normalizeSafe`

Alias for vec3.normalize.

Additional vec3 Methods

`vec3:componentMul(b)`

(line in source)

`vec3:distanceToLineSegment(a, b)`

(line in source)

`vec3:fromString(s)`

(line in source)

`vec3:getAxis(i)`

(line in source)

`vec3:getBlueNoise2d()`

(line in source)

`vec3:getBlueNoise3d()`

(line in source)

`vec3:getBluePointInCircle(radius)`

(line in source)

`vec3:getBluePointInSphere(radius)`

(line in source)

`vec3:getRandomPointInCircle(radius)`

(line in source)

`vec3:getRandomPointInSphere(radius)`

(line in source)

`vec3:getRotationTo(toV)`

(line in source)

`vec3:invBilinear2D(a1, a2, b1, b2)`

(line in source)

`vec3:lengthGuarded()`

(line in source)

`vec3:perpendicular()`

(line in source)

`vec3:perpendicularN()`

(line in source)

`vec3:ropeRock(cutOff)`

(line in source)

`vec3:rotated(q)`

(line in source)

`vec3:setAdd(a)`

(line in source)

`vec3:setAdd2(a, b)`

(line in source)

`vec3:setAddXYZ(x, y, z)`

(line in source)

`vec3:setAxis(i, v)`

(line in source)

`vec3:setComponentMul(a)`

(line in source)

`vec3:setCross(a, b)`

(line in source)

`vec3:setEulerYXZ(q)`

(line in source)

`vec3:setFromTable(t)`

(line in source)

`vec3:setLerp(from, to, t)`

(line in source)

`vec3:setMax(a)`

(line in source)

`vec3:setMin(a)`

(line in source)

`vec3:setPerpendicular(a)`

(line in source)

`vec3:setProjectToOriginPlane(pnorm, a)`

(line in source)

`vec3:setRotate(q, a)`

(line in source)

`vec3:setScaled(b)`

(line in source)

`vec3:setScaled2(a, b)`

(line in source)

`vec3:setSub(a)`

(line in source)

`vec3:setSub2(a, b)`

(line in source)

`vec3:setToBase(nx, ny, nz)`

(line in source)

`vec3:setTrianglePointFromUV(a, b, c, u, v)`

(line in source)

`vec3:squaredDistanceToLine(a, b)`

(line in source)

`vec3:toBase(nx, ny, nz)`

(line in source)

`vec3:toFloat3()`

(line in source)

`vec3:triangleClosestPointUV(a, b, c)`

(line in source)

`vec3:xnormSquaredDistanceToLineSegment(a, b)`

(line in source)

`vec3:xy()`

(line in source)

Additional quat Methods

`quat:inverse()`

(see source)

`quat:inversed()`

(see source)

`quat:norm()`

(see source)

`quat:normalized()`

(see source)

`quat:scale(a)`

(see source)

`quat:setInvMul2(a, b)`

(see source)

`quat:setMul2(a, b)`

(see source)

`quat:setMulInv2(a, b)`

(see source)

`quat:setMulXYZW(ax, ay, az, aw, bx, by, bz, bw)`

(see source)

`quat:squaredNorm()`

(see source)

`quat:toDict()`

(see source)

`quat:toTable()`

(see source)

Additional Global Math Functions

`altitudeOBB_Plane(c1, x1, y1, z1, plpos, pln)`

Returns the altitude (signed distance) of an OBB above a plane.

`biasGainFun(x, t, s)`

Combined bias and gain curve function.

`closestLinePoints(l1p1, l1p2, l2p1, l2p2)`

Finds the closest points between two infinite lines.

`closestLineSegmentPoints(l1p1, l1p2, l2p1, l2p2)`

Finds the closest points between two line segments.

`constainsCylinder_Point(cposa, cposb, cR, p)`

Tests if a point is inside a cylinder.

`containsOBB_point(c1, x1, y1, z1, p)`

Tests if a point is inside an OBB.

`containsSphere_OBB(c1, r1, c2, x2, y2, z2)`

Tests if a sphere fully contains an OBB.

`getBlueNoise1d(x)`

Returns a 1D blue noise value for the given input.

`guardZero(x)`

Returns x if non-zero, otherwise returns a tiny epsilon value (branchless).

`isinf(a)`

Returns true if the value is infinite.

`isnaninf(a)`

Returns true if the value is NaN or infinite.

`linePointFromXnorm(p0, p1, xnorm)`

Returns a point on a line segment at normalized position xnorm.

`median4(a,b,c,d)`

Returns the median of 4 values.

`median5(a,b,c,d,e)`

Returns the median of 5 values.

`nanError(x)`

Raises an error if the value is NaN.

`overlapsOBB_Plane(c1, x1, y1, z1, plpos, pln)`

Tests if an OBB overlaps with a plane.

`push3(x, y, z)`

Creates a stack-allocated vec3 (StackVec3) for temporary calculations.

`quatFromAxisAngle(axle, angleRad)`

(see source for details)

`quatFromDir(dir, up)`

(see source for details)

`quatFromEuler(x, y, z)`

(see source for details)

`randomGauss3()`

Returns a number (sum of 3 math.random() calls), range approximately [0..3]. NOT a vector despite the name.

`randomState(v)`

Returns a deterministic random state from a seed value.

`signApply(s, v)`

(see source for details)

`smootherstep(x)`

(see source for details)

`smootheststep(x)`

(see source for details)

`smoothmax(a, b, k)`

(see source for details)

StackVec3 Methods

Lightweight stack-allocated 3D vectors created via push3(). Use a shared stack internally - each result must be consumed (via :xyz(), :copy(), or another method that pops) before using another push3. Support basic arithmetic operators (+, -, *, /, unary -).

Methods that pop (consume the stack entry):

StackVec3:xyz() → x, y, z
StackVec3:copy() → vec3
StackVec3:dot(a) → number
StackVec3:length() → number
StackVec3:squaredLength() → number
StackVec3:distance(a) → number
StackVec3:squaredDistance(a) → number

Methods that stay on stack (chainable):

StackVec3:cross(b) → StackVec3
StackVec3:resized(m) → StackVec3
StackVec3:normalized() → StackVec3
StackVec3:z0() → StackVec3

vec3 and quat are backed by FFI structs (__luaVec3_t, __luaQuat_t) with double precision
Falls back to plain Lua tables if FFI is unavailable
Temporary vec3 variables tmpv1, tmpv2, tmpv3 are reused internally to minimize allocation
quat * vec3 rotates the vector (using -w convention); quat * quat composes rotations
OBB functions use center + half-extents representation: c = center vec3, x/y/z = axis half-extent vec3s

mathlib Reference

On this page