Source: Roblox Creator Hub · CC BY 4.0 · View source · Code samples: MIT Imported 2026-10-03. Formatting adapted for this site.
vector
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
| Name | Type / Returns | Description |
|---|---|---|
| vector.zero | vector | Constant vector with all components set to 0. |
| vector.one | vector | Constant vector with all components set to 1. |
vector.zero
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.
| Field | Value |
|---|---|
| type | vector |
vector.one
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.
| Field | Value |
|---|---|
| type | vector |
Functions
| Name | Type / Returns | Description |
|---|---|---|
| vector.create | vector | Creates a new vector with the given component values. |
| vector.magnitude | number | Calculates the magnitude of a given vector. |
| vector.normalize | vector | Computes the normalized version (unit vector) of a given vector. |
| vector.cross | vector | Computes the cross product of two vectors. |
| vector.dot | number | Computes the dot product of two vectors. |
| vector.angle | number | Computes the angle between two vectors in radians. |
| vector.floor | vector | Applies math.floor() to every component of the input vector. |
| vector.ceil | vector | Applies math.ceil() to every component of the input vector. |
| vector.abs | vector | Applies math.abs() to every component of the input vector. |
| vector.sign | vector | Applies math.sign() to every component of the input vector. |
| vector.clamp | vector | Applies math.clamp() to every component of the input vector. |
| vector.lerp | vector | Returns a vector linearly interpolated between two vectors by a fractional alpha. |
| vector.max | vector | Applies math.max() to the corresponding components of the input vectors. |
| vector.min | vector | Applies math.min() to the corresponding components of the input vectors. |
vector.create
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).
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| x | number | The x component of the new vector. | |
| y | number | The y component of the new vector. | |
| z | number | The z component of the new vector. Defaults to 0 when omitted. |
Returns
| Type | Description |
|---|---|
| vector | A new vector with the specified x, y, and z component values. |
vector.magnitude
Returns the magnitude (Euclidean length) of the vector, computed as math.sqrt(vec.x^2 + vec.y^2 + vec.z^2).
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| vec | vector | The vector whose magnitude is computed. |
Returns
| Type | Description |
|---|---|
| number | The Euclidean length of the vector. |
vector.normalize
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.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| vec | vector | The vector to normalize. |
Returns
| Type | Description |
|---|---|
| vector | A unit vector pointing in the same direction as the input. |
vector.cross
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).
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| vec1 | vector | The first operand vector. | |
| vec2 | vector | The second operand vector. |
Returns
| Type | Description |
|---|---|
| vector | A vector perpendicular to both inputs whose magnitude equals the area of the parallelogram they span. |
vector.dot
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.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| vec1 | vector | The first operand vector. | |
| vec2 | vector | The second operand vector. |
Returns
| Type | Description |
|---|---|
| number | The scalar dot product of the two vectors. |
vector.angle
Computes the angle between two vectors in radians. The axis, if specified, is used to determine the sign of the angle.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| vec1 | vector | The first vector. | |
| vec2 | vector | The second vector. | |
| axis | vector? | An optional reference axis used to determine the sign of the returned angle. |
Returns
| Type | Description |
|---|---|
| number | The angle between the two vectors in radians, signed if an axis is provided. |
vector.floor
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)).
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| vec | vector | The vector whose components are rounded down. |
Returns
| Type | Description |
|---|---|
| vector | A new vector with each component rounded down to the nearest integer. |
vector.ceil
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)).
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| vec | vector | The vector whose components are rounded up. |
Returns
| Type | Description |
|---|---|
| vector | A new vector with each component rounded up to the nearest integer. |
vector.abs
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)).
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| vec | vector | The vector whose components are made absolute. |
Returns
| Type | Description |
|---|---|
| vector | A new vector with each component replaced by its absolute value. |
vector.sign
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.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| vec | vector | The vector whose component signs are extracted. |
Returns
| Type | Description |
|---|---|
| vector | A new vector where each component is the sign of the corresponding input component. |
vector.clamp
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.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| vec | vector | The vector whose components are clamped. | |
| min | vector | The vector of per-component minimum bounds. | |
| max | vector | The vector of per-component maximum bounds. Each component must be greater than or equal to the corresponding component of min. |
Returns
| Type | Description |
|---|---|
| vector | A new vector with each component clamped between the corresponding components of min and max. |
vector.lerp
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].
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| vec1 | vector | The starting vector (returned when alpha is 0). | |
| vec2 | vector | The ending vector (returned when alpha is 1). | |
| alpha | number | The interpolation fraction. Not clamped to [0, 1]. |
Returns
| Type | Description |
|---|---|
| vector | A vector interpolated component-wise between vec1 and vec2. |
vector.max
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.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| ... | vector | One or more vectors to compare component-wise. |
Returns
| Type | Description |
|---|---|
| vector | A new vector where each component is the maximum of the corresponding components across all inputs. |
vector.min
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.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| ... | vector | One or more vectors to compare component-wise. |
Returns
| Type | Description |
|---|---|
| vector | A new vector where each component is the minimum of the corresponding components across all inputs. |