Vector3

For general information on vectors, see Vector and Vectors and Matrices.

A Vector3 is a vector that contains 3 numbers.

Methods

Method	Brief description
length	Computes the length of the vector.
lengthSquared	Computes the squared length of the vector.
dot	Computes the dot product between vectors.
add in-place	Adds vectors.
subtract in-place	Subtracts vectors.
offset in-place	Adds a number to each component of the vector.
multiply in-place	Performs component multiplication.
transform in-place	Transforms a vector with a matrix.
divide in-place	Performs component division.
reduce in-place	Runs the modulo operation on each component of the vector.
scale in-place	Multiplies each component of the vector by a number.
normalize in-place	Normalizes the vector, making its length 1.
clampLength in-place	Applies bounds to the length of the vector, scaling as needed.
clamped	Returns a new copy of this vector with clampLength applied.
normalized	Returns a new, normalized copy of the vector.
toRad	Returns a copy of this vector, converted to radians.
toDeg	Returns a copy of this vector, converted to degrees.
floor in-place	Floors the components of the vector.
ceil in-place	Ceilings the components of the vector.
copy	Returns a copy of this vector.
set in-place	Assigns the values from another vector to this one.
reset in-place	Sets the components of this vector to 0.
applyFunc in-place	Apply a function to the components of this vector.
augmented	Convert this vector into a Vector4 by appending a number.
cross in-place	Calculate the cross product of two vectors.
crossed	Calculate the cross product of two vectors.

Fields

Field	Brief description
_	Always 0.
x, r, [1]	First component.
y, g, [2]	Second component.
z, b, [3]	Third component.

Operators

