14 min read

Source: Roblox Creator Hub · CC BY 4.0 · View source · Code samples: MIT Imported 2026-10-03. Formatting adapted for this site.

Vector3

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:

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

Vector3.new

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

Parameters

Vector3.FromNormalId

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).

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

Parameters

Vector3.FromAxis

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).

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

Parameters

Properties

Vector3.zero

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.

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

Vector3.one

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.

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

Vector3.xAxis

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.

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

Vector3.yAxis

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.

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

Vector3.zAxis

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.

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

Vector3.X

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

Vector3.Y

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

Vector3.Z

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

Vector3.Magnitude

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.

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

Vector3.Unit

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.

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

Methods

Vector3:Abs

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

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

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

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

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).

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

Parameters

Returns

Vector3:Angle

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.

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)

Parameters

Returns

Vector3:Dot

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.

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

Parameters

Returns

Vector3:FuzzyEq

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.

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)

Parameters

Returns

Vector3:Lerp

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].

Parameters

Returns

Vector3:Max

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

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

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

Parameters

Returns

Vector3:Min

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

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

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

Parameters

Returns

Constants

Vector3.zero

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.

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

Vector3.one

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.

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

Vector3.xAxis

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.

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

Vector3.yAxis

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.

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

Vector3.zAxis

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.

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

Operators

Vector3 + Vector3 (addition)

Produces a Vector3 by adding each component of the first vector to the corresponding component of the second.

Vector3 - Vector3 (subtraction)

Produces a Vector3 by subtracting each component of the second vector from the corresponding component of the first.

Vector3 * Vector3 (multiplication)

Produces a Vector3 by multiplying each component of the first vector by the corresponding component of the second.

Vector3 / Vector3 (division)

Produces a Vector3 by dividing each component of the first vector by the corresponding component of the second.

Vector3 // Vector3 (floor division)

Produces a Vector3 by floor dividing each component of the first vector by the corresponding component of the second.

Vector3 * number (multiplication)

Produces a Vector3 by multiplying each component of the provided vector by the number.

Vector3 / number (division)

Produces a Vector3 by dividing each component of the provided vector by the number.

Vector3 // number (floor division)

Produces a Vector3 by floor dividing each component of the provided vector by the number.