MEK(Math Essentials and Kinematics)

A zero-dependency, lightweight, high-performance 2D math, geometry, and spatial utility library written in pure Lua.

Designed for LÖVE2D projects, and general games and software developed in Lua.

---

Features

• Zero External Dependencies: Runs on standard Lua 5.1+, LuaJIT, or LÖVE2D out of the box.
• 2D Vector Math: Basic arithmetic, dot/cross products, normalization, distance calculations, and angle computations.
• Deterministic PRNG: Fast Linear Congruential Generator (LCG) for seedable pseudo-random numbers.
• Interpolation & Easing: Linear interpolation (lerp), clamping, mapping, and step functions.
• Array Statistics: Min/max, mean, median, sum, and array manipulation helpers.
• Geometry & Collision Helpers: Point-in-polygon tests, raycast/line-segment proximity, box/circle bounds testing, and capsule helpers.
• Polygon Utilities: Vertices transformation, area, centroid calculations, and scale/rotation transforms around custom pivots.
• Affine Transformations: 3x3 matrix math for 2D positioning, rotation, and scaling.

---

Installation

Simply drop mek.lua into your project directory or library folder and require it:

local m = require("path.to.mek")

API Reference

Below is a handful of common math helpers that mek provides

1. Basic Math & Utilities

Function	Signature	Description
m.clamp	m.clamp(val, min, max)	Clamps a number between min and max.
m.lerp	m.lerp(a, b, t)	Linearly interpolates between a and b by factor t.
m.map	m.map(val, inMin, inMax, outMin, outMax)	Maps a value from one numeric range to another.
m.sign	m.sign(val)	Returns 1 for positive numbers, -1 for negative, and 0 for zero.
m.round	m.round(val, decimals)	Rounds a float to a given number of decimal places.

---

2. Vectors & Distance Operations

Function	Signature	Description
m.dist	m.dist(x1, y1, x2, y2)	Calculates Euclidean distance between two points.
m.distSq	m.distSq(x1, y1, x2, y2)	Calculates squared distance (avoids expensive sqrt calls).
m.dot	m.dot(x1, y1, x2, y2)	Returns the dot product of two 2D vectors.
m.cross	m.cross(x1, y1, x2, y2)	Returns the 2D cross product magnitude (scalar Z value).
m.normalize	m.normalize(x, y)	Returns normalized unit vector (nx, ny) and its original magnitude.
m.angle	m.angle(x1, y1, x2, y2)	Returns the angle in radians from point 1 to point 2 (atan2).

---

3. Spatial Queries & Collisions

Function	Signature	Description
m.pointInPolygon	m.pointInPolygon(px, py, vertices)	Tests if point (px, py) lies inside a closed polygon {{x1,y1}, ...} via ray-casting.
m.pointNearSegment	m.pointNearSegment(px, py, ax, ay, bx, by, tol)	Tests if point (px, py) is within tol distance of line segment AB.

---

4. Shape & Polygon Transforms

Function	Signature	Description
m.getCentroid	m.getCentroid(vertices)	Computes the center of mass (cx, cy) for a list of vertices.
m.getArea	m.getArea(vertices)	Calculates total polygon area using the Shoelace algorithm.
m.rotatePoint	m.rotatePoint(px, py, cx, cy, angle)	Rotates point (px, py) around pivot (cx, cy) by angle radians.
m.scalePoint	m.scalePoint(px, py, cx, cy, scale)	Scales point (px, py) relative to origin point (cx, cy).

---

5. Affine Matrix (3x3) Operations

Function / Method	Signature	Description
m.matrix3	m.matrix3()	Instantiates a new 3x3 identity transformation matrix.
:translate	mat:translate(tx, ty)	Chains a 2D translation transform to the matrix.
:rotate	mat:rotate(angle)	Chains a rotation transform (in radians) to the matrix.
:scale	mat:scale(sx, sy)	Chains a 2D scale transform to the matrix.
:transformPoint	mat:transformPoint(x, y)	Applies matrix transformations to a point and returns transformed (tx, ty).

---

6. Deterministic PRNG (Random Number Generator)

Function / Method	Signature	Description
m.newPRNG	m.newPRNG(seed)	Creates a seedable Linear Congruential Generator object.
:random	rng:random()	Returns a pseudo-random float in the range [0, 1).
:random (Integer)	rng:random(min, max)	Returns a pseudo-random integer in the range [min, max].

---

7. Statistical Utilities

Function	Signature	Description
m.sum	m.sum(array)	Returns the sum of all numeric elements in a flat array.
m.mean	m.mean(array)	Calculates the arithmetic mean (average) of an array.
m.median	m.median(array)	Returns the median value of an array.
m.minMax	m.minMax(array)	Returns both the minimum and maximum values (min, max) in an array.

License MIT License. Free to use in personal and commercial projects.