Operator	Brief description
(vector + vector)	Add two vectors.
(vector + number) comm.	Add the number to each component of the vector.
(-vector)	Negate the vector.
(vector - vector)	Subtract two vectors.
(vector - number)	Subtract the number from each component of the vector.
(number - vector)	Negate the vector, then add the number to each component.
(vector * vector)	Multiply (component-wise) two vectors.
(vector * number) comm.	Scale the vector.
(vector * matrix)	Transform the vector using the matrix.
(vector / vector)	Divide (component-wise) two vectors.
(vector / number)	Scale the vector by (1/number).
(#vector)	Number of components in the vector.
(vector < vector)	Component-wise less than.
(vector <= vector)	Component-wise less than or equal.
tostring(vector)	Result of tostring(vector).

Methods

Math operations

Mathematical operations that apply to all vectors, such as computing their length

length

---

Mathematical definition

Computes the Euclidean norm of the vector.

Computes the length of a vector.

Arguments	Return Type
length()	number

lengthSquared

---

Computes the length of a vector, squared. Due to the nature of the length calculation, this is a little bit faster than length.

Arguments	Return Type
lengthSquared()	number

dot

---

Computes the dot product between two vectors. The argument must be the same type as the target vector.

Arguments	Return Type
dot(Vector3 other)	number

add

---

Mathematical definition

Performs vector addition with another vector, storing the result in this vector.

Adds the values from this vector and another vector of the same size, and writes them to this vector. To create a new instance from the sum, see + (operator).

Arguments	Return Type
add(Vector3 other)	self Vector3

subtract

---

Mathematical definition

Performs vector subtraction with another vector (in the order this - other), storing the result in this vector.

Subtracts the passed vector of the same size from this vector, and writes the result to this vector. To create a new instance from the difference, see - (operator).

Arguments	Return Type
subtract(Vector3 other)	self Vector3

offset

---

Adds factor to all components of this vector. To create a new instance from the result, see + (operator) or - (operator).

Arguments	Return Type
offset(number factor)	self Vector3

multiply

---

Multiplies vectors of the same size by multiplying their components. The result is written to this vector.

Arguments	Return Type
multiply(Vector3 other)	self Vector3

transform

---

Mathematical definition

Multiplies the provided matrix with this vector, in the order M * V, and writes the resulting vector to this vector.

Applies a matrix transformation to this vector. Equivalent to multiplying the matrix by the vector. The matrix must be the same size as the vector; the following are valid:

Arguments	Return Type
transform(Matrix3 mat)	self Vector3

divide

---

Divides vectors of the same size by dividing their components. The result is written to this vector.

Arguments	Return Type
divide(Vector3 other)	self Vector3

reduce

---

For each component in this vector, perform the positive modulo operation on it and the equivalent component in the other vector.

Arguments	Return Type
reduce(Vector3 other)	self Vector3

scale

---

Multiplies each component in this vector by factor.

Arguments	Return Type
scale(number factor)	self Vector3

normalize

---

Normalizes this vector in-place. After this operation, the length of the vector will be 1, unless the length is currently 0. If this vector's length is 0, then no normalization will occur.

Arguments	Return Type
normalize()	self Vector3

clampLength

---

Scales this vector such that its length is within the bounds specified by minLength and maxLength. If this vector's length is 0, no scaling will be performed, even if minLength is greater than 0. If this vector's length is already within the specified bounds, no scaling will be performed.

Both minLength and maxLength can be omitted or set to nil, resulting in no lower or upper bound on the length of the vector.

clamped

---

Copies this vector, then clamps its length. See clampLength for details.

normalized

---

Copies this vector, then normalizes it. See normalize for details.

Arguments	Return Type
normalized()	new Vector3

toRad

---

Returns a copy of this vector, scaled by a factor of (pi / 180). If this vector represents a rotation in degrees, the result will be a rotation in radians.

See also toDeg.

Arguments	Return Type
toRad()	new Vector3

toDeg

---

Returns a copy of this vector, scaled by a factor of (180 / pi). If this vector represents a rotation in radians, the result will be a rotation in degrees.

See also toRad.

Arguments	Return Type
toDeg()	new Vector3

floor

---

Returns a copy of this vector with every component floored.

Arguments	Return Type
floor()	new Vector3

ceil

---

Returns a copy of this vector with every component ceiling-ed.

Arguments	Return Type
ceil()	new Vector3

Utility methods

copy

---

Creates a copy of this vector. Creating a copy will make a new Vector with the same size and values, but which is disconnected from the original. This means that methods like set or add which modify the vector they are called with will not modify copies.

Arguments	Return Type
copy()	new Vector3

set

---

Assigns the values from another vector of the same size to this vector in place. To create a new instance, see copy.

Arguments	Return Type
set(Vector3 other)	self Vector3

reset

---

Sets all the components of this vector to 0.

Arguments	Return Type
reset()	self Vector3

applyFunc

---

Calls the provided function f on every component, and sets this vector's components to the return values of the function.

The function receives the following values as arguments: first, the value as a number, then the index (integer, 1 is x, 2 is y, etc.) The function is expected to return a number.

Arguments	Return Type
applyFunc(function f)	self Vector3

local A = vec(1, 2, 3)
-- cube the values
A:applyFunc(function(value, index) return value*value*value end)
print(A) -- {1, 8, 27}

Vector3 methods

augmented

---

Converts this Vector3 into a Vector4 using the provided number as the fourth component.

Arguments	Return Type
augmented(number d)	Vector4

cross

---

Calculates the Cross product between two Vector3s and stores the result in this vector.

Arguments	Return Type
cross(Vector3 other)	self Vector3

crossed

---

Calculates the Cross product between two Vector3s and creates a new Vector3 to store the result.

Arguments	Return Type
crossed(Vector3 other)	new Vector3

Fields

Swizzling

Swizzling is available for all vector types. For details, see Swizzling.

_

Read-only number. Always 0. Attempting to write to this field will have no effect.

Vector4 fields

x, r, 1

---

Read/write number. The first component of the vector.

y, g, 2

---

Read/write number. The second component of the vector.

z, b, 3

---

Read/write number. The third component of the vector.

Operators

Lua operators, such as +, -, and *, apply to vectors and have different results.

+ (operator)

With two vectors

---

Adds the values from this vector and another vector of the same size. The result is a new vector of the same size which holds the sum.

Left	Right	Result
Vector3	Vector3	new Vector3

local a = vec(1, 2, 3)
local b = vec(4, 4, 6)
print(a + b, a, b) -- {5, 6, 9}  {1, 2, 3}  {4, 4, 6}

With a vector and number

Operator is commutative and has the same result regardless of order.

The result is a new vector of the same size which holds the result of adding the number to all components of this vector.

Left	Right	Result
Vector3	number	new Vector3
number	Vector3	new Vector3

- (operator)

As a unary operator

---

Returns a new vector of the same size, but all the components negated. Effectively the same as * -1.

Operand	Result
Vector3	new Vector3

With two vectors

---

Mathematical definition

Performs vector subtraction with another vector, and creates a new vector from the result.

Subtracts the right vector from the left vector. The result is a new vector of the same size which holds the difference.

Left	Right	Result
Vector3	Vector3	new Vector3

local a = vec(1, 2, 3)
local b = vec(4, 4, 6)
print(b - a, a, b) -- {3, 2, 3}  {1, 2, 3}  {4, 4, 6}

With a vector and a number

Only applies when the number is on the right side of the operator.

Returns a new vector of the same size containing the result of subtracting the number from all components of the vector.

Left	Right	Result
Vector3	number	new Vector3

With a number and a vector

Only applies when the number is on the left side of the operator.

Returns a new vector of the same size containing the result of negating all of the components of the vector, then adding the number. In effect, number - vector == (-vector) + number.

Left	Right	Result
number	Vector3	new Vector3

* (operator)

With two vectors

---

Returns a new vector of the same size containing the result of multiplying the vectors together (component multiplication.)

Left	Right	Result
Vector3	Vector3	new Vector3

With a vector and a number

Operator is commutative and has the same result regardless of order.

Returns a new vector of the same size containing the result of scaling the vector by the number (scalar multiplication.)

Left	Right	Result
Vector3	number	new Vector3
number	Vector3	new Vector3

With a vector and a matrix

This definition only applies if the vector is on the left side. If the vector is on the right side, see the associated operator on the matrix.

Returns a new vector of the same size containing the result of transforming the vector with the matrix.

Left	Right	Result
Vector3	Matrix3	new Vector3

/ (operator)

With two vectors

---

Returns a new vector of the same size containing the result of dividing the left vector by the right vector (component division.)

Left	Right	Result
Vector3	Vector3	new Vector3

With a vector and a number

Only applies when the number is on the right side of the operator. There is no definition with the number on the left side of the operator.

Returns a new vector of the same size containing the result of scaling the vector by the reciprocal of the number.

Left	Right	Result
Vector3	number	new Vector3

# (operator)

---

Returns the number of components in this vector(3)

Operand	Result
Vector3	3

< (operator)

---

Returns true if all of the components of the left vector are strictly less than the corresponding components of the right vector.

Left	Right	Result
Vector3	Vector3	boolean

local A = vec(1, 2, 3)
local B = vec(4, 5, 6)
local C = vec(4, 1, 6)
print(A < B) -- true
print(B < C) -- false

<= (operator)

---

Returns true if all of the components of the left vector are strictly less than or equal to the corresponding components of the right vector.

Left	Right	Result
Vector3	Vector3	boolean

local A = vec(1, 2, 3)
local B = vec(4, 5, 6)
local C = vec(1, 2, 3)
print(A <= B) -- true
print(B <= C) -- true

tostring return value

---

Converts the vector to a string representing its components.

Operand	Result
Vector3	string