$math

Vectors, rotations, interpolation, clamping, trigonometry.

86 natives. Read-only natives only look things up; the rest change something. Parameter types use the language's names (Types).

abs

read-only

$math.abs(value: var) -> var

Get the absolute value.

Parameter	Type	Meaning
value	var	Argument

Returns var: Result

acos

read-only

$math.acos(value: var) -> var

Take the arc cosine of a value.

Parameter	Type	Meaning
value	var	Argument

Returns var: Result

angle

read-only

$math.angle(degrees: var, radians: var) -> float

Convert from degrees or radians to internal angle type.

Parameter	Type	Meaning
degrees	var	The value in degrees
radians	var	The value in radians

Returns float: Result as an angle

asin

read-only

$math.asin(value: var) -> var

Take the arc sine of a value.

Parameter	Type	Meaning
value	var	Argument

Returns var: Result

atan

read-only

$math.atan(value: var) -> var

Take the arc tangent of a value.

Parameter	Type	Meaning
value	var	Argument

Returns var: Result

atan2

read-only

$math.atan2(y: var, x: var) -> var

Take the arc tangent of a pair of values.

Parameter	Type	Meaning
y	var	Y axis value
x	var	X axis value

Returns var: Result

ceili

read-only

$math.ceili(value: var) -> int

Return the lowest integer >= value.

Parameter	Type	Meaning
value	var	The value to ceil

Returns int: Result

clamp

read-only

$math.clamp(value: var, min: var, max: var) -> var

Clamp a value between a min and max.

Parameter	Type	Meaning
value	var	The value to clamp
min	var	The minimum value
max	var	The maximum value

Returns var: Result

clamp_length

read-only

$math.clamp_length(value: vec3, min_len: float, max_len: float) -> vec3

Clamps the magnitude of a vector.

Parameter	Type	Meaning
value	vec3	Input vector
min_len	float	The lower bound of length clamp
max_len	float	The upper bound of length clamp

Returns vec3: Result

clamp_length_2d

read-only

$math.clamp_length_2d(value: vec2, min_len: float, max_len: float) -> vec2

Clamps the magnitude of a 2d vector.

Parameter	Type	Meaning
value	vec2	Input vector
min_len	float	The lower bound of length clamp
max_len	float	The upper bound of length clamp

Returns vec2: Result

cos

read-only

$math.cos(angle: var) -> var

Take the cosine of a value.

Parameter	Type	Meaning
angle	var	Argument

Returns var: Result

critically_damped_spring_angular

read-only

$math.critically_damped_spring_angular(current: var, target: var, velocity: var, damping_value: var, delta_time: var) -> float

Use a critically damped spring to update an angular value. Handles unwinding of angles.

Parameter	Type	Meaning
current	var	The current value in radians.
target	var	The desired value in radians.
velocity	var	The rate of change in the value desired.
damping_value	var	The spring dampening value.
delta_time	var	The time elapsed in seconds.

Returns float: New value after spring has been applied.

critically_damped_spring_standard

read-only

$math.critically_damped_spring_standard(current: var, target: var, velocity: var, damping_value: var, delta_time: var) -> float

Use a critically damped spring to update a linear value.

Parameter	Type	Meaning
current	var	The current value.
target	var	The desired value.
velocity	var	The rate of change in the value desired.
damping_value	var	The spring dampening value.
delta_time	var	The time elapsed in seconds.

Returns float: New value after spring has been applied.

critically_damped_spring_standard_3d

read-only

$math.critically_damped_spring_standard_3d(current: var, target: var, velocity: var, damping_value: var, delta_time: var) -> vec3

Use a critically damped spring to update a linear value.

Parameter	Type	Meaning
current	var	The current value.
target	var	The desired value.
velocity	var	The rate of change in the value desired.
damping_value	var	The spring dampening value.
delta_time	var	The time elapsed in seconds.

Returns vec3: New value after spring has been applied.

cross

read-only

$math.cross(a: var, b: var) -> vec3

Take the cross product of two vectors.

Parameter	Type	Meaning
a	var	First argument
b	var	Second argument

Returns vec3: Result

curve_max_x

read-only

$math.curve_max_x(curve: Reference) -> float

Find a curve's maximum x value or position.

Parameter	Type	Meaning
curve	Reference	The curve.

