Vector3

Overview

Vector3 is a data type used to express vector in a three-dimensional space using X, Y, and Z axes. It is used to handle a variety of 3D data such as position, direction, speed, and strength. It is also one of the key elements used by many systems to calculate coordinates and vector within a space or simulating 3D physics.

Constructors

new

Creates and returns a new vector using the passed X, Y, and Z values.

Parameters

Parameter	Description
number x	The value of X coordinate.
number y	The value of Y coordinate.
number z	The value of Z coordinate.

Return

Return	Description
Vector3	The created Vector3.

Code Samples

local Vector = Vector3.new(1, 2, 3)
print(Vector)

Properties

X

number

The value of X coordinate.

Code Samples

local Vector = Vector3.new(10, 5, 8)
print(Vector.X)

Y

number

The value of Y coordinate.

Code Samples

local Vector = Vector3.new(10, 5, 8)
print(Vector.Y)

Z

number

The value of Z coordinate.

Code Samples

local Vector = Vector3.new(10, 5, 8)
print(Vector.Z)

zero

Vector3

A vector of which axis values are zeroes (0, 0, 0).

Code Samples

local ZeroVector = Vector3.zero
print(ZeroVector)

one

Vector3

A vector of which axis values are ones (1, 1, 1).

Code Samples

local OneVector = Vector3.one
print(OneVector)

xAxis

Vector3

A Vector3 set to have the value of 1 for X axis and 0 for other axes (1, 0, 0).

Code Samples

local XAxis = Vector3.xAxis
print(XAxis)

yAxis

Vector3

A Vector3 set to have the value of 1 for Y axis and 0 for other axes (0, 1, 0).

Code Samples

local YAxis = Vector3.yAxis
print(YAxis)

zAxis

Vector3

A Vector3 set to have the value of 1 for Z axis and 0 for other axes (0, 0, 1).

Code Samples

local ZAxis = Vector3.zAxis
print(ZAxis)

Unit

Vector3

A Vector3 of which size is removed and length is 1 while maintaining the original direction.

Code Samples

local Vector = Vector3.new(100, 50, 200)
print(Vector.Unit)

Magnitude

number

The value representing the size of a Vector3.

Code Samples

local Vector = Vector3.new(100, 50, 200)
print(Vector.Magnitude)

Methods

Abs

Makes each coordinate of a vector positive, even if some of them were negative, and returns a new vector.

Parameters

Return

Vector3	The created Vector3.

Code Samples

local v = Vector3.new(-2, 4, -6)
print("Abs:", v:Abs()) --> Output: 2, 4, 6

Angle

Calculates the angle between two vectors in radian and returns it. If there is a reference axis, the direction of the angle is also considered in the return value.

Parameters

Vector3 otherVector	The Vector3 to calculate its angle.
Vector3 axis	The Vector3 to be used as a reference axis to determine the direction of an angle. If no axis is provided, only the absolute angle between two vectors is calculated.

Return

number	Returns the angle between two vectors in radian.

Code Samples

