Vector3

A vector that holds 3 numbers

warning

This page is a WIP. It contains all the information in Figura's documentation but we're working on adding more helpful descriptions.

Can be created using functions in the "vectors" api

For this entire page assume:

local vec3 = vec(2, 5, 3)

---

Math

add()

Adds the given vector or values to this one, and returns self for chaining

Overload 1

add(vec)

Parameters:

Name	Type	Description	Default
vec	Vector3	-	-

Returns:

Type	Description
Vector3	Returns self for chaining

Overload 2

add(x, y, z)

Parameters:

Name	Type	Description	Default
x	Number	-	-
y	Number	-	-
z	Number	-	-

Returns:

Type	Description
Vector3	Returns self for chaining

Example:

vec3:add(2, 0.5, 4)

---

div()

Divides this vector by the given vector or values, and returns self for chaining

Overload 1

div(vec)

Parameters:

Name	Type	Description	Default
vec	Vector3	-	-

Returns:

Type	Description
Vector3	Returns self for chaining

Overload 2

div(x, y, z)

Parameters:

Name	Type	Description	Default
x	Number	-	-
y	Number	-	-
z	Number	-	-

Returns:

Type	Description
Vector3	Returns self for chaining

Example:

vec3:div(2, 3, 2)

---

mul()

Multiplies the given vector or values into this one, and returns self for chaining

Overload 1

mul(vec)

Parameters:

Name	Type	Description	Default
vec	Vector3	-	-

Returns:

Type	Description
Vector3	Returns self for chaining

Overload 2

mul(x, y, z)

Parameters:

Name	Type	Description	Default
x	Number	-	-
y	Number	-	-
z	Number	-	-

Returns:

Type	Description
Vector3	Returns self for chaining

Example:

vec3:mul(2, 3, 2)

---

sub()

Subtracts the given vector or values from this one, and returns self for chaining

Overload 1

sub(vec)

Parameters:

Name	Type	Description	Default
vec	Vector3	-	-

Returns:

Type	Description
Vector3	Returns self for chaining

Overload 2

sub(x, y, z)

Parameters:

Name	Type	Description	Default
x	Number	-	-
y	Number	-	-
z	Number	-	-

Returns:

Type	Description
Vector3	Returns self for chaining

Example:

vec3:sub(1, 0.5, 1)

---

ceil()

Returns a copy of this vector with its values rounded up

ceil()

Returns:

Type	Description
Vector3	Returns self for chaining

Example:

vec3:ceil()

---

clampLength()

Modifies this vector so that its length is between minLength and maxLength

If the vector has length zero, it is unmodified

Returns self for chaining

clampLength(minLength, maxLength)

Parameters:

Name	Type	Description	Default
minLength	Number	-	-
maxLength	Number	-	-

Returns:

Type	Description
Vector3	Returns self for chaining

Example:

vec3:clampLength(1, 5)

---

clamped()

Returns a modified copy of this vector, with its length clamped from minLength to maxLength

If the vector has length zero, then the copy does too

clamped(minLength, maxLength)

Parameters:

Name	Type	Description	Default
minLength	Number	-	-
maxLength	Number	-	-

Returns:

Type	Description
Vector3	Returns self for chaining

Example:

vec3:clamped(1, 3)

---

cross()

Sets this vector to the cross product of itself and the other vector

Returns self for chaining

cross(other)

Parameters:

Name	Type	Description	Default
other	Vector3	-	-

Returns:

Type	Description
Vector3	Returns self for chaining

Example:

vec3:cross(vec(2, 3, 5))

---

crossed()

Returns a new vector which is the cross product of this and the other one

crossed(other)

Parameters:

Name	Type	Description	Default
other	Vector3	-	-

Returns:

Type	Description
Vector3	Returns self for chaining

Example:

vec3:crossed(vec(2, 5, 4))

---

dot()

Returns the dot product of this vector with the other

dot(vec)

Parameters:

Name	Type	Description	Default
vec	Vector3	-	-

Returns:

Type	Description
Number	-

Example:

vec3:dot(vec(2, 2, 3))

---

floor()

Returns a copy of this vector with its values rounded down

floor()

Returns:

Type	Description
Vector3	Returns self for chaining

Example:

vec3:floor()

---

length()

Returns the length of this vector

length()

Returns:

Type	Description
Number	-

Example:

vec3:length()

---

lengthSquared()

Returns the length of this vector squared

Suitable when you only care about relative lengths, because it avoids a square root

lengthSquared()

Returns:

Type	Description
Number	-

Example:

