Roblox UtilitiesDevlHub Roblox Documentation

Library

vector

A library of vector functions.

This library implements functionality for the vector type in addition to the built-in primitive operator support. It uses vectors with three components (x, y, and z).

Individual vector components can be accessed using the fields x or X, y or Y, z or Z. Since vector values are immutable, writing to individual components is not supported.

Properties 2#

zerovectorConstant vector with all components set to 0.
onevectorConstant vector with all components set to 1.

zero: vector#

A pre-allocated constant equivalent to vector.create(0, 0, 0). Useful as a default value or additive identity in vector arithmetic without allocating a new vector each time.

one: vector#

A pre-allocated constant equivalent to vector.create(1, 1, 1). Useful as a multiplicative identity or scale factor in vector arithmetic without allocating a new vector each time.

Functions 14#

createCreates a new vector with the given component values.
magnitudeCalculates the magnitude of a given vector.
normalizeComputes the normalized version (unit vector) of a given vector.
crossComputes the cross product of two vectors.
dotComputes the dot product of two vectors.
angleComputes the angle between two vectors in radians.
floorApplies math.floor() to every component of the input vector.
ceilApplies math.ceil() to every component of the input vector.
absApplies math.abs() to every component of the input vector.
signApplies math.sign() to every component of the input vector.
clampApplies math.clamp() to every component of the input vector.
lerpReturns a vector linearly interpolated between two vectors by a fractional alpha.
maxApplies math.max() to the corresponding components of the input vectors.
minApplies math.min() to the corresponding components of the input vectors.

create(x: number, y: number, z: number): vector#

Creates a new vector with the given component values. The z parameter defaults to 0 when omitted, so vector.create(1, 2) is equivalent to vector.create(1, 2, 0).

NameTypeDefaultDescription
xnumberThe x component of the new vector.
ynumberThe y component of the new vector.
znumberThe z component of the new vector. Defaults to 0 when omitted.
Returns
  • vector — A new vector with the specified x, y, and z component values.

magnitude(vec: vector): number#

Returns the magnitude (Euclidean length) of the vector, computed as math.sqrt(vec.x^2 + vec.y^2 + vec.z^2).

NameTypeDefaultDescription
vecvectorThe vector whose magnitude is computed.
Returns
  • number — The Euclidean length of the vector.

normalize(vec: vector): vector#

Returns a unit vector (magnitude of 1) pointing in the same direction as the input. Computed as vec / vector.magnitude(vec). If the input vector has zero magnitude, the result contains nan components.

NameTypeDefaultDescription
vecvectorThe vector to normalize.
Returns
  • vector — A unit vector pointing in the same direction as the input.

cross(vec1: vector, vec2: vector): vector#

Returns the cross product of two vectors, which is a vector perpendicular to both inputs whose magnitude equals the area of the parallelogram they span. The result is computed as vector.create(vec1.y*vec2.z - vec1.z*vec2.y, vec1.z*vec2.x - vec1.x*vec2.z, vec1.x*vec2.y - vec1.y*vec2.x).

NameTypeDefaultDescription
vec1vectorThe first operand vector.
vec2vectorThe second operand vector.
Returns
  • vector — A vector perpendicular to both inputs whose magnitude equals the area of the parallelogram they span.

dot(vec1: vector, vec2: vector): number#

Returns the dot product (scalar product) of two vectors, computed as vec1.x*vec2.x + vec1.y*vec2.y + vec1.z*vec2.z. The result is a single number equal to the product of the magnitudes of the two vectors times the cosine of the angle between them.

NameTypeDefaultDescription
vec1vectorThe first operand vector.
vec2vectorThe second operand vector.
Returns
  • number — The scalar dot product of the two vectors.

angle(vec1: vector, vec2: vector, axis: vector?): number#

Computes the angle between two vectors in radians. The axis, if specified, is used to determine the sign of the angle.

NameTypeDefaultDescription
vec1vectorThe first vector.
vec2vectorThe second vector.
axisvector?An optional reference axis used to determine the sign of the returned angle.
Returns
  • number — The angle between the two vectors in radians, signed if an axis is provided.

floor(vec: vector): vector#

Returns a new vector with each component rounded down to the nearest integer, equivalent to vector.create(math.floor(vec.x), math.floor(vec.y), math.floor(vec.z)).

NameTypeDefaultDescription
vecvectorThe vector whose components are rounded down.
Returns
  • vector — A new vector with each component rounded down to the nearest integer.

ceil(vec: vector): vector#

Returns a new vector with each component rounded up to the nearest integer, equivalent to vector.create(math.ceil(vec.x), math.ceil(vec.y), math.ceil(vec.z)).

NameTypeDefaultDescription
vecvectorThe vector whose components are rounded up.
Returns
  • vector — A new vector with each component rounded up to the nearest integer.

abs(vec: vector): vector#

Returns a new vector with each component replaced by its absolute value, equivalent to vector.create(math.abs(vec.x), math.abs(vec.y), math.abs(vec.z)).

NameTypeDefaultDescription
vecvectorThe vector whose components are made absolute.
Returns
  • vector — A new vector with each component replaced by its absolute value.

sign(vec: vector): vector#

Returns a new vector where each component is 1 if the corresponding input component is positive, -1 if negative, or 0 if zero. Equivalent to vector.create(math.sign(vec.x), math.sign(vec.y), math.sign(vec.z)). The behavior for negative zero and nan is consistent with math.sign.

NameTypeDefaultDescription
vecvectorThe vector whose component signs are extracted.
Returns
  • vector — A new vector where each component is the sign of the corresponding input component.

clamp(vec: vector, min: vector, max: vector): vector#

Returns a new vector with each component clamped between the corresponding components of min and max. Each component of max must be greater than or equal to the corresponding component of min; otherwise, an error is raised.

NameTypeDefaultDescription
vecvectorThe vector whose components are clamped.
minvectorThe vector of per-component minimum bounds.
maxvectorThe vector of per-component maximum bounds. Each component must be greater than or equal to the corresponding component of min.
Returns
  • vector — A new vector with each component clamped between the corresponding components of min and max.

lerp(vec1: vector, vec2: vector, alpha: number): vector#

Returns a vector linearly interpolated between two vectors (vec1, vec2) by the fraction alpha. Note that alpha is not limited to the range [0, 1].

NameTypeDefaultDescription
vec1vectorThe starting vector (returned when alpha is 0).
vec2vectorThe ending vector (returned when alpha is 1).
alphanumberThe interpolation fraction. Not clamped to [0, 1].
Returns
  • vector — A vector interpolated component-wise between vec1 and vec2.

max(...: vector): vector#

Returns a new vector where each component is the maximum of the corresponding components across all input vectors. Accepts a variadic number of vectors (at least one). When a component is nan in one vector but a valid number in another, the valid number is used.

NameTypeDefaultDescription
...vectorOne or more vectors to compare component-wise.
Returns
  • vector — A new vector where each component is the maximum of the corresponding components across all inputs.

min(...: vector): vector#

Returns a new vector where each component is the minimum of the corresponding components across all input vectors. Accepts a variadic number of vectors (at least one). When a component is nan in one vector but a valid number in another, the valid number is used.

NameTypeDefaultDescription
...vectorOne or more vectors to compare component-wise.
Returns
  • vector — A new vector where each component is the minimum of the corresponding components across all inputs.