local a = Vector3.new(1, 0, 0)
local b = Vector3.new(0, 1, 0)
print("Angle:", a:Angle(b) -- Output: 1.570796

Ceil

Rounds up each coordinate of the vectors and returns a new vector.

Parameters

Return

Vector3	The created Vector3.

Code Samples

local v = Vector3.new(-2.6, 5.1, 8.8)
print("Ceil:", v:Ceil()) --> Output: -2, 6, 9

ClampMagnitude

Returns a new vector of which length is restricted not to exceed maxLength.

Parameters

number maxLength	The maximum value used to restrict vector length.

Return

Vector3	The created Vector3.

Code Samples

local v = Vector3.new(10, 0, 0)
print("ClampMagnitude", v:ClampMagnitude(3)) --> Output: 3, 0, 0

Cross

Returns the cross product between two vectors as a new vector.

Parameters

Vector3 Parameter for cross product.	The Vector3 to calculate its cross product.

Return

Vector3	The created Vector3.

Code Samples

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

Distance

Returns the distance between two vectors.

Parameters

Vector3 otherVector	The Vector3 to calculate distance.

Return

number	Returns the linear distance between two vectors in a numeric value.

Code Samples

local a = Vector3.new(0, 0, 0)
local b = Vector3.new(3, 4, 0)
print("Distance:", a:Distance(b)) --> Output: 5

Dot

Returns the dot value between two vectors as a scalar.

Parameters

Vector3 vector	The Vector3 to calculate its dot product.

Return

number	Returns the dot product between two vectors as a scalar.

Code Samples

local a = Vector3.new(1, 2, 3)
local b = Vector3.new(4, 5, 6)
print("Dot:", a:Dot(b)) --> Output: 32

Floor

Rounds down each coordinate of the exiting vectors and returns a new vector.

Parameters

Return

Vector3	The created Vector3.

Code Samples

local v = Vector3.new(-2.6, 5.1, 8.8)
print("Floor:", v:Floor()) --> Output: -3, 5, 8

FuzzyEq

Compares the squared size of both vectors and returns true if both values are within the epsilon range calculated according to vector size. In this case, both vectors are treated as the same vector.

Parameters

Vector3 otherVector	The Vector3 to compare.
number epsilon	A value indicates tolerance. This value is applied in proportion to vector size. It is used to determine whether the difference of two squared vectors is within this range.

Return

bool	Returns true if the difference of two squared vectors is within the epsilon tolerance according to vector size. Returns false otherwise.

Code Samples

local a = Vector3.new(1.0001, 2.0001, 3.0001)
local b = Vector3.new(1.0002, 2.0002, 3.0002)
print("FuzzyEq:", a:FuzzyEq(b)) --> Output: false

Lerp

Calculates the linear interpolation between the current vector and the target vector according to alpha ratio and returns it as a new vector.

Parameters

Vector3 goal	The target Vector3 to be interpolated.
number alpha	A value indicating interpolation ratio.

Return

Vector3	The created Vector3.

Code Samples

local a = Vector3.new(0, 0, 0)
local b = Vector3.new(10, 10, 10)
print("Lerp:", a:Lerp(b, 0.3)) --> Output: 3, 3, 3

Max

Compares the X, Y, and Z value of two vectors, selects the higher value for each axis, and returns a new vector with the selected values.

Parameters

Vector3 otherVector	The other Vector3 to compare.

Return

Vector3	The created Vector3.

Code Samples

local a = Vector3.new(1, 5, 3)
local b = Vector3.new(4, 2, 6)
print("Max:", a:Max(b)) --> Output: 4, 5, 6

Min

Compares the X, Y, and Z value of two vectors, selects the lower value for each axis, and returns a new vector with the selected values.

Parameters

Vector3 otherVector	The other Vector3 to compare.

Return

Vector3	The created Vector3.

Code Samples

local a = Vector3.new(1, 5, 3)
local b = Vector3.new(4, 2, 6)
print("Min:", a:Min(b)) --> Output: 1, 2, 3

MoveTowards

Returns a new vector, which is moved from the current vector toward the target vector in the distance of maxDelta.

Parameters

Vector3 target	The Vector3 to be the movement target.
number maxDelta	The maximum distance movable in a single calculation.

Return

Vector3	The created Vector3.

Code Samples

local a = Vector3.new(0, 0, 0)
local b = Vector3.new(10, 0, 0)
print("MoveTowards:", a:MoveTowards(b, 3)) --> Output: 3, 0, 0

Reflect

Returns a new vector, which is reflected by a given normal vector.

Parameters

Vector3 inNormal	The normal vector (Vector3) to be the reference point of reflection.

Return

Vector3	The created Vector3.

Code Samples

local v = Vector3.new(1, -1, 0)
local n = Vector3.new(0, 1, 0)
print("Reflect", v:Reflect(n)) --> Output: 1, 1, 0

Rotate

Returns a new vector, which is rotated by radians along the provided axis.

Parameters

Vector3 axis	The Vector3 to be the rotation axis.
number radians	A value specifying the angle by which a vector is rotated, measured in radian.

Return

Vector3	The created Vector3.

Code Samples

local v = Vector3.new(1, 0, 0)
local axis = Vector3.new(0, 1, 0)
print("Rotate:", v:Rotate(axis, math.rad(90))) --> Output: 0, 0, -1

Sign

Converts the each coordinate of an existing vector and returns the result as a new vector. Any negative number is converted to -1; any positive value is converted to 1; and 0 is not converted.

Parameters

Return

Vector3	The created Vector3.

Code Samples

local v = Vector3.new(-2.6, 5.1, 0)
print("Sign:", v:Sign()) --> Output: -1, 1, 0

Slerp

Calculates the spherical linear interpolation between the current vector and the target vector according to alpha ratio and returns it as a new vector.

While Lerp interpolates along a linear path, Slerp interpolates along a curve on a unit sphere, making its rotation axis movement smoother and more constant.

Parameters

Vector3 goal	The target Vector3 to be interpolated.
number alpha	A value indicating interpolation ratio.

Return

Vector3	The created Vector3.

Code Samples

local a = Vector3.new(1, 0, 0)
local b = Vector3.new(0, 1, 0)
print("Slerp:", a:Slerp(b, 0.5)) --> Output: 0.707107, 0.707107, 0 

See also

Coordinate System