math reference

math.* functions are pure and work anywhere. A null argument gives a null result unless noted.

Functions

math.abs

math.abs(value: number) -> same_numeric

Returns the absolute value of a number.

value keeps its type: an int returns an int and a float returns a float. Check for null or use ?? to supply a fallback before calling. Null float inputs produce null.

Returns same_numeric

math.acos

math.acos(value: float) -> float?

Returns the arccosine of a float in radians.

value must be in [-1.0, 1.0] for a real result. Values outside that range return null. Check for null before calling.

Returns float?

math.asin

math.asin(value: float) -> float?

Returns the arcsine of a float in radians.

value must be in [-1.0, 1.0] for a real result. Values outside that range return null. Check for null before calling.

Returns float?

math.atan

math.atan(value: float) -> float

Returns the arctangent of a number in radians.

The result is between -math.pi / 2.0 and math.pi / 2.0.

The result is a float. Check for null or use ?? to supply a fallback before calling. Null or NaN inputs return null.

Returns float

math.atan2

math.atan2(y: float, x: float) -> float

Returns the angle of a vector in radians.

y and x are the vector’s coordinates. The result is from -math.pi to math.pi, inclusive.

Check for null or use ?? to supply a fallback before calling. Null or NaN inputs return null.

Returns float

math.cbrt

math.cbrt(value: float) -> float

Returns the cube root of a number.

value can be negative, zero, or positive.

The result is a float. Check for null or use ?? to supply a fallback before calling. Null or NaN inputs return null.

Returns float

math.ceil

math.ceil(value: float) -> float

Rounds a number up to a whole number.

For example, 1.2 becomes 2.0 and -1.8 becomes -1.0.

The result is a float. Check for null or use ?? to supply a fallback before calling. Null or NaN inputs return null.

Returns float

math.ceilTo

math.ceilTo(value: float, step: float) -> float?

Rounds a float up to a multiple of step.

value is divided by step, rounded up, and multiplied by step. A zero, null, or NaN step returns null instead of stopping the script with an error. Check for null before calling.

Returns float?

math.clamp

math.clamp(value: number, min: number, max: number) -> same_numeric

Keeps a number within a range.

Returns value when it is between min and max, including both ends. Below the range it returns min; above the range it returns max.

Mixing ints and floats gives a float result. min > max stops the script with an error. Check for null or use ?? to supply a fallback before calling.

Returns same_numeric

math.cos

math.cos(value: float) -> float

Returns the cosine of an angle in radians.

value is the angle in radians.

The result is a float. Check for null or use ?? to supply a fallback before calling. Null or NaN inputs return null.

Returns float

math.cosh

math.cosh(value: float) -> float

Returns the hyperbolic cosine of a number.

value is the number to calculate from.

The result is a float. Check for null or use ?? to supply a fallback before calling. Null or NaN inputs return null.

Returns float

math.exp

math.exp(value: float) -> float

Returns e raised to a power.

value is the exponent. A result too large for a float may be infinite.

Check for null or use ?? to supply a fallback before calling. Null or NaN inputs return null.

Returns float

math.floor

math.floor(value: float) -> float

Rounds a number down to a whole number.

For example, 1.8 becomes 1.0 and -1.2 becomes -2.0.

The result is a float. Check for null or use ?? to supply a fallback before calling. Null or NaN inputs return null.

Returns float

math.floorTo

math.floorTo(value: float, step: float) -> float?

Rounds a float down to a multiple of step.

value is divided by step, rounded down, and multiplied by step. A zero, null, or NaN step returns null instead of stopping the script with an error. Check for null before calling.

Returns float?

math.isEven

math.isEven(value: int) -> bool

Tests whether an integer is even.

Returns true when value % 2 == 0. Check for null before using a nullable int. Supported integers range from math.minInt (-9223372036854775807) to math.maxInt (9223372036854775807).

Returns bool

math.isFinite

math.isFinite(value: float?) -> bool

Reports whether a number is finite and non-null.

Returns false for null, NaN, and positive or negative infinity; otherwise true.

This check does not change a nullable value’s type. Use x != null when you need to use x as a non-null value.

Returns bool

math.isOdd

math.isOdd(value: int) -> bool

Tests whether an integer is odd.

Returns true when value % 2 != 0. Check for null before using a nullable int. Supported integers range from math.minInt (-9223372036854775807) to math.maxInt (9223372036854775807).

Returns bool

math.log

math.log(value: float) -> float?

Returns the natural logarithm of a float.

value must be greater than 0.0 for a real result. Values at or below 0.0 return null. Check for null before calling.

Returns float?

math.log10

math.log10(value: float) -> float?

