mathLuaLuau

The math library rounds numbers and computes powers, logarithms, trigonometry, interpolation, random numbers and noise. It also holds constants like math.pi.

Its functions take and return number values (64-bit floats). Most follow the C standard library and return NaN or an infinity for input outside their domain instead of raising an error.

Summary

Rounding and parts

math.floorLua: Rounds a number down to the nearest integer
math.ceilLua: Rounds a number up to the nearest integer
math.roundLuau: Rounds a number to the nearest integer
math.modfLua: Splits a number into its integer and fractional parts
math.fmodLua: Returns the remainder of x / y with the quotient rounded toward zero
math.frexpLua: Splits a number into a significand and a binary exponent
math.ldexpLua: Builds a number from a significand and a binary exponent

Signs and limits

math.absLua: Returns the absolute value of a number
math.signLuau: Returns -1, 0 or 1 for the sign of a number
math.minLua: Returns the smallest of its arguments
math.maxLua: Returns the largest of its arguments
math.clampLuau: Limits a number to a range

Powers and logarithms

math.powLua: Raises a number to a power
math.sqrtLua: Returns the square root of a number
math.expLua: Returns e raised to the power of a number
math.logLuaLuau: Returns the logarithm of a number in a given base
math.log10Lua: Returns the base-10 logarithm of a number

Trigonometry

math.sinLua: Returns the sine of an angle in radians
math.cosLua: Returns the cosine of an angle in radians
math.tanLua: Returns the tangent of an angle in radians
math.asinLua: Returns the arc sine of a number in radians
math.acosLua: Returns the arc cosine of a number in radians
math.atanLua: Returns the arc tangent of a number in radians
math.atan2Lua: Returns the arc tangent of y / x using both signs to pick the quadrant
math.sinhLua: Returns the hyperbolic sine of a number
math.coshLua: Returns the hyperbolic cosine of a number
math.tanhLua: Returns the hyperbolic tangent of a number
math.degLua: Converts an angle from radians to degrees
math.radLua: Converts an angle from degrees to radians

Interpolation

math.lerpLuau: Interpolates linearly between two numbers
math.mapLuau: Maps a number linearly from one range onto another

Random numbers

math.randomLua: Returns a random float or integer from the global generator
math.randomseedLua: Reseeds the global random number generator

Noise

math.noiseLuau: Returns the 3D Perlin noise value at a point

Number checks

math.isnanLuau: Checks whether a number is NaN
math.isinfLuau: Checks whether a number is an infinity
math.isfiniteLuau: Checks whether a number is neither NaN nor an infinity

Constants

math.piLua: Holds the ratio of a circle's circumference to its diameter
math.hugeLua: Holds positive infinity
math.nanLuau: Holds a NaN (not a number) value
math.eLuau: Holds Euler's number, the base of the natural logarithm
math.phiLuau: Holds the golden ratio
math.sqrt2Luau: Holds the square root of 2
math.tauLuau: Holds the ratio of a circle's circumference to its radius

Rounding and parts

`math.floor`Lua

function math.floor(n: number): number

Rounds n down to the nearest integer.

Input

print(math.floor(2.9))
print(math.floor(-2.1))

Output

2
-3

`math.ceil`Lua

function math.ceil(n: number): number

Rounds n up to the nearest integer.

Input

print(math.ceil(2.1))
print(math.ceil(-2.9))

Output

3
-2

`math.round`Luau

function math.round(n: number): number

Rounds n to the nearest integer. A value exactly halfway between two integers rounds away from zero.

Input

print(math.round(2.5))
print(math.round(-2.5))
print(math.round(2.4))

Output

3
-3
2

`math.modf`Lua

function math.modf(n: number): (number, number)

Returns the integer part and the fractional part of n. Both have the sign of n.

Input

const whole, fraction = math.modf(-1.5)
print(whole)
print(fraction)

Output

-1
-0.5

`math.fmod`Lua

function math.fmod(x: number, y: number): number

Returns the remainder of x / y with the quotient rounded toward zero. The result has the sign of x. The % operator rounds the quotient down instead and its result has the sign of y:

Input

print(math.fmod(-7, 3))
print(-7 % 3)

