Skip to main content

Vectors and angles

Created by traceless.vector and traceless.angle. Both use the same mutable userdata. Vector methods require Vector userdata, not an x/y/z table. Vector operations use native float components; angles are degrees.

angles​

vector:angles()

Returns: pitch, yaw, roll numbers.

Converts a direction to angles in degrees and returns three scalar values.

dist​

vector:dist(other)

Returns: number.

Three-dimensional Euclidean distance to another Vector.

dist2d​

vector:dist2d(other)

Returns: number.

Two-dimensional distance using x and y only.

dot​

vector:dot(other)

Returns: number.

Dot product with another Vector.

init​

vector:init([x = 0 [, y = 0 [, z = 0]]])

Returns: the same Vector.

Mutates its three components and returns self. Omitted components become zero.

init_from_angles​

vector:init_from_angles(pitch, yaw)

Returns: the same Vector.

Mutates the vector to a direction generated from numeric pitch and yaw degrees; returns self.

length​

vector:length()

Returns: number.

Three-dimensional Euclidean length.

length2d​

vector:length2d()

Returns: number.

Length using x and y only.

length2dsqr​

vector:length2dsqr()

Returns: number.

Squared length using x and y only.

lengthsqr​

vector:lengthsqr()

Returns: number.

Squared three-dimensional length.

lerp​

vector:lerp(other, amount)

Returns: new Vector.

Interpolates from self to another Vector using a numeric amount. The amount is not clamped, so values outside 0–1 extrapolate.

normalize​

vector:normalize()

Returns: number: original length.

Mutates to unit length and returns its pre-normalization length. Zero vector stays unchanged and returns 0. This method does not return self for chaining.

normalized​

vector:normalized()

Returns: new Vector.

Returns a normalized copy; zero vector returns a zero copy without changing self.

scale​

vector:scale(factor)

Returns: none.

Mutates components by a numeric factor. It does not return self for chaining.

scaled​

vector:scaled(factor)

Returns: new Vector.

Returns a copy multiplied by a numeric factor without changing self.

to​

vector:to(other)

Returns: new Vector.

Returns other - self; this is a displacement, not a normalized direction.

unpack​

vector:unpack()

Returns: x, y, z numbers.

Returns three scalar components.

vectors​

vector:vectors()

Returns: right Vector, up Vector.

Produces independent basis vectors from this direction.

Fields​

x, y, and z are readable/writable numbers. For an angle they represent pitch, yaw, and roll. Setting an unknown field raises unknown vector field; reading an unknown member returns nil.

Operators​

a + b and a - b combine vectors componentwise; -a negates a vector. a * scalar scales, and a * b multiplies componentwise. a / scalar and a / b divide; zero scalar or any zero divisor component raises division by zero. A scalar on the left is not supported. All operators return new vectors and leave their operands unchanged.

local traceless = require("traceless")
local direction = traceless.vector(3, 4, 0)
local previous_length = direction:normalize() -- 5, not a vector
local offset = direction:scaled(20)