# Module: `nupp.math` # Math helpers `nupp.math` adds the scalar and two-dimensional operations missing from Lua's built-in `math` table. It is pure generated Lua and adds no native dependency. `lerp(from, to, t)` linearly interpolates without clamping `t`, so factors outside `[0, 1]` extrapolate. It returns `from` exactly at zero and `to` exactly at one. `wrapAngle(radians)` returns the equivalent angle in `[-π, π)`. `deltaAngle(from, to)` returns the shortest signed rotation from one angle to another. ```nupp assert(nupp.math.lerp(10, 20, 0.25) == 12.5) local turn = nupp.math.deltaAngle(math.rad(350), math.rad(10)) assert(math.abs(math.deg(turn) - 20) < 0.000001) ``` `nupp.math.vec2` represents vectors as `(x, y)` number pairs rather than allocated objects. Multiple return values make composition direct: ```nupp local vec2 = nupp.math.vec2 local x, y = vec2.normalize(3, 4) assert(x == 0.6 and y == 0.8) x, y = vec2.rotate(x, y, math.pi / 2) local projectedX, projectedY = vec2.project(x, y, 1, 0) ``` Arithmetic operations are `add`, `subtract`, `scale`, `dot`, and `cross`. Measurement operations are `length`, `lengthSquared`, `distance`, and `distanceSquared`. Motion and orientation operations are `normalize`, `lerp`, `moveTowards`, `rotate`, `angle`, `angleBetween`, and `signedAngleBetween`. `project` projects onto another vector; `reflect` reflects across a normal. | Operation | Signature shape | | --- | --- | | `add`, `subtract` | `(ax, ay, bx, by) -> x, y` | | `scale` | `(x, y, factor) -> x, y` | | `dot`, `cross` | `(ax, ay, bx, by) -> number` | | `length`, `lengthSquared` | `(x, y) -> number` | | `distance`, `distanceSquared` | `(ax, ay, bx, by) -> number` | | `normalize` | `(x, y) -> x, y` | | `lerp` | `(ax, ay, bx, by, t) -> x, y` | | `moveTowards` | `(ax, ay, bx, by, maxDistance) -> x, y` | | `rotate` | `(x, y, radians) -> x, y` | | `angle` | `(x, y) -> radians` | | `angleBetween`, `signedAngleBetween` | `(ax, ay, bx, by) -> radians` | | `project`, `reflect` | `(x, y, axisX, axisY) -> x, y` | `normalize(0, 0)` and projection onto the zero vector return `(0, 0)`. `moveTowards` snaps exactly to the destination when the remaining distance is within the requested step, and a nonpositive step leaves the start unchanged. Angle-between operations involving a zero vector return zero; reflection across a zero normal returns the original vector. `lerp` is unclamped. Use squared length/distance when only comparing magnitudes, to avoid an unnecessary square root. See [the standard-library overview](stdlib.md) for selection and lazy-loading rules. Scalar helpers and two-dimensional vectors. ## Submodules | Module | Description | | --- | --- | | `nupp.math.vec2` | Two-dimensional vector operations over (x, y) number pairs. | ## Functions ### `deltaAngle` _function_ Computes the shortest signed rotation from one angle to another. ```nupp local deltaAngle: function(from: number, to: number): number ``` #### Arguments | Name | Type | Description | | --- | --- | --- | | `from` | `number` | the starting angle in radians | | `to` | `number` | the target angle in radians | #### Returns | Type | Description | | --- | --- | | `number` | the signed rotation in `[-pi, pi)` | ### `lerp` _function_ Linearly interpolates between two numbers without clamping the factor. ```nupp local lerp: function(from: number, to: number, t: number): number ``` #### Arguments | Name | Type | Description | | --- | --- | --- | | `from` | `number` | the value returned when `t` is zero | | `to` | `number` | the value returned when `t` is one | | `t` | `number` | the interpolation factor | #### Returns | Type | Description | | --- | --- | | `number` | `from + (to - from) * t` | ### `wrapAngle` _function_ Wraps an angle to the equivalent value in `[-pi, pi)`. ```nupp local wrapAngle: function(radians: number): number ``` #### Arguments | Name | Type | Description | | --- | --- | --- | | `radians` | `number` | the angle in radians | #### Returns | Type | Description | | --- | --- | | `number` | the wrapped angle |