Output

-1
2

Returns NaN when y is 0.

`math.frexp`Lua

function math.frexp(n: number): (number, number)

Returns a significand s and a binary exponent e such that n == s * 2 ^ e. The absolute value of s is at least 0.5 and less than 1, unless n is 0.

`math.ldexp`Lua

function math.ldexp(s: number, e: number): number

Returns s * 2 ^ e. It's the inverse of math.frexp. e is truncated to an integer.

Signs and limits

`math.abs`Lua

function math.abs(n: number): number

Returns the absolute value of n. NaN stays NaN.

`math.sign`Luau

function math.sign(n: number): number

Returns -1 when n is negative, 1 when it's positive and 0 when it's 0 or NaN.

`math.min`Lua

function math.min(first: number, ...: number): number

Returns the smallest of its arguments. Calling it without arguments is an error.

Input

print(math.min(3, 9, 4))

Output

`math.max`Lua

function math.max(first: number, ...: number): number

Returns the largest of its arguments. Calling it without arguments is an error.

Input

print(math.max(3, 9, 4))

Output

`math.clamp`Luau

function math.clamp(n: number, min: number, max: number): number

Returns n limited to the range min to max. It returns min when n is below it, max when n is above it and n otherwise.

Input

print(math.clamp(150, 0, 100))
print(math.clamp(-5, 0, 100))
print(math.clamp(42, 0, 100))

Output

100
0
42

A min greater than max is an error.

Powers and logarithms

`math.pow`Lua

function math.pow(x: number, y: number): number

Returns x raised to the power of y like x ^ y.

`math.sqrt`Lua

function math.sqrt(n: number): number

Returns the square root of n. Returns NaN when n is negative.

`math.exp`Lua

function math.exp(n: number): number

Returns math.e raised to the power of n.

`math.log`LuaLuau

function math.log(n: number, base: number?): number

Returns the logarithm of n in base. Without base it returns the natural logarithm (base math.e). Returns NaN when n is negative and -math.huge when it's 0.

Input

print(math.log(8, 2))
print(math.log(1000, 10))

Output

3
3

Bases 2 and 10 use dedicated functions and give exact results for exact powers. Other bases compute math.log(n) / math.log(base).

`math.log10`Lua

function math.log10(n: number): number

Returns the base-10 logarithm of n. Returns NaN when n is negative and -math.huge when it's 0. It's the same as math.log(n, 10).

Trigonometry

`math.sin`Lua

function math.sin(n: number): number

Returns the sine of n, an angle in radians. The result is in the range -1 to 1.

`math.cos`Lua

function math.cos(n: number): number

Returns the cosine of n, an angle in radians. The result is in the range -1 to 1.

`math.tan`Lua

function math.tan(n: number): number

Returns the tangent of n, an angle in radians.

`math.asin`Lua

function math.asin(n: number): number

Returns the arc sine of n in radians, in the range -math.pi / 2 to math.pi / 2. Returns NaN when n is outside -1 to 1.

`math.acos`Lua

function math.acos(n: number): number

Returns the arc cosine of n in radians, in the range 0 to math.pi. Returns NaN when n is outside -1 to 1.

`math.atan`Lua

function math.atan(n: number): number

Returns the arc tangent of n in radians, in the range -math.pi / 2 to math.pi / 2.

`math.atan2`Lua

function math.atan2(y: number, x: number): number

Returns the arc tangent of y / x in radians, in the range -math.pi to math.pi. It uses the signs of both arguments to pick the quadrant and handles an x of 0. That makes it the function for the angle of a direction:

Input

print(math.deg(math.atan2(1, 1)))
print(math.deg(math.atan2(1, -1)))

Output

45
135

`math.sinh`Lua

function math.sinh(n: number): number

Returns the hyperbolic sine of n.

`math.cosh`Lua

function math.cosh(n: number): number

Returns the hyperbolic cosine of n.

`math.tanh`Lua

function math.tanh(n: number): number

Returns the hyperbolic tangent of n.

`math.deg`Lua

function math.deg(n: number): number

Converts n from radians to degrees.

`math.rad`Lua

function math.rad(n: number): number

