Data type

`Vector3`

Represents a 3D value with a direction and magnitude.

The Vector3 data type represents a vector in 3D space, typically used as a point in 3D space or the dimensions of a rectangular prism. Vector3 supports basic component-based arithmetic operations (sum, difference, product, and quotient) and these operations can be applied on the left or right hand side to either another Vector3 or a number. It also features methods for common vector operations, such as Cross() and Dot().

Alternatively to Vector3, consider using the methods and properties of the vector library.

Some example usages of Vector3 are the Position, Rotation, and Size of parts, for example:

Luau

local part = Instance.new("Part")
part.Position = part.Position + Vector3.new(5, 2, 10) -- Move part by (5, 2, 10)
print(part.Position) --> 5, 2, 10

Vector3 is also commonly used when constructing more complex 3D data types such as CFrame. Many of these data types' methods will use a Vector3 within their parameters, such as CFrame:PointToObjectSpace().

Constructors 3#

new	Returns a new `Vector3` from the given `x`, `y`, and `z` components.
FromNormalId	Returns a new `Vector3` in the given direction.
FromAxis	Returns a new `Vector3` for the given axis.

`new(x: number = 0, y: number = 0, z: number = 0)`#

Returns a new Vector3 using the given x, y, and z components.

Name	Type	Default	Description
`x`	`number`	`0`	The x-axis component of the vector.
`y`	`number`	`0`	The y-axis component of the vector.
`z`	`number`	`0`	The z-axis component of the vector.

`FromNormalId(normal: NormalId)`#

Returns a unit Vector3 pointing in the direction of the given NormalId. For example, NormalId.Top returns (0, 1, 0) and NormalId.Front returns (0, 0, -1).

Luau

print(Vector3.FromNormalId(Enum.NormalId.Right)) --> 1, 0, 0
print(Vector3.FromNormalId(Enum.NormalId.Left))  --> -1, 0, 0

Name	Type	Default	Description
`normal`	`NormalId`		The `NormalId` specifying the face direction to convert into a unit vector.

`FromAxis(axis: Axis)`#

Returns a unit Vector3 for the given Axis. The mapping is Axis.X to (1, 0, 0), Axis.Y to (0, 1, 0), and Axis.Z to (0, 0, 1).

Luau

print(Vector3.FromAxis(Enum.Axis.X)) --> 1, 0, 0
print(Vector3.FromAxis(Enum.Axis.Z)) --> 0, 0, 1

Name	Type	Default	Description
`axis`	`Axis`		The `Axis` specifying which coordinate axis to convert into a unit vector.

Constants 5#

zero	A `Vector3` with a magnitude of `0`.
one	A `Vector3` with a value of `1` on every axis.
xAxis	A `Vector3` with a value of `1` on the X axis.
yAxis	A `Vector3` with a value of `1` on the Y axis.
zAxis	A `Vector3` with a value of `1` on the Z axis.

`zero`: `Vector3`#

A Vector3 with a magnitude of 0.

This API member is a constant, and must be accessed through the Vector3 global as opposed to an individual Vector3 object.

Luau

print(Vector3.zero)  --> 0, 0, 0

`one`: `Vector3`#

A Vector3 with a value of 1 on every axis.

This API member is a constant, and must be accessed through the Vector3 global as opposed to an individual Vector3 object.

Luau

print(Vector3.one)  --> 1, 1, 1

`xAxis`: `Vector3`#

A Vector3 with a value of 1 on the X axis.

This API member is a constant, and must be accessed through the Vector3 global as opposed to an individual Vector3 object.

Luau

print(Vector3.xAxis)  --> 1, 0, 0

`yAxis`: `Vector3`#

A Vector3 with a value of 1 on the Y axis.

This API member is a constant, and must be accessed through the Vector3 global as opposed to an individual Vector3 object.

Luau

print(Vector3.yAxis)  --> 0, 1, 0

`zAxis`: `Vector3`#

A Vector3 with a value of 1 on the Z axis.

This API member is a constant, and must be accessed through the Vector3 global as opposed to an individual Vector3 object.

Luau

print(Vector3.zAxis)  --> 0, 0, 1

Properties 10#

