---
name: math
last_updated: 2026-06-10T23:09:13Z
type: library
summary: "A library of math functions."
---

# math

A library of math functions.

**Type:** library

## Description

This library is an interface to the standard C math library, providing all of
its functions inside the [math](/docs/reference/engine/globals/math.md) table.

## Properties

### math.e

**Type:** `number`

The value of Euler's number, e.

### math.huge

**Type:** `number`

Returns a value larger than or equal to any other numerical value (about
2<sup>1024</sup>). Dividing a positive number by zero yields this same
value.

### math.nan

**Type:** `number`

A NaN value, as defined by the IEEE 754 standard. Comparing directly to
`math.nan` will always return false; use [math.isnan()](/docs/reference/engine/globals/math.md) instead.

### math.phi

**Type:** `number`

The value of the golden ratio.

### math.pi

**Type:** `number`

The value of pi.

### math.sqrt2

**Type:** `number`

The value of the square root of 2.

### math.tau

**Type:** `number`

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

## Functions

### math.abs

**Signature:** `math.abs(x: number): number`

Returns the absolute value of `x`.

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `x` | `number` |  |  |

**Returns:** `number`

### math.acos

**Signature:** `math.acos(x: number): number`

Returns the arc cosine of `x`.

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `x` | `number` |  |  |

**Returns:** `number`

### math.asin

**Signature:** `math.asin(x: number): number`

Returns the arc sine of `x`.

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `x` | `number` |  |  |

**Returns:** `number`

### math.atan

**Signature:** `math.atan(x: number): number`

Returns the arc tangent of `x` in radians.

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `x` | `number` |  |  |

**Returns:** `number`

### math.atan2

**Signature:** `math.atan2(y: number, x: number): number`

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` |  |  |
| `x` | `number` |  |  |

**Returns:** `number`

### math.ceil

**Signature:** `math.ceil(x: number): int`

Returns the smallest integer larger than or equal to `x`.

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `x` | `number` |  |  |

**Returns:** `int`

### math.clamp

**Signature:** `math.clamp(x: number, min: number, max: number): number`

Returns a number between `min` and `max`, inclusive.

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `x` | `number` |  |  |
| `min` | `number` |  |  |
| `max` | `number` |  |  |

**Returns:** `number`

### math.cos

**Signature:** `math.cos(x: number): number`

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

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `x` | `number` |  |  |

**Returns:** `number`

### math.cosh

**Signature:** `math.cosh(x: number): number`

Returns the hyperbolic cosine of `x`.

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `x` | `number` |  |  |

**Returns:** `number`

### math.deg

**Signature:** `math.deg(x: number): number`

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

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `x` | `number` |  |  |

**Returns:** `number`

### math.exp

**Signature:** `math.exp(x: number): number`

Returns the value `e`^`x`.

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `x` | `number` |  |  |

**Returns:** `number`

### math.floor

**Signature:** `math.floor(x: number): int`

Returns the largest integer smaller than or equal to `x`.

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `x` | `number` |  |  |

**Returns:** `int`

### math.fmod

**Signature:** `math.fmod(x: number, y: number): number`

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

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `x` | `number` |  |  |
| `y` | `number` |  |  |

**Returns:** `number`

### math.frexp

**Signature:** `math.frexp(x: number): number, int`

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` |  |  |

**Returns:** `number`, `int`

### math.isfinite

**Signature:** `math.isfinite(x: number): boolean`

Returns true if `x` is a finite number, meaning it is neither NaN nor
positive or negative infinity (±[math.huge](/docs/reference/engine/globals/math.md)).

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `x` | `number` |  |  |

**Returns:** `boolean`

### math.isinf

**Signature:** `math.isinf(x: number): boolean`

Returns true if `x` is positive or negative infinity
(±[math.huge](/docs/reference/engine/globals/math.md)) and false otherwise.

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `x` | `number` |  |  |

**Returns:** `boolean`

### math.isnan

**Signature:** `math.isnan(x: number): boolean`

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

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `x` | `number` |  |  |

**Returns:** `boolean`

### math.ldexp

