Vector3

Supported Datatype

Represents a 3D value with a direction and magnitude.

Description

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

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

Vector3.new(x: number = 0, y: number = 0, z: number = 0)

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

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

FromNormalId Supported Returns a new Vector3 in the given direction.

Vector3.FromNormalId(normal: NormalId)

Returns a new Vector3 in the given direction.

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

FromAxis Supported Returns a new Vector3 for the given axis.

Vector3.FromAxis(axis: Axis)

Returns a new Vector3 for the given 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).

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

Constants

zero Not yet A Vector3 with a magnitude of 0.

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

one Not yet A Vector3 with a value of 1 on every axis.

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

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

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

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

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

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

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

Properties

zero Not yet A Vector3 with a magnitude of 0.

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

one Not yet A Vector3 with a value of 1 on every axis.

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

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

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

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

Vector3.yAxis()

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

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

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

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

X Supported The X coordinate of the Vector3.

Vector3.X()

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

Y Supported The Y coordinate of the Vector3.

Vector3.Y()

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

Z Supported The Z coordinate of the Vector3.

Vector3.Z()

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

Magnitude Supported The length of the Vector3.

Vector3.Magnitude()

The length of the Vector3.

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

Unit Supported A normalized copy of the Vector3 - one that has the same direction as the original but a magnitude of 1.

Vector3.Unit()

A normalized copy of the Vector3 - one that has the same direction as the original but a magnitude of 1.

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

Abs Not yet Returns a new vector from the absolute values of the original's components.

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

Ceil Not yet Returns a new vector from the ceiling of the original's components.

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

Floor Not yet Returns a new vector from the floor of the original's components.

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

Sign Not yet Returns a new vector from the sign (-1, 0, or 1) of the original's components.

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

Cross Supported Returns the cross product of the two vectors.

Vector3:Cross(other: Vector3)

Returns the cross product of the two vectors.

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

Angle Not yet Returns the angle in radians between the two vectors. If you provide an axis, it determines the sign of the angle.

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

Returns the angle in radians between the two vectors. If you provide an axis, it determines the sign of the 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)

Dot Supported Returns a scalar dot product of the two vectors.

Vector3:Dot(other: Vector3)

Returns a scalar dot product of the two vectors.

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

FuzzyEq Not yet Returns true if the difference between the squared magnitude of the two vectors is within epsilon. epsilon is scaled re…

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

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.

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)

Lerp Supported Returns a Vector3 linearly interpolated between this Vector3 and the given goal by the given alpha.

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

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

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

Vector3:Max(vector: Vector3)

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)

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

Vector3:Min(vector: Vector3)

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)

Math operations

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

+: Vector3

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

operator

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

-: Vector3

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

operator

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

*: Vector3

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

operator

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

/: Vector3

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

operator

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

//: Vector3

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

operator

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

*: Vector3

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

operator

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

/: Vector3

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

operator

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

//: Vector3

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

operator

Nova binding inventory

Library	Members
FromAxis, FromNormalId, new	Cross, Dot, Lerp, Magnitude, Unit, X, Y, Z, isClose, lerp, magnitude, unit, x, y, z

Roblox reference: Vector3