Returns float: The maximum position in the curve.

curve_max_y

read-only

$math.curve_max_y(curve: Reference) -> float

Find a curve's approximate maximum y value.

Parameter	Type	Meaning
curve	Reference	The curve.

Returns float: The maximum value in the curve.

curve_min_x

read-only

$math.curve_min_x(curve: Reference) -> float

Find a curve's minimum x value or position.

Parameter	Type	Meaning
curve	Reference	The curve.

Returns float: The minimum position in the curve.

curve_min_y

read-only

$math.curve_min_y(curve: Reference) -> float

Find a curve's approximate minimum y value.

Parameter	Type	Meaning
curve	Reference	The curve.

Returns float: The minimum value in the curve.

deg2rad

read-only

$math.deg2rad(degrees: var) -> var

Convert from degrees to radians. Accepts float, vec2, vec3, or vec4.

Parameter	Type	Meaning
degrees	var	The value in degrees

Returns var: Result in radians

distance

read-only

$math.distance(a: var, b: var) -> float

Get the distance between two vectors.

Parameter	Type	Meaning
a	var	Argument
b	var	Argument

Returns float: Result

distance_2d

read-only

$math.distance_2d(a: var, b: var) -> float

Get the 2D distance between two vectors

Parameter	Type	Meaning
a	var	Argument
b	var	Argument

Returns float: Result

dividei

read-only

$math.dividei(a: int, b: int) -> int

Use integer division to divide two integers (a / b).

Parameter	Type	Meaning
a	int	First argument
b	int	Second argument

Returns int: Integer result

dot

read-only

$math.dot(a: var, b: var) -> float

Take the dot product of two vectors.

Parameter	Type	Meaning
a	var	First argument
b	var	Second argument

Returns float: Result

eulers_from_rotation

read-only

$math.eulers_from_rotation(quat: vec4) -> vec3

Generate (roll, pitch, yaw) vector from a quaternion.

Parameter	Type	Meaning
quat	vec4	The rotation.

Returns vec3: A vector containing (roll, pitch, yaw)

eval_curve

read-only

$math.eval_curve(curve: Reference, t: float) -> float

Evaluate value of a curve at a specified position.

Parameter	Type	Meaning
curve	Reference	The curve.
t	float	The position.

Returns float: The value of the curve at the point.

floori

read-only

$math.floori(value: var) -> int

Return the highest integer <= value.

Parameter	Type	Meaning
value	var	The value to floor

Returns int: Result

get_closest_point_on_box

read-only

$math.get_closest_point_on_box(point: vec3, extents: vec3, box_offset: vec3, transform: Component, return_relative: bool) -> vec3

Finds the closest point on a box, from another point.

Parameter	Type	Meaning
point	vec3	Point to test.
extents	vec3	The box extents.
box_offset	vec3	offset from transform position.
transform	Component	Optional. The transform component of the box. If null, the box is in world space.
return_relative	bool	Whether to return relative position to the input transform. If false, returns absolute position.

Returns vec3: The closest point on the box.

get_closest_point_on_line_segment

$math.get_closest_point_on_line_segment(a: vec3, b: vec3, point: vec3) -> vec3

Finds the closest point on a line segment, from another point.

Parameter	Type	Meaning
a	vec3	One end of line segment
b	vec3	The other end of line segment
point	vec3	Point to test.

Returns vec3: The closest point on the line segment

hours

read-only

$math.hours(time: var) -> float

Convert a time value to hours.

Parameter	Type	Meaning
time	var	The time value

Returns float: Result

length

read-only

$math.length(value: var) -> float

Get the length of the vector.

Parameter	Type	Meaning
value	var	Argument

Returns float: Result

length_2d

read-only

$math.length_2d(value: var) -> float

Get the 2D length of the vector using only the X and Y components.

Parameter	Type	Meaning
value	var	Argument

Returns float: Result

length_squared

read-only

$math.length_squared(value: var) -> float

Get the squared length of the vector

Parameter	Type	Meaning
value	var	Argument

Returns float: Result

lerp

read-only

$math.lerp(min: var, max: var, t: var) -> var

Linearly interpolate a value between two others.

Parameter	Type	Meaning
min	var	The value returned when t=0
max	var	The value returned when t=1
t	var	The interpolation factor between 0 and 1

