math

Mathematical functions of Lua 5.1 / LuaJIT 2.1, unchanged by the client; angles are in radians.

At a glance

Every function takes numbers (numeric strings are converted) and raises bad argument #1 to 'sqrt' (number expected, got nil), with the right name and position, for anything else. There is no integer type: every result is a double. Out-of-domain inputs give NaN or infinity, not an error.

Rounding and sign

math.abs(x): number

math.abs(x: number): number

Returns: the absolute value of x.

math.ceil(x): number

math.ceil(x: number): number

Returns: the smallest integer value >= x.

math.floor(x): number

math.floor(x: number): number

Returns: the largest integer value <= x. Round to nearest with math.floor(x + 0.5).

print(math.floor(-2.5), math.ceil(-2.5), math.floor(2.5 + 0.5))

math.fmod(x, y): number

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

Returns: the remainder of x / y rounded toward zero, with the sign of x. The % operator differs for negative operands.

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

math.modf(x): number, number

math.modf(x: number): number, number

Returns: the integral part of x (toward zero) and the fractional part.

print(math.modf(-3.25))

Trigonometry

math.sin(x): number

math.sin(x: number): number

Returns: the sine of x.

math.cos(x): number

math.cos(x: number): number

Returns: the cosine of x.

math.tan(x): number

math.tan(x: number): number

Returns: the tangent of x.

math.asin(x): number

math.asin(x: number): number

Returns: the arc sine of x, NaN outside [-1, 1].

math.acos(x): number

math.acos(x: number): number

Returns: the arc cosine of x, NaN outside [-1, 1].

math.atan(x): number

math.atan(x: number): number

Returns: the arc tangent of x, between -pi/2 and pi/2. It takes one argument in Lua 5.1: use math.atan2 for two.

math.atan2(y, x): number

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

Returns: the angle of the point (x, y), between -pi and pi, using both signs to find the quadrant.

local yaw = math.deg(math.atan2(1, 0))
print(yaw)

math.sinh(x): number

math.sinh(x: number): number

Returns: the hyperbolic sine of x.

math.cosh(x): number

math.cosh(x: number): number

Returns: the hyperbolic cosine of x.

math.tanh(x): number

math.tanh(x: number): number

Returns: the hyperbolic tangent of x.

math.rad(x): number

math.rad(x: number): number

Returns: x in radians.

math.deg(x): number

math.deg(x: number): number

Returns: x in degrees.

local yaw = math.rad(90)
print(math.cos(yaw), math.deg(yaw))

Powers and logarithms

math.sqrt(x): number

math.sqrt(x: number): number

Returns: the square root of x, NaN for a negative x.

math.pow(x, y): number

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

Returns: x ^ y.

math.exp(x): number

math.exp(x: number): number

Returns: e raised to the power x.

math.log(x, base): number

math.log(x: number, base?: number): number

Returns: the logarithm of x. -math.huge for 0, NaN for a negative x.

print(math.log(8, 2), math.log(math.exp(1)))

math.log10(x): number

math.log10(x: number): number

Returns: the base-10 logarithm of x.

math.frexp(x): number, number

math.frexp(x: number): number, number

Returns: m and e such that x = m * 2^e, with e an integer and |m| in [0.5, 1), or 0, 0 for 0.

math.ldexp(m, e): number

math.ldexp(m: number, e: number): number

Returns: m * 2^e.

Min and max

math.max(x, ...): number

math.max(x: number, ...: number): number

Returns: the largest argument.

math.min(x, ...): number

math.min(x: number, ...: number): number

Returns: the smallest argument.

local function clamp(v, lo, hi)
    return math.max(lo, math.min(hi, v))
end
print(clamp(15, 0, 10))

Random

LuaJIT uses its own generator (Tausworthe, period 2^223), the same on every platform. Every new VM starts with the same seed, so the sequence repeats after each Clear VM until you call math.randomseed.

math.random(m, n): number

math.random(m?: number, n?: number): number

Returns:

• no argument: a float in [0, 1)
• math.random(n): an integer in [1, n]
• math.random(m, n): an integer in [m, n]

The range is not checked: math.random(0) or math.random(5, 1) return a meaningless number instead of raising an error. Pass integers.

print(math.random(1, 6), math.random())

math.randomseed(seed)

math.randomseed(seed?: number)

Returns: nothing. The same seed gives the same sequence.

math.randomseed()

Constants

math.huge: number

Positive infinity. -math.huge is negative infinity.

math.pi: number

The value of pi, 3.1415926535898.

Complete example

Turn a direction into a yaw in degrees, and pick a random point on a circle around the player.

local function yaw_of(dx, dz)
    return (math.deg(math.atan2(-dx, dz)) + 360) % 360
end

local function random_on_circle(cx, cz, radius)
    local angle = math.random() * 2 * math.pi
    return cx + math.cos(angle) * radius, cz + math.sin(angle) * radius
end

math.randomseed(os.time())
local x, z = random_on_circle(0, 0, 8)
print(("point %.2f %.2f, yaw %.1f"):format(x, z, yaw_of(x, z)))
print(math.floor(-0.5), math.huge, -math.huge, math.huge - math.huge ~= math.huge - math.huge)