14 min read

Source: Roblox Creator Hub · CC BY 4.0 · View source · Code samples: MIT Imported 2026-10-03. Formatting adapted for this site.

math

This library is an interface to the standard C math library, providing all of its functions inside the math table.

Properties

Name	Type / Returns	Description
math.e	number	The value of Euler's number, e.
math.huge	number	Returns a value larger than or equal to any other numerical value (about 2¹⁰²⁴).
math.nan	number	A NaN value, as defined by the IEEE 754 standard.
math.phi	number	The value of the golden ratio.
math.pi	number	The value of pi.
math.sqrt2	number	The value of the square root of 2.
math.tau	number	The value of tau, which is defined as `2 * math.pi`.

math.e

The value of Euler's number, e.

Field	Value
type	number

math.huge

Returns a value larger than or equal to any other numerical value (about 2¹⁰²⁴). Dividing a positive number by zero yields this same value.

Field	Value
type	number

math.nan

A NaN value, as defined by the IEEE 754 standard. Comparing directly to math.nan will always return false; use math.isnan() instead.

Field	Value
type	number

math.phi

The value of the golden ratio.

Field	Value
type	number

math.pi

The value of pi.

Field	Value
type	number

math.sqrt2

The value of the square root of 2.

Field	Value
type	number

math.tau

The value of tau, which is defined as 2 * math.pi.

Field	Value
type	number

Functions

Name	Type / Returns	Description
math.abs	number	Returns the absolute value of `x`.
math.acos	number	Returns the arc cosine of `x`.
math.asin	number	Returns the arc sine of `x`.
math.atan	number	Returns the arc tangent of `x` in radians.
math.atan2	number	Returns the arc tangent of `y`/`x` (in radians) while using the signs of both parameters to find the quadrant of the result.
math.ceil	int	Returns the smallest integer larger than or equal to `x`.
math.clamp	number	Returns a number between `min` and `max`, inclusive.
math.cos	number	Returns the cosine of `x`, assumed to be in radians.
math.cosh	number	Returns the hyperbolic cosine of `x`.
math.deg	number	Returns the angle `x` (given in radians) in degrees.
math.exp	number	Returns the value `e`^`x`.
math.floor	int	Returns the largest integer smaller than or equal to `x`.
math.fmod	number	Returns the remainder of the division of `x` by `y` that rounds the quotient towards zero.
math.frexp	number, int	Returns `m` and `e` such that `x` = `m`*`2`^`e`.
math.isfinite	boolean	Returns true if `x` is a finite number.
math.isinf	boolean	Returns true if `x` is positive or negative infinity and false otherwise.
math.isnan	boolean	Returns true if `x` is not a number (NaN) and false otherwise.
math.ldexp	number	Returns `x`*`2`^`e` (`e` should be an integer).
math.lerp	number	Returns the linear interpolation between `a` and `b`.
math.log	number	Returns the logarithm of `x` using the given base.
math.log10	number	Returns the base-10 logarithm of `x`.
math.map	number	Returns the value of `x` mapped from one range to another.
math.max	number	Returns the maximum value among the numbers passed to the function.
math.min	number	Returns the minimum value among the numbers passed to the function.
math.modf	number, number	Returns two numbers: the integral part of `x` and the fractional part of `x`.
math.noise	number	Returns a Perlin noise value.
math.pow	number	Returns `x`^`y`.
math.rad	number	Returns the angle `x` (given in degrees) in radians.
math.random	number	Returns a random number within the range provided.
math.randomseed	()	Sets `x` as the seed for the pseudo-random generator.
math.round	number	Returns the integer with the smallest difference between it and the given number.
math.sign	int	Returns `-1` if `x` is less than `0`, `0` if `x` equals `0`, or `1` if `x` is greater than `0`.
math.sin	number	Returns the sine of `x`, assumed to be in radians.
math.sinh	number	Returns the hyperbolic sine of `x`.
math.sqrt	number	Returns the square root of `x`.
math.tan	number	Returns the tangent of `x`, assumed to be in radians.
math.tanh	number	Returns the hyperbolic tangent of `x`.

math.abs

Returns the absolute value of x.

Parameters

Name	Type	Default	Description
x	number		The number to return the absolute value of.

Returns

Type	Description
number	The absolute value of `x`.

math.acos

Returns the arc cosine of x.

Parameters

Name	Type	Default	Description
x	number		The cosine value, between `-1` and `1`.

Returns

Type	Description
number	The angle in radians whose cosine is `x`, in the range `[0, pi]`.

math.asin

Returns the arc sine of x.

Parameters

Name	Type	Default	Description
x	number		The sine value, between `-1` and `1`.

Returns

Type	Description
number	The angle in radians whose sine is `x`, in the range `[-pi/2, pi/2]`.

math.atan

Returns the arc tangent of x in radians.

Parameters

Name	Type	Default	Description
x	number		The value to compute the arc tangent of.

Returns

Type	Description
number	The arc tangent of `x` in radians, in the range `[-pi/2, pi/2]`.

math.atan2

