> Agent-readable docs index: /llms.txt. Download /docs.zip to grep all markdown files locally.

---
title: math
description: Extended Lua math library functions
icon: calculator
---

The `math` namespace extends the standard Lua math library with additional helper functions and constants.

## abs

```lua
math.abs(x: number): number
```

> Returns the absolute value of x.

<Schema title="Parameters">
  <SchemaField name="x" type="number" required>
    Number
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="value" type="number">
    The absolute value of x.
  </SchemaField>
</Schema>

## acos

```lua
math.acos(x: number): number
```

> Returns the arc cosine of x (in radians).

<Schema title="Parameters">
  <SchemaField name="x" type="number" required>
    Number
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="value" type="number">
    The arc cosine of x (in radians).
  </SchemaField>
</Schema>

## asin

```lua
math.asin(x: number): number
```

> Returns the arc sine of x (in radians).

<Schema title="Parameters">
  <SchemaField name="x" type="number" required>
    Number
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="value" type="number">
    The arc sine of x (in radians).
  </SchemaField>
</Schema>

## atan

```lua
math.atan(x: number): number
```

> Returns the arc tangent of x (in radians).

<Schema title="Parameters">
  <SchemaField name="x" type="number" required>
    Number
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="value" type="number">
    The arc tangent of x (in radians).
  </SchemaField>
</Schema>

## atan2

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

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

<Schema title="Parameters">
  <SchemaField name="x" type="number" required>
    Number
  </SchemaField>

  <SchemaField name="y" type="number" required>
    Number
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="value" type="number">
    The arc tangent of y/x (in radians).
  </SchemaField>
</Schema>

## ceil

```lua
math.ceil(x: number): number
```

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

<Schema title="Parameters">
  <SchemaField name="x" type="number" required>
    Number
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="value" type="number">
    The smallest integer larger than or equal to x.
  </SchemaField>
</Schema>

## clamp

```lua
math.clamp(value: number[, min: number, max: number]): number
```

> Returns the clamped value.

<Schema title="Parameters">
  <SchemaField name="value" type="number" required>
    The value to clamp
  </SchemaField>

  <SchemaField name="min" type="number">
    The minimum value
  </SchemaField>

  <SchemaField name="max" type="number">
    The maximum value
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="value" type="number">
    The clamped value.
  </SchemaField>
</Schema>

## cos

```lua
math.cos(x: number): number
```

> Returns the cosine of x (assumed to be in radians).

<Schema title="Parameters">
  <SchemaField name="x" type="number" required>
    Number
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="value" type="number">
    The cosine of x (assumed to be in radians).
  </SchemaField>
</Schema>

## cosh

```lua
math.cosh(x: number): number
```

> Returns the hyperbolic cosine of x.

<Schema title="Parameters">
  <SchemaField name="x" type="number" required>
    Number
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="value" type="number">
    The hyperbolic cosine of x.
  </SchemaField>
</Schema>

## deg

```lua
math.deg(x: number): number
```

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

<Schema title="Parameters">
  <SchemaField name="x" type="number" required>
    Number
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="value" type="number">
    The angle x (given in radians) in degrees.
  </SchemaField>
</Schema>

## exp

```lua
math.exp(x: number): number
```

> Returns the value e power x.

<Schema title="Parameters">
  <SchemaField name="x" type="number" required>
    Number
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="value" type="number">
    The value e power x.
  </SchemaField>
</Schema>

## floor

```lua
math.floor(x: number): number
```

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

<Schema title="Parameters">
  <SchemaField name="x" type="number" required>
    Number
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="value" type="number">
    The largest integer smaller than or equal to x.
  </SchemaField>
</Schema>

## fmod

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

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

<Schema title="Parameters">
  <SchemaField name="x" type="number" required>
    Number
  </SchemaField>

  <SchemaField name="y" type="number" required>
    Number
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="value" type="number">
    The remainder of the division of x by y that rounds the quotient towards zero.
  </SchemaField>
</Schema>

## frexp

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

> $$
> x = m2^e
> $$
>
> Returns `m` and `e` such that `x = m2e`, `e` is an integer and the absolute value of `m` is in the range `[0.5, 1)` (or zero when `x` is zero).

<Schema title="Parameters">
  <SchemaField name="x" type="number" required>
    Number
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="m" type="number">
    The mantissa, whose absolute value is in the range `[0.5, 1)` (or zero when `x` is zero).
  </SchemaField>

  <SchemaField name="e" type="number">
    The exponent, an integer.
  </SchemaField>
</Schema>

## huge

```lua
math.huge: number
```

> The value HUGE\_VAL, a value larger than or equal to any other numerical value.

## ldexp

```lua
math.ldexp(x: number, e: number): number
```

> $$
> output = m2^e
> $$
>
> Returns `m2e` (e should be an integer).

<Schema title="Parameters">
  <SchemaField name="x" type="number" required>
    Number
  </SchemaField>

  <SchemaField name="e" type="number" required>
    Number
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="value" type="number">
    The value `m2e` (e should be an integer).
  </SchemaField>
</Schema>

## log

```lua
math.log(x: number): number
```

> Returns the natural logarithm of x.

<Schema title="Parameters">
  <SchemaField name="x" type="number" required>
    Number
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="value" type="number">
    The natural logarithm of x.
  </SchemaField>
</Schema>

## log10

```lua
math.log10(x: number): number
```