zero`Vector3`	A `Vector3` with a magnitude of `0`.
one`Vector3`	A `Vector3` with a value of `1` on every axis.
xAxis`Vector3`	A `Vector3` with a value of `1` on the X axis.
yAxis`Vector3`	A `Vector3` with a value of `1` on the Y axis.
zAxis`Vector3`	A `Vector3` with a value of `1` on the Z axis.
X`number`	The X coordinate of the `Vector3`.
Y`number`	The Y coordinate of the `Vector3`.
Z`number`	The Z coordinate of the `Vector3`.
Magnitude`number`	The length of the `Vector3`.
Unit`Vector3`	A normalized copy of the `Vector3` - one that has the same direction as the original but a magnitude of `1`.

`zero`: `Vector3`#

A Vector3 with a magnitude of 0.

This API member is a constant, and must be accessed through the Vector3 global as opposed to an individual Vector3 object.

Luau

print(Vector3.zero) --> 0, 0, 0

`one`: `Vector3`#

A Vector3 with a value of 1 on every axis.

This API member is a constant, and must be accessed through the Vector3 global as opposed to an individual Vector3 object.

Luau

print(Vector3.one)  --> 1, 1, 1

`xAxis`: `Vector3`#

A Vector3 with a value of 1 on the X axis.

This API member is a constant, and must be accessed through the Vector3 global as opposed to an individual Vector3 object.

Luau

print(Vector3.xAxis)  --> 1, 0, 0

`yAxis`: `Vector3`#

A Vector3 with a value of 1 on the Y axis.

This API member is a constant, and must be accessed through the Vector3 global as opposed to an individual Vector3 object.

Luau

print(Vector3.yAxis)  --> 0, 1, 0

`zAxis`: `Vector3`#

A Vector3 with a value of 1 on the Z axis.

This API member is a constant, and must be accessed through the Vector3 global as opposed to an individual Vector3 object.

Luau

print(Vector3.zAxis)  --> 0, 0, 1

`X`: `number`#

The X coordinate of the Vector3. In world space, this axis corresponds to the left-right (east-west) direction.

`Y`: `number`#

The Y coordinate of the Vector3. In world space, this axis corresponds to the up-down (vertical) direction.

`Z`: `number`#

The Z coordinate of the Vector3. In world space, this axis corresponds to the north-south (forward-back) direction.

`Magnitude`: `number`#

The length (magnitude) of the Vector3, computed as math.sqrt(X^2 + Y^2 + Z^2). This is useful for comparing distances or determining how far a point is from the origin.

Luau

local v = Vector3.new(3, 4, 0)
print(v.Magnitude) --> 5

`Unit`: `Vector3`#

A normalized copy of the Vector3 — one that has the same direction as the original but a magnitude of 1. This is useful when you need only the direction of a vector without its length, for example to get a movement direction regardless of speed.

If the vector has a magnitude of 0 (i.e. all components are zero), the resulting Unit vector will have NaN components. Check Magnitude before using Unit when the vector may be zero-length.

Luau

local v = Vector3.new(3, 4, 0)
print(v.Unit)      --> 0.6, 0.8, 0
print(v.Unit.Magnitude) --> 1

Methods 11#

Abs	Returns a new vector from the absolute values of the original's components.
Ceil	Returns a new vector from the ceiling of the original's components.
Floor	Returns a new vector from the floor of the original's components.
Sign	Returns a new vector from the sign (-1, 0, or 1) of the original's components.
Cross	Returns the cross product of the two vectors.
Angle	Returns the angle in radians between the two vectors. If you provide an axis, it determines the sign of the angle.
Dot	Returns a scalar dot product of the two vectors.
FuzzyEq	Returns `true` if the difference between the squared magnitude of the two vectors is within `epsilon`. `epsilon` is scaled relative to the magnitude, rather than an absolute epsilon.
Lerp	Returns a `Vector3` linearly interpolated between this `Vector3` and the given goal by the given alpha.
Max	Returns a `Vector3` with each component as the highest among the respective components of both provided `Vector3` objects.
Min	Returns a `Vector3` with each component as the lowest among the respective components of both provided `Vector3` objects.

`Abs()`: Vector3#

Returns a new vector from the absolute values of the original's components. For example, a vector of (-2, 4, -6) returns a vector of (2, 4, 6).

Returns

Vector3

`Ceil()`: Vector3#

Returns a new vector from the ceiling of the original's components. For example, a vector of (-2.6, 5.1, 8.8) returns a vector of (-2, 6, 9).

Returns

Vector3

`Floor()`: Vector3#

Returns a new vector from the floor of the original's components. For example, a vector of (-2.6, 5.1, 8.8) returns a vector of (-3, 5, 8).