Returns the arc tangent of y/x (in radians) while using the signs of both parameters to find the quadrant of the result. It also handles correctly the case of x being zero.

Parameters

Name	Type	Default	Description
y	number		The Y coordinate.
x	number		The X coordinate.

Returns

Type	Description
number	The arc tangent of `y`/`x` in radians, in the range `[-pi, pi]`.

math.ceil

Returns the smallest integer larger than or equal to x.

Parameters

Name	Type	Default	Description
x	number		The number to round up.

Returns

Type	Description
int	The smallest integer greater than or equal to `x`.

math.clamp

Returns a number between min and max, inclusive.

Parameters

Name	Type	Description
x	number	The number to clamp.
min	number	The minimum value of the range.
max	number	The maximum value of the range; must be greater than or equal to `min`.

Returns

Type	Description
number	`x` constrained to the range `[`min`,` max`]`.

math.cos

Returns the cosine of x, assumed to be in radians.

Parameters

Name	Type	Default	Description
x	number		The angle in radians.

Returns

Type	Description
number	The cosine of `x`.

math.cosh

Returns the hyperbolic cosine of x.

Parameters

Name	Type	Default	Description
x	number		The number to compute the hyperbolic cosine of.

Returns

Type	Description
number	The hyperbolic cosine of `x`.

math.deg

Returns the angle x (given in radians) in degrees.

Parameters

Name	Type	Default	Description
x	number		The angle in radians to convert.

Returns

Type	Description
number	The angle `x` converted to degrees.

math.exp

Returns the value e^x.

Parameters

Name	Type	Default	Description
x	number		The exponent.

Returns

Type	Description
number	The value of `e` raised to the power `x`.

math.floor

Returns the largest integer smaller than or equal to x.

Parameters

Name	Type	Default	Description
x	number		The number to round down.

Returns

Type	Description
int	The largest integer less than or equal to `x`.

math.fmod

Returns the remainder of the division of x by y that rounds the quotient towards zero.

Parameters

Name	Type	Default	Description
x	number		The dividend.
y	number		The divisor.

Returns

Type	Description
number	The remainder of the division of `x` by `y`.

math.frexp

Returns m and e such that x = m*2^e. e is an integer and the absolute value of m is in the range of 0.5 to 1 (inclusive of 0.5 but exclusive of 1), or zero when x is zero.

Parameters

Name	Type	Default	Description
x	number		The number to decompose into mantissa and exponent.

Returns

Type	Description
number	The mantissa `m`, a value whose absolute value is in `[0.5, 1)` or zero.
int	The exponent `e` such that `x = m * 2^e`.

math.isfinite

Returns true if x is a finite number, meaning it is neither NaN nor positive or negative infinity (±math.huge).

Parameters

Name	Type	Default	Description
x	number		The number to test.

Returns

Type	Description
boolean	True if `x` is neither NaN nor infinity, false otherwise.

math.isinf

Returns true if x is positive or negative infinity (±math.huge) and false otherwise.

Parameters

Name	Type	Default	Description
x	number		The number to test.

Returns

Type	Description
boolean	True if `x` is positive or negative infinity, false otherwise.

math.isnan

Returns true if x is not a number (NaN) and false otherwise.

Parameters

Name	Type	Default	Description
x	number		The number to test.

Returns

Type	Description
boolean	True if `x` is NaN, false otherwise.

math.ldexp

Returns x*2^e (e should be an integer).

Parameters

Name	Type	Default	Description
x	number		The mantissa value.
e	int		The integer exponent.

Returns

Type	Description
number	The value `x * 2^e`.

math.lerp

Returns the linear interpolation between a and b based on the factor t.

This function uses the formula a+(b-a)*t. t is typically between 0 and 1 but values outside this range are acceptable.

Parameters

Name	Type	Description
a	number	The starting value.
b	number	The ending value.
t	number	The interpolation factor, typically between `0` and `1`.

Returns

Type	Description
number	The interpolated value between `a` and `b`.

math.log

Returns the logarithm of x using the given base, or the mathematical constant e if no base is provided (natural logarithm).

Parameters

Name	Type	Default	Description
x	number		The number to compute the logarithm of.
base	number	2.7182818	The base of the logarithm, the constant `e` by default.

Returns

Type	Description
number	The logarithm of `x` in the given base.

math.log10

Returns the base-10 logarithm of x.

Parameters

Name	Type	Default	Description
x	number		The number to compute the base-10 logarithm of.

Returns

Type	Description
number	The base-10 logarithm of `x`.

math.map

Returns a value that represents x mapped linearly from the input range (inmin to inmax) to the output range (outmin to outmax). This is achieved by determining the relative position of x within the input range and applying that ratio to the output range.

Parameters

Name	Type	Description
x	number	The number to be mapped.
inmin	number	The lower bound of the input range.
inmax	number	The upper bound of the input range.
outmin	number	The lower bound of the output range.
outmax	number	The upper bound of the output range.

Returns

Type	Description
number	The value of `x` mapped to the output range.

math.max

Returns the maximum value among the numbers passed to the function.

Parameters

Name	Type	Default	Description
x	number		The first number to compare.
...	number		Additional numbers to compare.