Converts n from degrees to radians.

Interpolation

`math.lerp`Luau

function math.lerp(a: number, b: number, t: number): number

Interpolates linearly from a to b by the factor t and returns a + (b - a) * t. A t of 1 returns exactly b. t isn't clamped: values outside 0 to 1 extrapolate past a or b.

Input

print(math.lerp(10, 20, 0.25))
print(math.lerp(10, 20, 1.5))

Output

12.5
25

`math.map`Luau

function math.map(x: number, inmin: number, inmax: number, outmin: number, outmax: number): number

Maps x linearly from the range inmin to inmax onto the range outmin to outmax. The result isn't clamped when x is outside the input range.

Input

-- a 0 to 255 color channel as a fraction from 0 to 1
print(math.map(51, 0, 255, 0, 1))

Output

0.2

Random numbers

`math.random`Lua

function math.random(): number
function math.random(n: number): number
function math.random(min: number, max: number): number

Returns a random number from the global random number generator. Its result depends on the arguments:

With none, a float from 0 up to but not including 1.
With n, an integer from 1 to n inclusive.
With min and max, an integer from min to max inclusive.

The arguments are truncated to integers. An empty range, like math.random(0) or a min greater than max, is an error. The generator is PCG32. Each Luwu VM seeds it differently when it starts.

`math.randomseed`Lua

function math.randomseed(seed: number)

Reseeds the global random number generator. Every call to math.random after it returns a sequence that depends only on seed.

Input

math.randomseed(42)
const first = { math.random(100), math.random(100), math.random(100) }
math.randomseed(42)
const second = { math.random(100), math.random(100), math.random(100) }
print(table.concat(first, ", ") == table.concat(second, ", "))

Output

true

Noise

`math.noise`Luau

function math.noise(x: number, y: number?, z: number?): number

Returns the 3D Perlin noise value at the point (x, y, z). y and z default to 0. The result is in the range -1 to 1 and changes smoothly as the point moves. That makes noise useful for terrain, textures and other natural-looking variation. The same point always gives the same value.

Input

print(math.noise(1.5, 2.25, 0.75))
print(math.noise(1, 2, 3))

Output

-0.21080541610717773
0

Points where every coordinate is an integer always return 0.
The noise repeats every 256 units along each axis.
The coordinates are converted to 32-bit floats. Large coordinates lose precision in that conversion and above 2^24 (about 16.7 million) the fractional part is gone. With the precision fix on, each coordinate first wraps into one 256-unit period at full 64-bit precision. A large coordinate then returns the same value as the matching small one.

Number checks

`math.isnan`Luau

function math.isnan(x: number): boolean

Returns true when x is NaN. NaN is the only value not equal to itself and x ~= x gives the same answer.

`math.isinf`Luau

function math.isinf(x: number): boolean

Returns true when x is math.huge or -math.huge.

`math.isfinite`Luau

function math.isfinite(x: number): boolean

Returns true when x is neither NaN nor an infinity.

Input

print(math.isfinite(1 / 3))
print(math.isfinite(1 / 0))
print(math.isfinite(0 / 0))

Output

true
false
false

Constants

`math.pi`Lua

math.pi: number

The ratio of a circle's circumference to its diameter, about 3.14159.

`math.huge`Lua

math.huge: number

Positive infinity. It's greater than every other number and -math.huge is less than every other number.

`math.nan`Luau

math.nan: number

A NaN (not a number) value. It isn't equal to anything, itself included. Use math.isnan to test for it.

`math.e`Luau

math.e: number

Euler's number, the base of the natural logarithm, about 2.71828.

`math.phi`Luau

math.phi: number

The golden ratio, about 1.61803.

`math.sqrt2`Luau

math.sqrt2: number

The square root of 2, about 1.41421.

`math.tau`Luau

math.tau: number

The ratio of a circle's circumference to its radius, 2 * math.pi.

mathInherited from Lua 5.1's standard library.LuaAdded by Luau: math.round, math.sign, math.clamp, math.lerp, math.map, math.noise, math.isnan, math.isinf, math.isfinite, math.nan, math.e, math.phi, math.sqrt2, math.tauChanged by Luau: math.log, math.noiseLuau