vec3:lengthSquared()

---

Transformations

scale()

Scales this vector by the given factor, and returns self for chaining

scale(factor)

Parameters:

Name	Type	Description	Default
factor	Number	-	-

Returns:

Type	Description
Vector3	Returns self for chaining

Example:

vec3:scale(2)

---

normalize()

Modifies this vector so that its length is 1 unless its length was originally 0

Returns self for chaining

normalize()

Returns:

Type	Description
Vector3	Returns self for chaining

Example:

vec3:normalize()

---

normalized()

Returns a copy of this vector with length 1 unless its length was originally 0

normalized()

Returns:

Type	Description
Vector3	Returns self for chaining

Example:

vec3:normalized()

---

offset()

Offsets this vector by the given factor, adding the factor to all components, and returns self for chaining

offset(factor)

Parameters:

Name	Type	Description	Default
factor	Number	-	-

Returns:

Type	Description
Vector3	Returns self for chaining

Example:

vec3:offset(2)

---

reduce()

Reduces this vector modulo the given vector or values, and returns self for chaining

Overload 1

reduce(vec)

Parameters:

Name	Type	Description	Default
vec	Vector3	-	-

Returns:

Type	Description
Vector3	Returns self for chaining

Overload 2

reduce(x, y, z)

Parameters:

Name	Type	Description	Default
x	Number	-	-
y	Number	-	-
z	Number	-	-

Returns:

Type	Description
Vector3	Returns self for chaining

Example:

vec3:reduce(1, 0.5, 2)

---

transform()

Transforms this vector by the given matrix, and returns self for chaining

transform(mat)

Parameters:

Name	Type	Description	Default
mat	Matrix2	-	-

Returns:

Type	Description
Vector3	Returns self for chaining

Example:

vec3:transform(matrices.mat3())

---

Utility

set()

Sets this vector to have the given values

Nil values are treated as zero

Returns self for chaining

Overload 1

set(vec)

Parameters:

Name	Type	Description	Default
vec	Vector3	-	-

Returns:

Type	Description
Vector3	Returns self for chaining

Overload 2

set(x, y, z)

Parameters:

Name	Type	Description	Default
x	Number	-	-
y	Number	-	-
z	Number	-	-

Returns:

Type	Description
Vector3	Returns self for chaining

Example:

vec3:set(1, 2, 3)

---

applyFunc()

Calls the given function on each element of this vector, and sets the values of the vector to the returns

The current index and its value is given as arguments of the function

Returns self for chaining

applyFunc(func)

Parameters:

Name	Type	Description	Default
func	Function	-	-

Returns:

Type	Description
Vector3	Returns self for chaining

Example:

-- Example 1:
vec3:applyFunc(math.sqrt)
-- Example 2:
vec3:applyFunc(function(v)
    return v + math.random() - 0.5
end)

---

augmented()

Returns the augmented form of this vector

The augmented form is a Vector of the same length + 1

The new axis will have the given value, or 1 when it is not specified

Overload 1

augmented()

Returns:

Type	Description
Vector4	-

Overload 2

augmented(value)

Parameters:

Name	Type	Description	Default
value	Number	-	-

Returns:

Type	Description
Vector4	-

Example:

vec3:augmented(4)

---

copy()

Creates and returns a copy of this vector

copy()

Returns:

Type	Description
Vector3	Returns self for chaining

Example:

vec3:copy()

---

reset()

Resets this vector back to being all zeroes, and returns itself for chaining

reset()

Returns:

Type	Description
Vector3	Returns self for chaining

Example:

vec3:reset()

---

unpack()

Returns this vector's values as separate numbers

unpack()

Returns:

Type	Description
Number	x value
Number	y value
Number	z value

Example:

local x, y, z = vec3:unpack()

---

Conversion

toDeg()

Returns a copy of this vector, in degrees

toDeg()

Returns:

Type	Description
Vector3	Returns self for chaining

Example:

vec3:toDeg()

---

toRad()

Returns a copy of this vector, in radians

toRad()

Returns:

Type	Description
Vector3	Returns self for chaining

Example:

vec3:toRad()

---

Fields

x

The first coordinate of this vector

Can also be gotten with the indices "r" and [1]

Example:

vec3.x
vec3.r
vec3[1]

---

y

The second coordinate of this vector

Can also be gotten with the indices "g" and [2]

Example:

vec3.y
vec3.g
vec3[2]

---

z

The third coordinate of this vector

Can also be gotten with the indices "b" and [3]

Example:

vec3.z
vec3.b
vec3[3]

---