Returns

Vector3

`Sign()`: Vector3#

Returns a new vector from the sign (-1, 0, or 1) of the original's components. For example, a vector of (-2.6, 5.1, 0) returns a vector of (-1, 1, 0).

Returns

Vector3

`Cross(other: Vector3)`: Vector3#

Returns the cross product of this vector and other. The resulting vector is perpendicular to both input vectors and has a magnitude equal to the area of the parallelogram they span. The direction follows the right-hand rule: if you curl the fingers of your right hand from self toward other, your thumb points in the direction of the result.

The cross product is commonly used to find normals to surfaces, determine the axis of rotation between two directions, and test whether two vectors are parallel (cross product of parallel vectors is the zero vector).

Luau

local a = Vector3.new(1, 0, 0)
local b = Vector3.new(0, 1, 0)
print(a:Cross(b)) --> 0, 0, 1
print(b:Cross(a)) --> 0, 0, -1

Name	Type	Default	Description
`other`	`Vector3`		The other `Vector3` to compute the cross product with.

Returns

Vector3

`Angle(other: Vector3, axis: Vector3 = nil)`: number#

Returns the angle in radians between this vector and other. The input vectors do not need to be unit vectors. Without an axis argument, the returned angle is always in the range [0, math.pi] (unsigned).

If you provide an axis Vector3, the returned angle is signed: positive when the rotation from self to other follows the right-hand rule around axis, and negative otherwise. The signed result is in the range [-math.pi, math.pi]. The axis is used only to determine the sign; the plane of rotation is still defined by self and other.

Luau

local a = Vector3.new(1, 0, 0)
local b = Vector3.new(0, 1, 0)
print(a:Angle(b))                         --> 1.5707963... (pi/2)
print(a:Angle(b, Vector3.new(0, 0, 1)))   --> 1.5707963... (positive, CCW about +Z)
print(b:Angle(a, Vector3.new(0, 0, 1)))   --> -1.5707963... (negative, CW about +Z)

Name	Type	Default	Description
`other`	`Vector3`		The `Vector3` to measure the angle to.
`axis`	`Vector3`	`nil`	An optional `Vector3` used to determine the sign of the angle via the right-hand rule.

Returns

number

`Dot(other: Vector3)`: number#

Returns the scalar dot product of this vector and other, computed as self.X * other.X + self.Y * other.Y + self.Z * other.Z.

The dot product is useful for determining the relationship between two directions: it equals the product of their magnitudes multiplied by the cosine of the angle between them. For unit vectors, a result of 1 means they point in the same direction, 0 means they are perpendicular, and -1 means they point in opposite directions.

Luau

local a = Vector3.new(1, 0, 0)
local b = Vector3.new(0, 1, 0)
print(a:Dot(b)) --> 0

local c = Vector3.new(1, 2, 3)
local d = Vector3.new(4, 5, 6)
print(c:Dot(d)) --> 32

Name	Type	Default	Description
`other`	`Vector3`		The `Vector3` to compute the dot product with.

Returns

number

`FuzzyEq(other: Vector3, epsilon: number = 0.00001 aka 1e-5)`: bool#

Returns true if the two vectors are approximately equal within the tolerance defined by epsilon. The comparison is performed per-component using a hybrid epsilon that scales relative to the magnitude of each component, making it suitable for both small and large values. The default epsilon of 0.00001 (1e-5) works well for most cases.

Luau

local a = Vector3.new(1, 2, 3)
local b = Vector3.new(1.000001, 2, 3)
print(a:FuzzyEq(b))        --> true  (within default epsilon)
print(a:FuzzyEq(b, 1e-8))  --> false (tighter tolerance)

Name	Type	Default	Description
`other`	`Vector3`		The `Vector3` to compare against.
`epsilon`	`number`	`0.00001 aka 1e-5`	The tolerance threshold for the comparison, scaled relative to the component magnitudes.

Returns

bool

`Lerp(goal: Vector3, alpha: number)`: Vector3#

Returns a Vector3 linearly interpolated between this Vector3 and the given goal Vector3 by the fraction alpha. Note that alpha is not limited to the range [0, 1].

Name	Type	Default	Description
`goal`	`Vector3`		The target `Vector3` to interpolate toward.
`alpha`	`number`		The interpolation fraction, typically between 0 (returns self) and 1 (returns goal), but not clamped.

Returns

Vector3