Returns the base-10 logarithm of a float.

value must be greater than 0.0 for a real result. Values at or below 0.0 return null. Check for null before calling.

Returns float?

math.log2

math.log2(value: float) -> float?

Returns the base-2 logarithm of a float.

value must be greater than 0.0 for a real result. Values at or below 0.0 return null. Check for null before calling.

Returns float?

math.max

math.max(value: number, values: number...) -> same_numeric

Returns the largest of one or more numbers.

Pass the first number as value and any others as values. Mixing ints and floats gives a float result.

Check for null or use ?? to supply a fallback before calling. NaN inputs produce null.

Returns same_numeric

math.min

math.min(value: number, values: number...) -> same_numeric

Returns the smallest of one or more numbers.

Pass the first number as value and any others as values. Mixing ints and floats gives a float result.

Check for null or use ?? to supply a fallback before calling. NaN inputs produce null.

Returns same_numeric

math.pow

math.pow(base: float, exponent: float) -> float?

Raises a number to a power.

Returns base raised to exponent, as a float. Inputs with no real-number result, such as a negative base with a fractional exponent, return null.

Check for null or use ?? to supply a fallback before calling.

Returns float?

math.randomFloat

math.randomFloat(min: float, max: float) -> float

Returns a random float from min up to, but not including, max.

Both bounds are required. Every equal-sized part of the range is equally likely. min >= max stops the script with an error.

Call this inside a handler. Replaying the same script uses the same sequence of random values.

Returns float

Available in Handlers and functions called from handlers.

math.randomInt

math.randomInt(min: int, max: int) -> int

Returns a random whole number between min and max, including both.

Both bounds are required. Every integer in the range is equally likely. min > max stops the script with an error. Bounds must be within math.minInt (-9223372036854775807) and math.maxInt (9223372036854775807).

Replaying the same script uses the same sequence of random values.

Returns int

Available in Handlers and functions called from handlers.

math.round

math.round(value: number, decimals: int = 0) -> float

Rounds a number to a chosen number of decimal places.

value can be an int or float; the result is always a float. decimals defaults to 0, which rounds to a whole number. Negative decimals round to tens, hundreds, and so on.

Check for null or use ?? to supply a fallback before calling. NaN inputs return null.

Returns float

math.roundTo

math.roundTo(value: float, step: float) -> float?

Rounds a float to the nearest multiple of step.

value is divided by step, rounded to the nearest integer value, and multiplied by step. A zero, null, or NaN step returns null instead of stopping the script with an error. Check for null before calling.

Returns float?

math.safeDiv

math.safeDiv(num: float?, den: float?, fallback: float = 0) -> float?

Returns a division result with a fallback for zero or missing denominators.

num is the numerator. den is the denominator; zero or null den returns fallback. Null num returns null because the numerator is missing. Otherwise the result is num / den.

Returns float?

math.sign

math.sign(value: float) -> float

Returns -1.0, 0.0, or 1.0 for a number’s sign.

Returns -1.0 for negative values, 1.0 for positive values, and 0.0 for both 0.0 and -0.0.

The result is a float. Check for null or use ?? to supply a fallback before calling. Null or NaN inputs return null.

Returns float

math.sin

math.sin(value: float) -> float

Returns the sine of an angle in radians.

value is the angle in radians.

The result is a float. Check for null or use ?? to supply a fallback before calling. Null or NaN inputs return null.

Returns float

math.sinh

math.sinh(value: float) -> float

Returns the hyperbolic sine of a number.

value is the number to calculate from.

The result is a float. Check for null or use ?? to supply a fallback before calling. Null or NaN inputs return null.

Returns float

math.sqrt

math.sqrt(value: float) -> float?

Returns the square root of a float.

value must be non-negative for a real result. Negative values produce null. Check for null before calling.

Returns float?

math.tan

math.tan(value: float) -> float

Returns the tangent of an angle in radians.

value is the angle in radians. Near odd multiples of math.pi / 2.0, the result may be very large or infinite.

Check for null or use ?? to supply a fallback before calling. Null or NaN inputs return null.

Returns float

math.tanh

math.tanh(value: float) -> float

Returns the hyperbolic tangent of a number.

Returns a value from -1.0 to 1.0.

The result is a float. Check for null or use ?? to supply a fallback before calling. Null or NaN inputs return null.

Returns float

math.trunc

math.trunc(value: float) -> float

Removes the fractional part of a number.

Rounds toward zero: 1.8 becomes 1.0 and -1.8 becomes -1.0.

The result is a float. Check for null or use ?? to supply a fallback before calling. Null or NaN inputs return null.

Returns float

Constants