Returns var: Result

ln

read-only

$math.ln(value: var) -> var

Take the natural log of a value.

Parameter	Type	Meaning
value	var	Argument

Returns var: Result

make_mask

read-only

$math.make_mask(value: var) -> int

Generate a base-10 mask given a value.

Parameter	Type	Meaning
value	var	The value to add to the mask.

Returns int: Generated mask.

map_range

read-only

$math.map_range(in_min: var, in_max: var, out_min: var, out_max: var, value: var) -> var

Linearly map a value from one range to another. The result is clamped between out_min and out_max.

Parameter	Type	Meaning
in_min	var	The lower end of the input range.
in_max	var	The upper end of the input range.
out_min	var	The lower end of the output range.
out_max	var	The upper end of the output range.
value	var	The value to be remapped.

Returns var: Result

max

read-only

$math.max(a: var, b: var) -> var

Get the maximum of two values.

Parameter	Type	Meaning
a	var	First argument
b	var	Second argument

Returns var: Result

milliseconds

read-only

$math.milliseconds(time: var) -> float

Convert a time value to milliseconds.

Parameter	Type	Meaning
time	var	The time value

Returns float: Result

min

read-only

$math.min(a: var, b: var) -> var

Get the minimum of two values.

Parameter	Type	Meaning
a	var	First argument
b	var	Second argument

Returns var: Result

minutes

read-only

$math.minutes(time: var) -> float

Convert a time value to minutes.

Parameter	Type	Meaning
time	var	The time value

Returns float: Result

normalize

read-only

$math.normalize(value: var) -> var

Normalize a vector.

Parameter	Type	Meaning
value	var	Argument

Returns var: Result

normalize_2d

read-only

$math.normalize_2d(value: var) -> vec2

Return a normalized 2D vector using just the X and Y components.

Parameter	Type	Meaning
value	var	Argument

Returns vec2: Result

normalize_rotation

$math.normalize_rotation(quat: vec4) -> vec4

Normalize a quaternion rotation.

Parameter	Type	Meaning
quat	vec4	The quaternion.

Returns vec4: New rotation.

point_in_box

read-only

$math.point_in_box(point: vec3, extents: vec3, box_offset: vec3, transform: Component) -> bool

Test whether a point is inside a box

Parameter	Type	Meaning
point	vec3	Point to test.
extents	vec3	The box extents.
box_offset	vec3	offset from transform position.
transform	Component	Optional. The transform component of the box. If null, the box is in world space.

Returns bool: Whether the point is inside

point_in_poly

read-only

$math.point_in_poly(test: vec2, poly: list) -> bool

Takes a point and a polygon and returns true if the point is inside.

Parameter	Type	Meaning
test	vec2	Point to test.
poly	list	List of vertices that define a polygon.

Returns bool: True if point is inside poly.

pow

read-only

$math.pow(base: var, exponent: var) -> var

Get the power of two values.

Parameter	Type	Meaning
base	var	Base value
exponent	var	Exponent value

Returns var: Result

project_point_onto_line_segment

$math.project_point_onto_line_segment(a: vec3, b: vec3, point: vec3) -> list

Finds the shortest distance from a point to line segment, returns ratio along segment and distance from segment

Parameter	Type	Meaning
a	vec3	One end of line segment
b	vec3	The other end of line segment
point	vec3	Point to test.

Returns list: The closest point on the line segment

quat_inverse

read-only

$math.quat_inverse(quat: vec4) -> vec4

Invert a quaternion

Parameter	Type	Meaning
quat	vec4	The quaternion to invert.

Returns vec4: New quaternion.

quat_mul

read-only

$math.quat_mul(a: vec4, b: vec4) -> vec4

Multiply quaternions

Parameter	Type	Meaning
a	vec4	The first quaternion.
b	vec4	The second quaternion.

Returns vec4: New quaternion.

rad2deg

read-only

$math.rad2deg(radians: var) -> var

Convert from radians to degrees. Accepts float, vec2, vec3, or vec4.

Parameter	Type	Meaning
radians	var	The value in radians

Returns var: Result in degrees

randb

read-only

$math.randb() -> bool

Get a random bool.

Returns bool: Result

randf

read-only

$math.randf(min: float, max: float) -> float

