Math Helpers

pl.math3d provides vector, quaternion, and matrix operations for 3D scene work. All types are plain Lua tables — no special metatables required.

local math3d = pl.math3d

Type Conventions

-- vec3
{ x = 1.0, y = 2.0, z = 3.0 }
{ 1.0, 2.0, 3.0 }                -- positional shorthand

-- quat (quaternion)
{ x = 0, y = 0, z = 0, w = 1 }

-- mat4 (4×4 matrix, column-major, 16 floats)
{ 1,0,0,0, 0,1,0,0, 0,0,1,0, 0,0,0,1 }

-- color (RGBA, 0.0–1.0)
{ r = 1.0, g = 0.84, b = 0.0, a = 1.0 }

Vector Operations

local v = math3d.vec3(1, 2, 3)               -- create vec3

math3d.dot(a, b)                              -- dot product → number
math3d.cross(a, b)                            -- cross product → vec3
math3d.normalize(v)                           -- unit vector → vec3
math3d.length(v)                              -- magnitude → number
math3d.distance(a, b)                         -- distance between points → number
math3d.lerp(a, b, 0.5)                        -- linear interpolation → vec3

Examples

local forward = math3d.normalize({ x = 1, y = 0, z = 1 })
-- { x = 0.707, y = 0, z = 0.707 }

local up    = math3d.vec3(0, 1, 0)
local right = math3d.cross(forward, up)

local dist = math3d.distance(
    { x = 0, y = 0, z = 0 },
    { x = 3, y = 4, z = 0 }
)
-- 5.0

Quaternion Operations

math3d.quat_identity()                        -- {0, 0, 0, 1}
math3d.quat_from_euler(x, y, z)               -- degrees → quat
math3d.quat_from_axis_angle(axis, radians)    -- axis-angle → quat
math3d.quat_slerp(a, b, t)                    -- spherical lerp → quat

Examples

-- Rotate 45° around Y axis
local rot = math3d.quat_from_euler(0, 45, 0)

-- Rotate 90° around arbitrary axis
local axis = math3d.normalize({ x = 1, y = 1, z = 0 })
local rot2 = math3d.quat_from_axis_angle(axis, math.rad(90))

-- Smooth rotation blend
local a = math3d.quat_from_euler(0, 0, 0)
local b = math3d.quat_from_euler(0, 180, 0)
local mid = math3d.quat_slerp(a, b, 0.5)   -- halfway rotation

Matrix Operations

-- Creation
math3d.mat4_identity()                        -- identity matrix
math3d.mat4_translate(x, y, z)                -- translation matrix
math3d.mat4_rotate(quat)                       -- rotation matrix from quaternion
math3d.mat4_scale(x, y, z)                    -- scale matrix

-- View & projection
math3d.mat4_look_at(eye, target, up)          -- view matrix
math3d.mat4_perspective(fov, aspect, near, far)  -- perspective projection
math3d.mat4_ortho(left, right, bottom, top, near, far)  -- orthographic

-- Arithmetic
math3d.mat4_mul(a, b)                          -- multiply two matrices → mat4
math3d.mat4_inverse(m)                         -- inverse of matrix → mat4

Examples

-- Build a model matrix: translate, then rotate, then scale
local T = math3d.mat4_translate(2, 0, -5)
local R = math3d.mat4_rotate(math3d.quat_from_euler(0, 45, 0))
local S = math3d.mat4_scale(0.5, 0.5, 0.5)

-- Apply in order: scale → rotate → translate (right to left)
local model = math3d.mat4_mul(T, math3d.mat4_mul(R, S))

-- Build a view matrix
local view = math3d.mat4_look_at(
    { x = 0, y = 1.6, z = 5 },    -- eye
    { x = 0, y = 1, z = 0 },      -- target
    { x = 0, y = 1, z = 0 }       -- up
)

-- Perspective projection
local proj = math3d.mat4_perspective(
    math.rad(50),    -- vertical FOV
    16 / 9,          -- aspect ratio
    0.1,             -- near plane
    1000             -- far plane
)

Quick Reference

Function	Input	Output	Description
`vec3(x,y,z)`	numbers	vec3	Create vector
`dot(a,b)`	vec3, vec3	number	Dot product
`cross(a,b)`	vec3, vec3	vec3	Cross product
`normalize(v)`	vec3	vec3	Unit vector
`length(v)`	vec3	number	Magnitude
`distance(a,b)`	vec3, vec3	number	Distance
`lerp(a,b,t)`	vec3, vec3, number	vec3	Linear interpolation
`quat_identity()`	—	quat	Identity quaternion
`quat_from_euler(x,y,z)`	degrees	quat	Euler → quaternion
`quat_from_axis_angle(axis,rad)`	vec3, number	quat	Axis-angle → quaternion
`quat_slerp(a,b,t)`	quat, quat, number	quat	Spherical interpolation
`mat4_identity()`	—	mat4	Identity matrix
`mat4_translate(x,y,z)`	numbers	mat4	Translation
`mat4_rotate(q)`	quat	mat4	Rotation
`mat4_scale(x,y,z)`	numbers	mat4	Scale
`mat4_look_at(eye,target,up)`	vec3×3	mat4	View matrix
`mat4_perspective(fov,a,n,f)`	numbers	mat4	Perspective projection
`mat4_ortho(l,r,b,t,n,f)`	numbers	mat4	Orthographic projection
`mat4_mul(a,b)`	mat4×2	mat4	Matrix multiply
`mat4_inverse(m)`	mat4	mat4	Matrix inverse