**Signature:** `math.ldexp(x: number, e: int): number`

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

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `x` | `number` |  |  |
| `e` | `int` |  |  |

**Returns:** `number`

### math.lerp

**Signature:** `math.lerp(a: number, b: number, t: number): number`

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 | Default | Description |
|------|------|---------|-------------|
| `a` | `number` |  | The starting value. |
| `b` | `number` |  | The ending value. |
| `t` | `number` |  | The interpolation factor, typically between `0` and `1`. |

**Returns:** `number` — The interpolated value between `a` and `b`.

### math.log

**Signature:** `math.log(x: number, base?: number): number`

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` |  |  |
| `base` | `number` | `2.7182818` | The base of the logarithm, the constant `e` by default. |

**Returns:** `number`

### math.log10

**Signature:** `math.log10(x: number): number`

Returns the base-10 logarithm of `x`.

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `x` | `number` |  |  |

**Returns:** `number`

### math.map

**Signature:** `math.map(x: number, inmin: number, inmax: number, outmin: number, outmax: number): number`

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 | Default | 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:** `number` — The value of `x` mapped to the output range.

### math.max

**Signature:** `math.max(x: number, ...: number): number`

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

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `x` | `number` |  |  |
| `...` | `number` |  |  |

**Returns:** `number`

### math.min

**Signature:** `math.min(x: number, ...: number): number`

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

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `x` | `number` |  |  |
| `...` | `number` |  |  |

**Returns:** `number`

### math.modf

**Signature:** `math.modf(x: number): number, number`

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

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `x` | `number` |  |  |

**Returns:** `number`, `number`

### math.noise

**Signature:** `math.noise(x: number, y?: number, z?: number): number`

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)](/docs/reference/engine/globals/math.md)
on the output.

If you leave arguments out, they will be interpreted as zero, so
[math.noise(1.158)](/docs/reference/engine/globals/math.md) is equivalent to
[math.noise(1.158, 0, 0)](/docs/reference/engine/globals/math.md) and [math.noise(1.158, 5.723)](/docs/reference/engine/globals/math.md)
is equivalent to [math.noise(1.158, 5.723, 0)](/docs/reference/engine/globals/math.md).

Note that this function uses a Perlin noise algorithm to assign fixed
values to coordinates. For example, [math.noise(1.158, 5.723)](/docs/reference/engine/globals/math.md)
will always return `0.48397532105446` and [math.noise(1.158, 6)](/docs/reference/engine/globals/math.md)
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.

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `x` | `number` |  |  |
| `y` | `number` | `0` |  |
| `z` | `number` | `0` |  |

**Returns:** `number`

### math.pow

**Signature:** `math.pow(x: number, y: number): number`

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

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `x` | `number` |  |  |
| `y` | `number` |  |  |

**Returns:** `number`

### math.rad

**Signature:** `math.rad(x: number): number`

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

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `x` | `number` |  |  |

**Returns:** `number`

### math.random

**Signature:** `math.random(m?: number, n?: number): number`

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` |  |
| `n` | `number` | `1` |  |

**Returns:** `number`

### math.randomseed

**Signature:** `math.randomseed(x: number): ()`

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

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `x` | `number` |  |  |

**Returns:** `()`

### math.round

**Signature:** `math.round(x: number): number`

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:** `number`

### math.sign

**Signature:** `math.sign(x: number): int`

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` |  |  |

**Returns:** `int`

### math.sin

**Signature:** `math.sin(x: number): number`

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

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `x` | `number` |  |  |

**Returns:** `number`

### math.sinh

**Signature:** `math.sinh(x: number): number`

Returns the hyperbolic sine of `x`.

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `x` | `number` |  |  |

**Returns:** `number`

### math.sqrt

**Signature:** `math.sqrt(x: number): number`

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` |  |  |

**Returns:** `number`

### math.tan

**Signature:** `math.tan(x: number): number`

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

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `x` | `number` |  |  |

**Returns:** `number`

### math.tanh

**Signature:** `math.tanh(x: number): number`

Returns the hyperbolic tangent of `x`.

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `x` | `number` |  |  |

**Returns:** `number`