Get a random float from min to max (inclusive).

Parameter	Type	Meaning
min	float	The minimum value
max	float	The maximum value (INCLUSIVE)

Returns float: Result

randi

read-only

$math.randi(min: int, max: int) -> int

Get a random integer from min to max (inclusive).

Parameter	Type	Meaning
min	int	The minimum value
max	int	The maximum value (INCLUSIVE)

Returns int: Result

randv

read-only

$math.randv(min: vec3, max: vec3) -> vec3

Get a random vector with values from min to max (inclusive).

Parameter	Type	Meaning
min	vec3	The minimum value
max	vec3	The maximum value

Returns vec3: Result

reverse_lookup_curve

read-only

$math.reverse_lookup_curve(curve: Reference, value: float, sub_divisions: int) -> float

Search for the first position in a curve where the value passed occurs. This only works with curves that have more than one point and do not change direction in the y axis.

Parameter	Type	Meaning
curve	Reference	The curve.
value	float	The value to search for.
sub_divisions	int	The number of times to subdivide the curve to find the value (precision)

Returns float: The position along the curve where the value first occurs or -1 if the value never occurs.

rotate_vec

read-only

$math.rotate_vec(vec: vec3, axis: vec3, angle: float) -> vec3

Rotate a vector around an axis by an angle.

Parameter	Type	Meaning
vec	vec3	The vector to rotate.
axis	vec3	The axis about which to rotate.
angle	float	The angle (radians) about the axis.

Returns vec3: New vector.

rotate_vec_2d

$math.rotate_vec_2d(vec: vec2, angle: float) -> vec2

Rotate a 2D vector around it's pivot.

Parameter	Type	Meaning
vec	vec2	The vector to rotate.
angle	float	The angle (radians) to rotate in radians.

Returns vec2: New vector.

rotate_vec_by_quaternion

read-only

$math.rotate_vec_by_quaternion(vec: vec3, quat: vec4) -> vec3

Rotate a vector by a quaternion.

Parameter	Type	Meaning
vec	vec3	The vector to rotate.
quat	vec4	The rotation.

Returns vec3: New vector.

rotation_from_axis_angle

read-only

$math.rotation_from_axis_angle(axis: vec3, angle: float) -> vec4

Generate a quaternion from an axis and angle.

Parameter	Type	Meaning
axis	vec3	The axis.
angle	float	The angle (radians) about the axis.

Returns vec4: New rotation.

rotation_from_euler_angles

read-only

$math.rotation_from_euler_angles(eulers: vec3) -> vec4

Create a quaternion from radian euler angles

Parameter	Type	Meaning
eulers	vec3	The X (roll), Y (pitch), and Z (yaw) rotations in euler angles as radians

Returns vec4: New rotation.

rotation_from_forward

read-only

$math.rotation_from_forward(forward: vec3) -> vec4

Generate a quaternion from a forward vector.

Parameter	Type	Meaning
forward	vec3	The forward vector.

Returns vec4: New rotation.

rotation_from_forward_up

read-only

$math.rotation_from_forward_up(forward: vec3, up: vec3) -> vec4

Generate a quaternion from a forward and up vector.

Parameter	Type	Meaning
forward	vec3	The forward vector.
up	vec3	The up vector.

Returns vec4: New rotation.

rotation_mul

read-only

$math.rotation_mul(a: vec4, b: vec4) -> vec4

Multiply two quaternion rotations.

Parameter	Type	Meaning
a	vec4	The first quaternion.
b	vec4	The second quaternion.

Returns vec4: New rotation.

rotation_to_angle

read-only

$math.rotation_to_angle(quat: vec4) -> float

Convert a quaternion to an angle of rotation.

Parameter	Type	Meaning
quat	vec4	The rotation.

Returns float: Angle of rotation.

rotation_to_axis

read-only

$math.rotation_to_axis(quat: vec4) -> vec3

Convert a quaternion to an axis of rotation.

Parameter	Type	Meaning
quat	vec4	The rotation.

Returns vec3: Axis of rotation.

roundi

read-only

$math.roundi(value: var) -> int

Return value rounded to the nearest integer (0.5 rounds up).

Parameter	Type	Meaning
value	var	The value to round

Returns int: Result

saturate

read-only