Returns

Type	Description
number	The largest value among all arguments.

math.min

Returns the minimum value among the numbers passed to the function.

Parameters

Name	Type	Default	Description
x	number		The first number to compare.
...	number		Additional numbers to compare.

Returns

Type	Description
number	The smallest value among all arguments.

math.modf

Returns two numbers: the integral part of x and the fractional part of x.

Parameters

Name	Type	Default	Description
x	number		The number to split into integral and fractional parts.

Returns

Type	Description
number	The integral part of `x`.
number	The fractional part of `x`.

math.noise

Returns a Perlin noise value. The returned value is most often between the range of -1 to 1 (inclusive) but sometimes may be outside that range; if the interval is critical to you, use math.clamp(noise, -1, 1) on the output.

If you leave arguments out, they will be interpreted as zero, so math.noise(1.158) is equivalent to math.noise(1.158, 0, 0) and math.noise(1.158, 5.723) is equivalent to math.noise(1.158, 5.723, 0).

Note that this function uses a Perlin noise algorithm to assign fixed values to coordinates. For example, math.noise(1.158, 5.723) will always return 0.48397532105446 and math.noise(1.158, 6) will always return 0.15315161645412.

If x, y, and z are all integers, the return value will be 0. For fractional values of x, y, and z, the return value will gradually fluctuate between -0.5 and 0.5. For coordinates that are close to each other, the return values will also be close to each other.

The noise repeats with a period of 256 on each axis, so math.noise(x, y, z) and math.noise(x + 256, y, z) return identical values.

Parameters

Name	Type	Default	Description
x	number		The X coordinate of the sample point.
y	number	0	The Y coordinate of the sample point.
z	number	0	The Z coordinate of the sample point.

Returns

Type	Description
number	A Perlin noise value, typically between `-1` and `1`.

math.pow

Returns x^y (you can also use the expression x^y to compute this value).

Parameters

Name	Type	Default	Description
x	number		The base value.
y	number		The exponent value.

Returns

Type	Description
number	The value `x` raised to the power `y`.

math.rad

Returns the angle x (given in degrees) in radians.

Parameters

Name	Type	Default	Description
x	number		The angle in degrees to convert.

Returns

Type	Description
number	The angle `x` converted to radians.

math.random

When called without arguments, returns a uniform pseudo-random real number in the range of 0 to 1 (inclusive of 0 but exclusive of 1).

When called with an integer number m, returns a uniform pseudo-random integer in the range of 1 to m, inclusive.

When called with two integer numbers m and n, returns a uniform pseudo-random integer in the range of m to n, inclusive.

Internally, this uses a 32-bit PCG (Permuted Congruential Generator) which achieves excellent statistical performance and makes its output hard to predict.

Parameters

Name	Type	Default	Description
m	number	0	When used alone, the upper bound of the integer range (lower bound is `1`). When used with `n`, the lower bound.
n	number	1	The upper bound of the integer range.

Returns

Type	Description
number	A pseudo-random number within the specified range.

math.randomseed

Sets x as the seed for the pseudo-random generator: equal seeds produce equal sequences of numbers.

Parameters

Name	Type	Default	Description
x	number		The seed value for the pseudo-random number generator.

Returns

Type	Description
()

math.round

Returns the integer with the smallest difference between it and the given number. For example, the value 5.8 returns 6.

For values like 0.5 that are equidistant to two integers, the value with the greater difference between it and zero is chosen. In other words, the function "rounds away from zero" such that 0.5 rounds to 1 and -0.5 rounds to -1.

Parameters

Name	Type	Default	Description
x	number		The value to be rounded.

Returns

Type	Description
number	The nearest integer to `x`, rounding away from zero for midpoints.

math.sign

Returns -1 if x is less than 0, 0 if x equals 0, or 1 if x is greater than 0.

Parameters

Name	Type	Default	Description
x	number		The number to determine the sign of.

Returns

Type	Description
int	`-1` if `x` is negative, `0` if `x` is zero, or `1` if `x` is positive.

math.sin

Returns the sine of x, assumed to be in radians.

Parameters

Name	Type	Default	Description
x	number		The angle in radians.

Returns

Type	Description
number	The sine of `x`.

math.sinh

Returns the hyperbolic sine of x.

Parameters

Name	Type	Default	Description
x	number		The number to compute the hyperbolic sine of.

Returns

Type	Description
number	The hyperbolic sine of `x`.

math.sqrt

Returns the square root of x. You can also use the expression x^0.5 to compute this value.

Parameters

Name	Type	Default	Description
x	number		The number to compute the square root of.

Returns

Type	Description
number	The square root of `x`.

math.tan

Returns the tangent of x, assumed to be in radians.

Parameters

Name	Type	Default	Description
x	number		The angle in radians.

Returns

Type	Description
number	The tangent of `x`.

math.tanh

Returns the hyperbolic tangent of x.

Parameters

Name	Type	Default	Description
x	number		The number to compute the hyperbolic tangent of.

Returns

Type	Description
number	The hyperbolic tangent of `x`.