Vector¶

Overview¶

Vectors are used to represent positional and colour data, and can contain between 2, 3, or 4 float values.

Examples¶

local v = Vector2.new(0.3, 10.0)
v = v + Vector.new(5.0, 0.1)
print(v.x, v.y) -- 5.3, 10.1

print(v:Dot(Vector2.new(1.0, 0.0))) -- 5.3

local v = Vector3.new(5.0)
print(v.x, v.y, v.z) -- 5.0, 5.0, 5.0

v.y = -3.1
v.z = v.z - 9.5
print(v.x, v.y, v.z) -- 5.0, -3.1, -4.5

v = v:Abs()
print(v.x, v.y, v.z) -- 5.0, 3.1, 4.5

local colour = Vector4.new(1.0, 0.5, 0.0, 1.0)
colour = colour * Vector4.new(1.0, 0.0, 0.0, 1.0)
print(colour.x, colour.y, colour.z, colour.w) -- 1.0, 0.0, 0.0, 1.0
print(colour.r, colour.g, colour.b, colour.a) -- 1.0, 0.0, 0.0, 1.0

local rgbOnly = colour.rgb
rgbOnly = rgbOnly + Vector3.new(0.0, 0.3, 0.7)
print(rgbOnly.x, rgbOnly.y, rgbOnly.z) -- 1.0, 0.3, 0.7
print(rgbOnly.r, rgbOnly.g, rgbOnly.b) -- 1.0, 0.3, 0.7

Common Methods and Properties¶

The methods/properties listed under this section are available on vectors regardless of their size.

Abs¶

function Vector:Abs() -> Vector

Computes the absolute value representation for the provided vector and returns it.

local a = Vector2.new(1.4, -5.8)
a = Vector2:Abs()
print(a.x, a.y) -- 1.4, 5.8

Ceil¶

function Vector:Ceil() -> Vector

Returns a vector where each element is the smallest integer that's greater than the original element.

local a = Vector2.new(1.4, -5.8)
a = Vector2:Ceil()
print(a.x, a.y) -- 2.0, -5.0

Floor¶

function Vector:Floor() -> Vector

Returns a vector where each element is the largest integer that's not greater than the original element.

local a = Vector2.new(1.4, -5.8)
a = Vector2:Floor()
print(a.x, a.y) -- 1.0, -6.0

Dot¶

function Vector:Dot(other : Vector) -> Float

Returns the dot-product of two vectors.

local a = Vector2.new(1, 5)
local b = Vector2.new (-2, 10)
print(a:Dot(b)) -- 48

local a = Vector3.new(0.5, -50, 10)
local b = Vector3.new (5, 0, -40)
print(a:Dot(b)) -- -397.5

Max¶

function Vector:Max(other : Vector) -> Vector

Returns an element-wise maximum between two vectors.

local a = Vector3.new(0.5, -50, 10)
local b = Vector3.new (5, 0, -40)
local c = a:Max(b)
print(c.x, c.y, c.z) -- 5, 0, 10

Min¶

function Vector:Min(other : Vector) -> Vector

Returns an element-wise minimum between two vectors.

local a = Vector3.new(0.5, -50, 10)
local b = Vector3.new (5, 0, -40)
local c = a:Min(b)
print(c.x, c.y, c.z) -- 0.5, -50, -40

Normalise¶

function Vector:Normalise()

Normalises the current vector, rescaling its elements so it becomes a vector of length 1. Does nothing if all elements of the vector are 0.

local v = Vector2.new(5, -2)
v:Normalise()
print(v.x, v.y) -- 0.93, -0.37

local v = Vector3.new(1.0, 0.5, 0.5)
v:Normalise()
print(v.x, v.y, v.z) -- 0.82, 0.41, 0.41

local v = Vector4.new(0.0)
v:Normalise()
print(v.x, v.y, v.z, v.w) -- 0.0, 0.0, 0.0, 0.0

NormaliseSafe¶

function Vector:Normalise(fallback : Vector) -> Vector

Returns a normalised version of the provided vector, with its elements rescaled so it becomes a vector of length 1.

If all of the provided vector's elements are 0, returns the fallback vector instead.

local target = Vector3.new(10, 0.0, 0.0)
local origin = Vector3.new(0.0, 0.0, 10.0)
local delta = target - origin

local direction = delta:NormaliseSafe(Vector3.new(0.0, 0.0, 1.0))
-- Always safe to use direction vector regardless of whether delta's length was 0 or not

Properties¶

Vector2¶

Additional properties and methods provided for Vector2 types.

Constructors¶

function Vector2.new() -> Vector2
function Vector2.new(v : Float) -> Vector2
function Vector2.new(x : Float, y : Float) -> Vector2

Creates and returns a vector with the provided values, or with all elements set to 0 if no arguments were provided.

Properties¶

Vector3¶

Additional properties and methods provided for Vector3 types.

Constructors¶

function Vector3.new() -> Vector3
function Vector3.new(v : Float) -> Vector3
function Vector3.new(x : Float, y : Float, z : Float) -> Vector3

Creates and returns a vector with the provided values, or with all elements set to 0 if no arguments were provided.

Cross¶

function Vector3:Cross(other : Vector3) -> Vector3

Returns the cross-product of two 3D vectors.

local a = Vector3.new(0.5, -50, 10)
local b = Vector3.new (5, 0, -40)
local c = a:Cross(b)
print(c.x, c.y, c.z) -- 2000, 70, 250

Reflect¶

function Vector3:Cross(normal : Vector3) -> Vector3

Calculates the reflection of the current vector along the provided normal.

local a = Vector3.new(0.5, -50, 10):Normalise()
local b = Vector3.new(5, 0, -40):Normalise()
local c = a:Reflect(b)

Rotate¶

function Vector3:Rotate(rotation : Quaternion) -> Vector3

Calculates the result of rotating this vector by the provided quaternion.

local v = Vector3.new(1.0, 0.0, 0.0)
local rotation = Quaternion.fromYawPitchRoll(160.0, 0.0, 0.0)
v = v:Rotate(rotation)

Properties¶

Vector4¶

Additional properties and methods provided for Vector4 types.

Constructors¶

function Vector4.new() -> Vector4
function Vector4.new(v : Float) -> Vector4
function Vector4.new(x : Float, y : Float, z : Float, w : Float) -> Vector4
function Vector4.new(xy : Vector2, zw : Vector2) -> Vector4

Creates and returns a vector with the provided values, or with all elements set to 0 if no arguments were provided.

Properties¶