$math.saturate(value: var) -> var

Clamp a value between 0 and 1.

Parameter	Type	Meaning
value	var	Argument

Returns var: Result

seconds

read-only

$math.seconds(time: var) -> float

Convert a time value to seconds.

Parameter	Type	Meaning
time	var	The time value

Returns float: Result

shift_within_pi

read-only

$math.shift_within_pi(current: var, target: var) -> var

Add or subtract multiples of 2pi to the first parameter to be within pi of the second parameter. Note: Expects radians

Parameter	Type	Meaning
current	var	The value to be shifted
target	var	The reference value

Returns var: Result

sign

read-only

$math.sign(value: var) -> var

Get the sign of value.

Parameter	Type	Meaning
value	var	Argument

Returns var: Result

sin

read-only

$math.sin(angle: var) -> var

Take the sine of a value.

Parameter	Type	Meaning
angle	var	Argument

Returns var: Result

slerp

read-only

$math.slerp(quat_a: vec4, quat_b: vec4, param: float) -> vec4

Interpolate between 2 quaternions

Parameter	Type	Meaning
quat_a	vec4	The first quaternion
quat_b	vec4	The second quaternion
param	float	The interpolation parameter

Returns vec4: Interpolated rotation.

slerp_fast

read-only

$math.slerp_fast(quat_a: vec4, quat_b: vec4, param: float) -> vec4

Interpolate between 2 quaternions, but faster and less accurate

Parameter	Type	Meaning
quat_a	vec4	The first quaternion
quat_b	vec4	The second quaternion
param	float	The interpolation parameter

Returns vec4: Interpolated rotation.

sqrt

read-only

$math.sqrt(value: var) -> var

Get the square root.

Parameter	Type	Meaning
value	var	Argument

Returns var: Result

srand

$math.srand(seed: var)

Set the random seed for the current instance of the calling script.

Parameter	Type	Meaning
seed	var	The seed value

srand_with_virtual_time

$math.srand_with_virtual_time()

Set the random seed for the current instance of the calling script using virtual time.

tan

read-only

$math.tan(angle: var) -> var

Take the tangent of a value.

Parameter	Type	Meaning
angle	var	Argument

Returns var: Result

truncatei

read-only

$math.truncatei(value: var) -> int

Return value with fractional portion removed.

Parameter	Type	Meaning
value	var	The value to truncate

Returns int: Result

unwind_angle

read-only

$math.unwind_angle(radians: var) -> var

Add or subtract multiples of 2pi to the value until it is between 0 and 2pi.

Parameter	Type	Meaning
radians	var	Argument

Returns var: Result

unwind_angle_zero

read-only

$math.unwind_angle_zero(radians: var) -> var

Add or subtract multiples of 2pi to the value until it is between -pi and pi.

Parameter	Type	Meaning
radians	var	Argument

Returns var: Result

vec2

read-only

$math.vec2(x: float, y: float) -> vec2

Create a 2-component vector.

Parameter	Type	Meaning
x	float	X-component
y	float	Y-component

Returns vec2: Result

vec3

read-only

$math.vec3(x: float, y: float, z: float) -> vec3

Create a 3-component vector.

Parameter	Type	Meaning
x	float	X-component
y	float	Y-component
z	float	Z-component

Returns vec3: Result

vec3_components_in_range

$math.vec3_components_in_range(vec: vec3, min: vec3, max: vec3) -> bool

Determines whether or not the X, Y and Z components of a vec3 fall within a given range.

Parameter	Type	Meaning
vec	vec3	The vector to test.
min	vec3	The minimum values in the range.
max	vec3	The maximum values of the range.

Returns bool: True if all components fall within the specified range, false otherwise.

vec4

read-only

$math.vec4(x: float, y: float, z: float, w: float) -> vec4

Create a 4-component vector. Only intended to be used for color and radian rotations.

Parameter	Type	Meaning
x	float	X-component
y	float	Y-component
z	float	Z-component
w	float	W-component

Returns vec4: Result

wrap

read-only

$math.wrap(value: var, left_bound: var, right_bound: var) -> var

Wrap a value between a min and max bound.

Parameter	Type	Meaning
value	var	The value to wrap
left_bound	var	The lesser boundary.
right_bound	var	The greater boundary.

Returns var: Result