> Returns the base-10 logarithm of x.

<Schema title="Parameters">
  <SchemaField name="x" type="number" required>
    Number
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="value" type="number">
    The base-10 logarithm of x.
  </SchemaField>
</Schema>

## map

```lua
math.map(value: number, in_from: number, in_to: number, out_from: number, out_to: number[, should_clamp: boolean]): number
```

> Linearly maps two number ranges and returns the mapped value.

<Schema title="Parameters">
  <SchemaField name="value" type="number" required>
    The value to map
  </SchemaField>

  <SchemaField name="in_from" type="number" required>
    In minimum value
  </SchemaField>

  <SchemaField name="in_to" type="number" required>
    In maximum value
  </SchemaField>

  <SchemaField name="out_from" type="number" required>
    Out minimum value
  </SchemaField>

  <SchemaField name="out_to" type="number" required>
    Out maximum value
  </SchemaField>

  <SchemaField name="should_clamp" type="boolean">
    Clamp In range
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="value" type="number">
    The mapped value.
  </SchemaField>
</Schema>

## max

```lua
math.max(x: number[, ...]): number
```

> Returns the maximum value among its arguments.

<Schema title="Parameters">
  <SchemaField name="x" type="number" required>
    Number
  </SchemaField>

  <SchemaField name="..." type="any">
    Comma-separated numbers to concatenate with x
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="value" type="number">
    The maximum value among its arguments.
  </SchemaField>
</Schema>

## min

```lua
math.min(x: number[, ...]): number
```

> Returns the minimum value among its arguments.

<Schema title="Parameters">
  <SchemaField name="x" type="number" required>
    Number
  </SchemaField>

  <SchemaField name="..." type="any">
    Comma-separated numbers to concatenate with x
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="value" type="number">
    The minimum value among its arguments.
  </SchemaField>
</Schema>

## modf

```lua
math.modf(x: number): number
```

> Returns two numbers, the integral part of x and the fractional part of x.

<Schema title="Parameters">
  <SchemaField name="x" type="number" required>
    Number
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="integral" type="number">
    The integral part of x.
  </SchemaField>

  <SchemaField name="fractional" type="number">
    The fractional part of x.
  </SchemaField>
</Schema>

## normalize\_yaw

```lua
math.normalize_yaw(x: number): number
```

> Returns the normalized yaw angle value.

<Schema title="Parameters">
  <SchemaField name="x" type="number" required>
    Number
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="value" type="number">
    The normalized yaw angle value.
  </SchemaField>
</Schema>

## pi

```lua
math.pi: number
```

> The value of pi.

## pow

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

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

<Schema title="Parameters">
  <SchemaField name="x" type="number" required>
    Number
  </SchemaField>

  <SchemaField name="y" type="number" required>
    Number
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="value" type="number">
    The value x^y.
  </SchemaField>
</Schema>

## rad

```lua
math.rad(x: number): number
```

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

<Schema title="Parameters">
  <SchemaField name="x" type="number" required>
    Number
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="value" type="number">
    The angle x (given in degrees) in radians.
  </SchemaField>
</Schema>

## random

```lua
math.random([m [, n]]): number
```

> This function is an interface to the simple pseudo-random generator function rand provided by ANSI C. When called without arguments, returns a uniform pseudo-random real number in the range \[0,1). When called with an integer number m, math.random returns a uniform pseudo-random integer in the range \[1, m]. When called with two integer numbers m and n, math.random returns a uniform pseudo-random integer in the range \[m, n].

<Schema title="Parameters">
  <SchemaField name="m" type="number">
    Number
  </SchemaField>

  <SchemaField name="n" type="number">
    Number
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="value" type="number">
    A uniform pseudo-random number.
  </SchemaField>
</Schema>

## randomseed

```lua
math.randomseed(x: number): number
```

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

<Schema title="Parameters">
  <SchemaField name="x" type="number" required>
    Number
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="value" type="number">
    The seed value.
  </SchemaField>
</Schema>

## sin

```lua
math.sin(x: number): number
```

> Returns the sine of x (assumed to be in radians).

<Schema title="Parameters">
  <SchemaField name="x" type="number" required>
    Number
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="value" type="number">
    The sine of x (assumed to be in radians).
  </SchemaField>
</Schema>

## sinh

```lua
math.sinh(x: number): number
```

> Returns the hyperbolic sine of x.

<Schema title="Parameters">
  <SchemaField name="x" type="number" required>
    Number
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="value" type="number">
    The hyperbolic sine of x.
  </SchemaField>
</Schema>

## sqrt

```lua
math.sqrt(x: number): number
```

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

<Schema title="Parameters">
  <SchemaField name="x" type="number" required>
    Number
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="value" type="number">
    The square root of x.
  </SchemaField>
</Schema>

## tan

```lua
math.tan(x: number): number
```

> Returns the tangent of x (assumed to be in radians).

<Schema title="Parameters">
  <SchemaField name="x" type="number" required>
    Number
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="value" type="number">
    The tangent of x (assumed to be in radians).
  </SchemaField>
</Schema>

## tanh

```lua
math.tanh(x: number): number
```

> Returns the hyperbolic tangent of x.

<Schema title="Parameters">
  <SchemaField name="x" type="number" required>
    Number
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="value" type="number">
    The hyperbolic tangent of x.
  </SchemaField>
</Schema>