Rounding and parts

math.floorInherited from Lua 5.1's standard library.Lua

math.ceilInherited from Lua 5.1's standard library.Lua

math.roundAdded by Luau 0.501 or earlier.Luau

math.modfInherited from Lua 5.1's standard library.Lua

math.fmodInherited from Lua 5.1's standard library.Lua

math.frexpInherited from Lua 5.1's standard library.Lua

math.ldexpInherited from Lua 5.1's standard library.Lua

Signs and limits

math.absInherited from Lua 5.1's standard library.Lua

math.signAdded by Luau 0.501 or earlier.Luau

math.minInherited from Lua 5.1's standard library.Lua

math.maxInherited from Lua 5.1's standard library.Lua

math.clampAdded by Luau 0.501 or earlier.Luau

Powers and logarithms

math.powInherited from Lua 5.1's standard library.Lua

math.sqrtInherited from Lua 5.1's standard library.Lua

math.expInherited from Lua 5.1's standard library.Lua

math.logInherited from Lua 5.1's standard library.LuaChanged by Luau 0.501 or earlier: Takes an optional base, as Lua 5.2 does.Luau

math.log10Inherited from Lua 5.1's standard library.Lua

Trigonometry

math.sinInherited from Lua 5.1's standard library.Lua

math.cosInherited from Lua 5.1's standard library.Lua

math.tanInherited from Lua 5.1's standard library.Lua

math.asinInherited from Lua 5.1's standard library.Lua

math.acosInherited from Lua 5.1's standard library.Lua

math.atanInherited from Lua 5.1's standard library.Lua

math.atan2Inherited from Lua 5.1's standard library.Lua

math.sinhInherited from Lua 5.1's standard library.Lua

math.coshInherited from Lua 5.1's standard library.Lua

math.tanhInherited from Lua 5.1's standard library.Lua

math.degInherited from Lua 5.1's standard library.Lua

math.radInherited from Lua 5.1's standard library.Lua

Interpolation

math.lerpAdded by Luau 0.656.Luau

math.mapAdded by Luau 0.648.Luau

Random numbers

math.randomInherited from Lua 5.1's standard library.Lua

math.randomseedInherited from Lua 5.1's standard library.Lua

Noise

math.noiseAdded by Luau 0.501 or earlier.Changed by Luau 0.716: Wraps inputs every 256 units so large inputs don't lose precision.Luau

Number checks

math.isnanAdded by Luau 0.701.Luau

math.isinfAdded by Luau 0.701.Luau

math.isfiniteAdded by Luau 0.701.Luau

Constants

math.piInherited from Lua 5.1's standard library.Lua

math.hugeInherited from Lua 5.1's standard library.Lua

math.nanAdded by Luau 0.711.Luau

math.eAdded by Luau 0.711.Luau

math.phiAdded by Luau 0.711.Luau

math.sqrt2Added by Luau 0.711.Luau

math.tauAdded by Luau 0.711.Luau

mathLuaLuau

`math.floor`Lua

`math.ceil`Lua

`math.round`Luau

`math.modf`Lua

`math.fmod`Lua

`math.frexp`Lua

`math.ldexp`Lua

`math.abs`Lua

`math.sign`Luau

`math.min`Lua

`math.max`Lua

`math.clamp`Luau

`math.pow`Lua

`math.sqrt`Lua

`math.exp`Lua

`math.log`LuaLuau

`math.log10`Lua

`math.sin`Lua

`math.cos`Lua

`math.tan`Lua

`math.asin`Lua

`math.acos`Lua

`math.atan`Lua

`math.atan2`Lua

`math.sinh`Lua

`math.cosh`Lua

`math.tanh`Lua

`math.deg`Lua

`math.rad`Lua

`math.lerp`Luau

`math.map`Luau

`math.random`Lua

`math.randomseed`Lua

`math.noise`Luau

`math.isnan`Luau

`math.isinf`Luau

`math.isfinite`Luau

`math.pi`Lua

`math.huge`Lua

`math.nan`Luau

`math.e`Luau

`math.phi`Luau

`math.sqrt2`Luau

`math.tau`Luau