Math
Vector tables ({x, y[, z]}), scalar helpers and angle conversion. Also defines the constants caffeine.math.pi and caffeine.math.epsilon (1e-5).
Namespace: caffeine.math
vec2#
Lua: caffeine.math.vec2
vec2(x, y) -> table
Creates a 2D vector table.
| Parameters | Type | Description |
|---|---|---|
x | number | X. |
y | number | Y. |
Returns: table. {x, y}
Example
local v = caffeine.math.vec2(1, 2)
vec3#
Lua: caffeine.math.vec3
vec3(x, y, z) -> table
Creates a 3D vector table.
| Parameters | Type | Description |
|---|---|---|
x | number | X. |
y | number | Y. |
z | number | Z. |
Returns: table. {x, y, z}
Example
local v = caffeine.math.vec3(1, 2, 3)
add#
Lua: caffeine.math.add
add(a, b) -> table
Component-wise sum of two vectors.
| Parameters | Type | Description |
|---|---|---|
a | table | Vector table {x, y[, z]}. |
b | table | Vector table {x, y[, z]}. |
Returns: table. Vector table; has z only when an operand has z.
Example
local p = caffeine.math.add(a, b)
sub#
Lua: caffeine.math.sub
sub(a, b) -> table
Component-wise difference a - b.
| Parameters | Type | Description |
|---|---|---|
a | table | Vector table {x, y[, z]}. |
b | table | Vector table {x, y[, z]}. |
Returns: table. Vector table; has z only when an operand has z.
Example
local d = caffeine.math.sub(a, b)
mul#
Lua: caffeine.math.mul
mul(a, b) -> table
Component-wise product of two vectors (not a dot product).
| Parameters | Type | Description |
|---|---|---|
a | table | Vector table {x, y[, z]}. |
b | table | Vector table {x, y[, z]}. |
Returns: table. Vector table; has z only when an operand has z.
Example
local m = caffeine.math.mul(a, b)
scale#
Lua: caffeine.math.scale
scale(v, s) -> table
Multiplies a vector by a scalar.
| Parameters | Type | Description |
|---|---|---|
v | table | Vector table {x, y[, z]}. |
s | number | Scalar factor. |
Returns: table. Scaled vector.
Example
local v2 = caffeine.math.scale(v, 2)
dot#
Lua: caffeine.math.dot
dot(a, b) -> number
Dot product of two vectors; a missing z counts as 0.
| Parameters | Type | Description |
|---|---|---|
a | table | Vector table {x, y[, z]}. |
b | table | Vector table {x, y[, z]}. |
Returns: number. Dot product.
Example
local d = caffeine.math.dot(a, b)
cross#
Lua: caffeine.math.cross
cross(a, b) -> table
Cross product; the result is always 3D.
| Parameters | Type | Description |
|---|---|---|
a | table | Vector table {x, y[, z]}. |
b | table | Vector table {x, y[, z]}. |
Returns: table. {x, y, z} vector.
Example
local n = caffeine.math.cross(a, b)
length#
Lua: caffeine.math.length
length(v) -> number
Length of a vector.
| Parameters | Type | Description |
|---|---|---|
v | table | Vector table {x, y[, z]}. |
Returns: number. Vector length.
Example
local l = caffeine.math.length(v)
lengthSquared#
Lua: caffeine.math.lengthSquared
lengthSquared(v) -> number
Squared length of a vector, without the square root.
| Parameters | Type | Description |
|---|---|---|
v | table | Vector table {x, y[, z]}. |
Returns: number. Squared length.
Example
local l2 = caffeine.math.lengthSquared(v)
distance#
Lua: caffeine.math.distance
distance(a, b) -> number
Distance between two points.
| Parameters | Type | Description |
|---|---|---|
a | table | Vector table {x, y[, z]}. |
b | table | Vector table {x, y[, z]}. |
Returns: number. Distance between the points.
Example
local d = caffeine.math.distance(a, b)
normalize#
Lua: caffeine.math.normalize
normalize(v) -> table
Returns the vector scaled to length 1.
| Parameters | Type | Description |
|---|---|---|
v | table | Vector table {x, y[, z]}. |
Returns: table. Unit vector, or zeros when the length is at most 0.0001.
Example
local dir = caffeine.math.normalize(caffeine.math.sub(b, a))
lerpVec#
Lua: caffeine.math.lerpVec
lerpVec(a, b, t) -> table
Linear interpolation between two vectors.
| Parameters | Type | Description |
|---|---|---|
a | table | Vector table {x, y[, z]}. |
b | table | Vector table {x, y[, z]}. |
t | number | Blend factor; not clamped. |
Returns: table. Vector table; has z only when an operand has z.
Example
local mid = caffeine.math.lerpVec(a, b, 0.5)
clamp#
Lua: caffeine.math.clamp
clamp(v, lo, hi) -> number
Limits a value to a range; swapped bounds are accepted.
| Parameters | Type | Description |
|---|---|---|
v | number | Value. |
lo | number | Lower bound. |
hi | number | Upper bound. |
Returns: number. Clamped value.
Example
local hp = caffeine.math.clamp(hp, 0, 100)
clamp01#
Lua: caffeine.math.clamp01
clamp01(v) -> number
Limits a value to 0..1.
| Parameters | Type | Description |
|---|---|---|
v | number | Value. |
Returns: number. Value limited to 0..1.
Example
local t = caffeine.math.clamp01(t)
lerp#
Lua: caffeine.math.lerp
lerp(a, b, t) -> number
Linear interpolation between two numbers.
| Parameters | Type | Description |
|---|---|---|
a | number | Start. |
b | number | End. |
t | number | Blend factor; not clamped. |
Returns: number. a + (b - a) * t
Example
local x = caffeine.math.lerp(0, 10, 0.25)
inverseLerp#
Lua: caffeine.math.inverseLerp
inverseLerp(a, b, v) -> number
The inverse of lerp; the result is not clamped.
| Parameters | Type | Description |
|---|---|---|
a | number | Start. |
b | number | End. |
v | number | Value. |
Returns: number. Position of v between a and b; 0 when a and b are equal.
Example
local t = caffeine.math.inverseLerp(0, 10, 5)
remap#
Lua: caffeine.math.remap
remap(v, inLo, inHi, outLo, outHi) -> number
Maps a value from one range to another.
| Parameters | Type | Description |
|---|---|---|
v | number | Value. |
inLo | number | Input range start. |
inHi | number | Input range end. |
outLo | number | Output range start. |
outHi | number | Output range end. |
Returns: number. Remapped value (not clamped).
Example
local pct = caffeine.math.remap(hp, 0, 100, 0, 1)
smoothstep#
Lua: caffeine.math.smoothstep
smoothstep(e0, e1, v) -> number
Smooth Hermite interpolation between two edges.
| Parameters | Type | Description |
|---|---|---|
e0 | number | Lower edge. |
e1 | number | Upper edge. |
v | number | Value. |
Returns: number. Smooth value in 0..1.
Example
local s = caffeine.math.smoothstep(0, 1, t)
approach#
Lua: caffeine.math.approach
approach(cur, target, step) -> number
Moves a value toward a target by at most step.
| Parameters | Type | Description |
|---|---|---|
cur | number | Current value. |
target | number | Target value. |
step | number | Maximum change; its absolute value is used. |
Returns: number. New value, never past the target.
Example
speed = caffeine.math.approach(speed, 0, 20 * caffeine.time.delta())
sign#
Lua: caffeine.math.sign
sign(v) -> number
Sign of a number.
| Parameters | Type | Description |
|---|---|---|
v | number | Value. |
Returns: number. -1, 0 or 1.
Example
local s = caffeine.math.sign(-3)
radians#
Lua: caffeine.math.radians
radians(deg) -> number
Converts degrees to radians.
| Parameters | Type | Description |
|---|---|---|
deg | number | Degrees. |
Returns: number. Radians.
Example
local r = caffeine.math.radians(90)
degrees#
Lua: caffeine.math.degrees
degrees(rad) -> number
Converts radians to degrees.
| Parameters | Type | Description |
|---|---|---|
rad | number | Radians. |
Returns: number. Degrees.
Example
local d = caffeine.math.degrees(caffeine.math.pi)