`Max(vector: Vector3)`: Vector3#

Returns a Vector3 with each component as the highest among the respective components of both provided Vector3 objects.

Luau

local a = Vector3.new(1, 2, 1)
local b = Vector3.new(2, 1, 2)

print(a:Max(b))  --> Vector3.new(2, 2, 2)

Name	Type	Default	Description
`vector`	`Vector3`		The `Vector3` to compare component-wise against.

Returns

Vector3

`Min(vector: Vector3)`: Vector3#

Returns a Vector3 with each component as the lowest among the respective components of both provided Vector3 objects.

Luau

local a = Vector3.new(1, 2, 1)
local b = Vector3.new(2, 1, 2)

print(a:Min(b))  --> Vector3.new(1, 1, 1)

Name	Type	Default	Description
`vector`	`Vector3`		The `Vector3` to compare component-wise against.

Returns

Vector3

Math operations 8#

Operation	Description
`Vector3 + Vector3` → `Vector3`	Produces a `Vector3` by adding each component of the first vector to the corresponding component of the second.
`Vector3 - Vector3` → `Vector3`	Produces a `Vector3` by subtracting each component of the second vector from the corresponding component of the first.
`Vector3 * Vector3` → `Vector3`	Produces a `Vector3` by multiplying each component of the first vector by the corresponding component of the second.
`Vector3 / Vector3` → `Vector3`	Produces a `Vector3` by dividing each component of the first vector by the corresponding component of the second.
`Vector3 // Vector3` → `Vector3`	Produces a `Vector3` by floor dividing each component of the first vector by the corresponding component of the second.
`Vector3 * number` → `Vector3`	Produces a `Vector3` by multiplying each component of the provided vector by the number.
`Vector3 / number` → `Vector3`	Produces a `Vector3` by dividing each component of the provided vector by the number.
`Vector3 // number` → `Vector3`	Produces a `Vector3` by floor dividing each component of the provided vector by the number.

Constructors 3#

function Object() { [native code] }new(x: number = 0, y: number = 0, z: number = 0)#

function Object() { [native code] }FromNormalId(normal: NormalId)#

function Object() { [native code] }FromAxis(axis: Axis)#

Constants 5#

zero: Vector3#

one: Vector3#

xAxis: Vector3#

yAxis: Vector3#

zAxis: Vector3#

Properties 10#

zero: Vector3#

one: Vector3#

xAxis: Vector3#

yAxis: Vector3#

zAxis: Vector3#

X: number#

Y: number#

Z: number#

Magnitude: number#

Unit: Vector3#

Methods 11#

Abs(): Vector3#

Returns

Ceil(): Vector3#

Returns

Floor(): Vector3#

Returns

Sign(): Vector3#

Returns

Cross(other: Vector3): Vector3#

Returns

Angle(other: Vector3, axis: Vector3 = nil): number#

Returns

Dot(other: Vector3): number#

Returns

FuzzyEq(other: Vector3, epsilon: number = 0.00001 aka 1e-5): bool#

Returns

Lerp(goal: Vector3, alpha: number): Vector3#

Returns

Max(vector: Vector3): Vector3#

Returns

Min(vector: Vector3): Vector3#

Returns

Math operations 8#

`new(x: number = 0, y: number = 0, z: number = 0)`#

`FromNormalId(normal: NormalId)`#

`FromAxis(axis: Axis)`#

`zero`: `Vector3`#

`one`: `Vector3`#

`xAxis`: `Vector3`#

`yAxis`: `Vector3`#

`zAxis`: `Vector3`#

`zero`: `Vector3`#

`one`: `Vector3`#

`xAxis`: `Vector3`#

`yAxis`: `Vector3`#

`zAxis`: `Vector3`#

`X`: `number`#

`Y`: `number`#

`Z`: `number`#

`Magnitude`: `number`#

`Unit`: `Vector3`#

`Abs()`: Vector3#

`Ceil()`: Vector3#

`Floor()`: Vector3#

`Sign()`: Vector3#

`Cross(other: Vector3)`: Vector3#

`Angle(other: Vector3, axis: Vector3 = nil)`: number#

`Dot(other: Vector3)`: number#

`FuzzyEq(other: Vector3, epsilon: number = 0.00001 aka 1e-5)`: bool#

`Lerp(goal: Vector3, alpha: number)`: Vector3#

`Max(vector: Vector3)`: Vector3#

`Min(vector: Vector3)`: Vector3#