vectorLuau

vector is a built-in value type for positions, directions and other groups of three numbers. Like numbers, vectors are plain values: creating one never allocates, and two vectors with the same components are equal. Read the components through x, y and z or their uppercase forms. Vectors are immutable: assigning to a component raises an error.

+, -, *, / and // work on each component, and *, / and // also take a number on either side. The vector library creates vectors and provides length, normalization, dot and cross products, angles, rounding and interpolation.

Input
const position = vector.create(1, 2, 3)
const moved = position * 2 + vector.one

print(moved.x)
print(`{moved}`)
print(moved == vector.create(3, 5, 7))
Output
3
3, 5, 7
true
Summary

Creating

vector.zeroLuau
Holds a vector with every component set to 0
vector.oneLuau
Holds a vector with every component set to 1
vector.createLuau
Creates a vector from its components

Length and direction

vector.magnitudeLuau
Returns the length of a vector
vector.normalizeLuau
Returns the unit vector pointing the same way as a vector

Products and angles

vector.crossLuau
Returns the cross product of two vectors
vector.dotLuau
Returns the dot product of two vectors
vector.angleLuau
Returns the angle between two vectors in radians

Component by component

vector.floorLuau
Applies math.floor to every component
vector.ceilLuau
Applies math.ceil to every component
vector.absLuau
Applies math.abs to every component
vector.signLuau
Applies math.sign to every component
vector.clampLuau
Clamps every component to the matching components of min and max
vector.maxLuau
Returns the largest of each component across the arguments
vector.minLuau
Returns the smallest of each component across the arguments

Interpolation

vector.lerpLuau
Interpolates linearly between two vectors

Creating

vector.zeroLuau

vector.zero: vector

A vector with every component set to 0, including the fourth in 4-wide mode.

vector.oneLuau

vector.one: vector

A vector with every component set to 1, including the fourth in 4-wide mode.

vector.createLuau

function vector.create(x: number, y: number, z: number?): vector

Creates a vector from its components. z defaults to 0. In 4-wide mode it takes a fourth argument for w that also defaults to 0.

Upstream Luau's library reference lists z as required. Luwu's type checker and VM both accept two arguments.

Length and direction

vector.magnitudeLuau

function vector.magnitude(vec: vector): number

Returns the length of the vector, including the fourth component in 4-wide mode.

vector.normalizeLuau

function vector.normalize(vec: vector): vector

Returns the unit vector pointing the same way as vec. It includes the fourth component in 4-wide mode. Normalizing vector.zero gives NaN in every component.

Products and angles

vector.crossLuau

function vector.cross(vec1: vector, vec2: vector): vector

Returns the cross product of two vectors. In 4-wide mode it ignores the fourth component and sets it to 0 in the result.

vector.dotLuau

function vector.dot(vec1: vector, vec2: vector): number

Returns the dot product of two vectors, including the fourth component in 4-wide mode.

vector.angleLuau

function vector.angle(vec1: vector, vec2: vector, axis: vector?): number

Returns the angle between two vectors in radians, from 0 to π. When axis is given, the angle is negative if the cross product of vec1 and vec2 points away from axis. The fourth component is ignored in 4-wide mode.

Input
const right = vector.create(1, 0, 0)
const up = vector.create(0, 1, 0)

print(vector.angle(right, up))
print(vector.angle(right, up, vector.create(0, 0, -1)))
Output
1.5707963267948966
-1.5707963267948966

Component by component

vector.floorLuau

function vector.floor(vec: vector): vector

Applies math.floor to every component.

vector.ceilLuau

function vector.ceil(vec: vector): vector

Applies math.ceil to every component.

vector.absLuau

function vector.abs(vec: vector): vector

Applies math.abs to every component.

vector.signLuau

function vector.sign(vec: vector): vector

Applies math.sign to every component: -1 for negative, 0 for zero and 1 for positive.

vector.clampLuau

function vector.clamp(vec: vector, min: vector, max: vector): vector

Applies math.clamp to every component of vec using the matching components of min and max. It throws when a component of min is greater than the same component of max.

vector.maxLuau

function vector.max(first: vector, ...: vector): vector

Returns a vector whose every component is the largest of that component across the arguments. It takes at least one vector.

Input
const a = vector.create(1, 5, 2)
const b = vector.create(4, 0, 3)

print(`{vector.max(a, b)}`)
print(`{vector.min(a, b)}`)
Output
4, 5, 3
1, 0, 2

vector.minLuau

function vector.min(first: vector, ...: vector): vector

Returns a vector whose every component is the smallest of that component across the arguments. It takes at least one vector.

Interpolation

vector.lerpLuau

function vector.lerp(vec1: vector, vec2: vector, t: number): vector

Interpolates linearly from vec1 to vec2: it computes vec1 + (vec2 - vec1) * t for each component. When t is exactly 1 the result is exactly vec2. A t outside 0 to 1 extrapolates past the ends.

Input
const start = vector.zero
const finish = vector.create(10, 20, 40)

print(`{vector.lerp(start, finish, 0.25)}`)
Output
2.5, 5, 10

Upstream Luau's library reference doesn't list vector.lerp yet.