VectR.lua

Attention: This page contains dead links!

Download Latest Version

VectR is a library designed to simplify vector mathematics and matrix calculations. It supports 2,3 and 4 dimensional vectors, as well as their equivalent square matrices.

Installation

Place the file vectr.lua into the LuaScriptsLib folder.


How to use

To enable the VectR library for a specific level, add this line to lunadll.lua:

local vectr = API.load("vectr");

This will load the VectR API.

Example

local vectr = API.load("vectr");
    
--Create a 3 dimensional vector
local v = vectr.v3(13,26,-3);
--Create a 3x3 matrix
local m = vectr.mat3({2,  4, -1},
                     {8,  6,  6},
                     {0,  1,  7});

function onLoop()
    --Perform a matrix multiplication to transform the vector.
    Text.print(tostring(m*v),0,0);
end

This will transform the vector "v" by the matrix "m".

Documentation

Values

These are variables you can access

zero2 Vector2 The vector (0,0)
right2 Vector2 The vector (1,0)
up2 Vector2 The vector (0,1)
zero3 Vector3 The vector (0,0,0)
right3 Vector3 The vector (1,0,0)
up3 Vector3 The vector (0,1,0)
forward3 Vector3 The vector (0,0,1)
zero4 Vector4 The vector (0,0,0,0)
right4 Vector4 The vector (1,0,0,0)
up4 Vector4 The vector (0,1,0,0)
forward4 Vector4 The vector (0,0,1,0)
w4 Vector4 The vector (0,0,0,1)
empty2 Mat2 The 2x2 zero matrix.
id2 Mat2 The 2x2 identity matrix.
empty3 Mat3 The 3x3 zero matrix.
id3 Mat3 The 3x3 identity matrix.
empty4 Mat4 The 4x4 zero matrix.
id4 Mat4 The 4x4 identity matrix.
_ver string The current VectR version.

Classes

These are classes contained within this library

VECTORS


Vector2

Values

Vector2.x The x value of the vector
Vector2.y The y value of the vector
Vector2.length The length of the vector
Vector2.sqrlength The squared length of the vector
Vector2._type A constant value that always contains the string "vector2"

Functions

Vector2:normalise
Calculates the normalised direction vector. Vector2
Vector2:normalize
Equivalent to "normalise". Vector2
Vector2:dot vector
Calculates the dot product between two vectors. number Vector2

The other vector.

Vector2:project vector
Projects the vector onto the line defined by the other vector. Vector2 Vector2

The other vector.

Vector2:rotate angle
Rotates the vector by a given angle. Vector2 number

The rotation angle in degrees.

Vector2:lookat x y
Rotates a vector to point in the direction defined by the given coordinates. Vector2 number

The x component of the other vector.

number

The y component of the other vector.

Vector2:lookat vector
Rotates a vector to point in the direction of the other vector. Vector2 Vector2

The other vector.

Vector2:tov3
Converts a vector to a 3 dimensional vector. The z-value will be set to 0. Vector3
Vector2:tov4
Converts a vector to a 4 dimensional vector. The z-value and w-value will be set to 0. Vector4

Operators

v1 + v2 Adds two vectors together, element-wise. Either vector can be substituted with a number to add to all elements in the vector.
v1 - v2 Subtracts one vector from another, element-wise. Either vector can be substituted with a number to subtract from all elements in the vector.
v1 * v2 Multiplies two vectors together, element-wise. Either vector can be substituted with a number to multiply by all elements in the vector.
v1 / v2 Divides two vectors by each other, element-wise. Either vector can be substituted with a number to divide all elements in the vector.
-v Negates a vector. Equivalent to "v*-1".
v1..v2 Computes the dot product of two vectors. Equivalent to "v1:dot(v2)".
v1%v2 Computes the projection of one vector onto another. Equivalent to "v1:project(v2)".
v1 == v2 Checks if two vectors hold the same value.
tostring(v) Converts a vector to a string representation.


Vector3

Values

Vector3.x The x value of the vector
Vector3.y The y value of the vector
Vector3.z The z value of the vector
Vector3.length The length of the vector
Vector3.sqrlength The squared length of the vector
Vector3._type A constant value that always contains the string "vector3"

Functions

Vector3:normalise
Calculates the normalised direction vector. Vector3
Vector3:normalize
Equivalent to "normalise". Vector3
Vector3:dot vector
Calculates the dot product between two vectors. number Vector3

The other vector.

Vector3:cross vector
Calculates the cross product between two vectors. Vector3 Vector3

The other vector.

Vector3:project vector
Projects the vector onto the line defined by the other vector. Vector3 Vector3

The other vector.

Vector3:rotate roll pitch yaw
Rotates the vector by a given set of angles. Vector3 number

The rotation angle along the x axis.

number

The rotation angle along the y axis.

number

The rotation angle along the z axis.

Vector3:rotate angle axis
Rotates the vector by a given angle around the given axis. Vector3 number

The rotation angle around the axis.

Vector3

The axis to rotate around.

Vector3:rotate matrix
Rotates the vector using a given rotation matrix Vector3 Mat3

The rotation matrix.

Vector3:lookat x y z
Rotates a vector to point in the direction defined by the given coordinates. Vector3 number

The x component of the other vector.

number

The y component of the other vector.

number

The z component of the other vector.

Vector3:lookat vector
Rotates a vector to point in the direction of the other vector. Vector3 Vector3

The other vector.

Vector3:planeproject normal
Projects a vector onto the 2D plane defined by the given normal vector. Vector3 Vector3

The normal vector.

Vector3:tov2
Converts a vector to a 2 dimensional vector. The z-value will be discarded. Vector2
Vector3:tov4
Converts a vector to a 4 dimensional vector. The w-value will be set to 0. Vector4


Operators

v1 + v2 Adds two vectors together, element-wise. Either vector can be substituted with a number to add to all elements in the vector.
v1 - v2 Subtracts one vector from another, element-wise. Either vector can be substituted with a number to subtract from all elements in the vector.
v1 * v2 Multiplies two vectors together, element-wise. Either vector can be substituted with a number to multiply by all elements in the vector.
v1 / v2 Divides two vectors by each other, element-wise. Either vector can be substituted with a number to divide all elements in the vector.
-v Negates a vector. Equivalent to "v*-1".
v1..v2 Computes the dot product of two vectors. Equivalent to "v1:dot(v2)".
v1^v2 Computes the cross product of two vectors. Equivalent to "v1:cross(v2)".
v1%v2 Computes the projection of one vector onto another. Equivalent to "v1:project(v2)".
v1 == v2 Checks if two vectors hold the same value.
tostring(v) Converts a vector to a string representation.

Vector4

Values

Vector4.x The x value of the vector
Vector4.y The y value of the vector
Vector4.z The z value of the vector
Vector4.w The w value of the vector
Vector4.length The length of the vector
Vector4.sqrlength The squared length of the vector
Vector4._type A constant value that always contains the string "vector4"

Functions

Vector4:normalise
Calculates the normalised direction vector. Vector4
Vector4:normalize
Equivalent to "normalise". Vector4
Vector4:dot vector
Calculates the dot product between two vectors. number Vector4

The other vector.

Vector4:project vector
Projects the vector onto the line defined by the other vector. Vector4 Vector4

The other vector.

Vector4:rotate roll pitch yaw
Rotates the vector by a given set of angles. Rotation only occurs in 3D space. The w-value will be left unchanged. Vector4 number

The rotation angle along the x axis.

number

The rotation angle along the y axis.

number

The rotation angle along the z axis.

Vector4:rotate angle axis
Rotates the vector by a given angle around the given axis. Rotation only occurs in 3D space. The w-value will be left unchanged. Vector4 number

The rotation angle around the axis.

Vector3

The axis to rotate around.

Vector4:rotate matrix
Rotates the vector using a given rotation matrix. Rotation only occurs in 3D space. The w-value will be left unchanged. Vector4 Mat3

The rotation matrix.

Vector4:rotate matrix
Rotates the vector using a given rotation matrix, in 4D space. Vector4 Mat4

The rotation matrix.

Vector4:lookat x y z
Rotates a vector to point in the direction defined by the given coordinates. Rotation only occurs in 3D space. The w-value will be left unchanged. Vector4 number

The x component of the other vector.

number

The y component of the other vector.

number

The z component of the other vector.

Vector4:lookat vector
Rotates a vector to point in the direction of the other vector. Rotation only occurs in 3D space. The w-value will be left unchanged. Vector4 Vector3

The other vector.

Vector4:planeproject normal
Projects a vector onto the 3D hyperplane defined by the given normal vector. Vector4 Vector4

The normal vector.

Vector4:tov2
Converts a vector to a 2 dimensional vector. The z-value and w-value will be discarded. Vector2
Vector4:tov3
Converts a vector to a 3 dimensional vector. The w-value will be discarded. Vector3


Operators

v1 + v2 Adds two vectors together, element-wise. Either vector can be substituted with a number to add to all elements in the vector.
v1 - v2 Subtracts one vector from another, element-wise. Either vector can be substituted with a number to subtract from all elements in the vector.
v1 * v2 Multiplies two vectors together, element-wise. Either vector can be substituted with a number to multiply by all elements in the vector.
v1 / v2 Divides two vectors by each other, element-wise. Either vector can be substituted with a number to divide all elements in the vector.
-v Negates a vector. Equivalent to "v*-1".
v1..v2 Computes the dot product of two vectors. Equivalent to "v1:dot(v2)".
v1%v2 Computes the projection of one vector onto another. Equivalent to "v1:project(v2)".
v1 == v2 Checks if two vectors hold the same value.
tostring(v) Converts a vector to a string representation.

MATRICES



Mat2

Values

Mat2[i][j] The element at row i and column j in the matrix.
Mat2.det The determinant of the matrix.
Mat2.trace The trace of the matrix.
Mat2.inverse The inverse of the matrix. If the matrix is singular (i.e. not invertible), this becomes nil.
Mat2.transpose The transpose of the matrix.
Mat2._type A constant value that always contains the string "mat2"

Functions

Mat2:tomat3
Converts a 2x2 matrix to a 3x3 matrix. The original matrix will be placed in the top left of the larger matrix, with the remaining elements filled by the identity matrix. Mat3
Mat2:tomat4
Converts a 2x2 matrix to a 4x4 matrix. The original matrix will be placed in the top left of the larger matrix, with the remaining elements filled by the identity matrix. Mat4

Operators

m1 + m2 Adds two matrices together, element-wise. Either matrix can be substituted with a number to add to all elements in the matrix.
m1 - m2 Subtracts one matrix from another, element-wise. Either matrix can be substituted with a number to subtract from all elements in the matrix.
m1 * m2 Multiplies two matrices together using matrix multiplication. Either matrix can be substituted with a number to multiply the matrix element-wise, or the second matrix can be substituted with a Vector2, resulting in a new Vector2 object.
m1 / m2 Divides two matrices by each other by inverting the second matrix (equivalent to m1*m2.inverse). The second matrix can be substituted with a number to perform division element-wise. The first matrix can be substituted with a number to multiply the inverse element-wise.
-m Negates a matrix. Equivalent to "m*-1".
m1 == m2 Checks if two matrices hold the same value.
tostring(m) Converts a matrix to a string representation.

Mat3

Values

Mat3[i][j] The element at row i and column j in the matrix.
Mat3.det The determinant of the matrix.
Mat3.trace The trace of the matrix.
Mat3.inverse The inverse of the matrix. If the matrix is singular (i.e. not invertible), this becomes nil.
Mat3.transpose The transpose of the matrix.
Mat3._type A constant value that always contains the string "mat3"

Functions

Mat3:tomat2
Converts a 3x3 matrix to a 2x2 matrix. The trailing row and column will be lost. Mat2
Mat3:tomat4
Converts a 3x3 matrix to a 4x4 matrix. The original matrix will be placed in the top left of the larger matrix, with the remaining elements filled by the identity matrix. Mat4

Operators

m1 + m2 Adds two matrices together, element-wise. Either matrix can be substituted with a number to add to all elements in the matrix.
m1 - m2 Subtracts one matrix from another, element-wise. Either matrix can be substituted with a number to subtract from all elements in the matrix.
m1 * m2 Multiplies two matrices together using matrix multiplication. Either matrix can be substituted with a number to multiply the matrix element-wise, or the second matrix can be substituted with a Vector3, resulting in a new Vector3 object.
m1 / m2 Divides two matrices by each other by inverting the second matrix (equivalent to m1*m2.inverse). The second matrix can be substituted with a number to perform division element-wise. The first matrix can be substituted with a number to multiply the inverse element-wise.
-m Negates a matrix. Equivalent to "m*-1".
m1 == m2 Checks if two matrices hold the same value.
tostring(m) Converts a matrix to a string representation.

Mat4

Values

Mat4[i][j] The element at row i and column j in the matrix.
Mat4.det The determinant of the matrix.
Mat4.trace The trace of the matrix.
Mat4.inverse The inverse of the matrix. If the matrix is singular (i.e. not invertible), this becomes nil.
Mat4.transpose The transpose of the matrix.
Mat4._type A constant value that always contains the string "mat4"

Functions

Mat4:tomat2
Converts a 4x4 matrix to a 2x2 matrix. The trailing rows and columns will be lost. Mat2
Mat4:tomat3
Converts a 4x4 matrix to a 3x3 matrix. The trailing row and column will be lost. Mat3

Operators

m1 + m2 Adds two matrices together, element-wise. Either matrix can be substituted with a number to add to all elements in the matrix.
m1 - m2 Subtracts one matrix from another, element-wise. Either matrix can be substituted with a number to subtract from all elements in the matrix.
m1 * m2 Multiplies two matrices together using matrix multiplication. Either matrix can be substituted with a number to multiply the matrix element-wise, or the second matrix can be substituted with a Vector4, resulting in a new Vector4 object.
m1 / m2 Divides two matrices by each other by inverting the second matrix (equivalent to m1*m2.inverse). The second matrix can be substituted with a number to perform division element-wise. The first matrix can be substituted with a number to multiply the inverse element-wise.
-m Negates a matrix. Equivalent to "m*-1".
m1 == m2 Checks if two matrices hold the same value.
tostring(m) Converts a matrix to a string representation.

MAIN


External Use Functions

These are functions you will need to use the library

v2 x y
Creates a Vector2 object. Vector2 number

The X component.

number

The Y component.

v2 v
Copies a Vector2 object. Vector2 Vector2

The vector to copy.

v3 x y z
Creates a Vector3 object. Vector3 number

The X component.

number

The Y component.

number

The Z component.

v3 v
Converts a Vector2 object to a Vector3 object. The z-value will be set to 0. Vector3 Vector2

The vector to convert.

v3 v
Copies a Vector3 object. Vector3 Vector3

The vector to copy.

v4 x y z w
Creates a Vector4 object. Vector4 number

The X component.

number

The Y component.

number

The Z component.

number

The W component.

v4 v
Converts a Vector2 object to a Vector4 object. The z-value will be set to 0. The w-value will be set to 1. Vector4 Vector2

The vector to convert.

v4 v
Converts a Vector3 object to a Vector4 object. The w-value will be set to 1. Vector4 Vector3

The vector to convert.

v4 v
Copies a Vector4 object. Vector4 Vector4

The vector to copy.

mat2 row1 row2
Creates a Mat2 object. Mat2 table of number

The first row of elements (must contain exactly 2 elements).

table of number

The second row of elements (must contain exactly 2 elements).

mat2 m
Copies a Mat2 object. Mat2 Mat2

The matrix to copy.

mat3 row1 row2 row3
Creates a Mat3 object. Mat3 table of number

The first row of elements (must contain exactly 3 elements).

table of number

The second row of elements (must contain exactly 3 elements).

table of number

The third row of elements (must contain exactly 3 elements).

mat3 m
Copies a Mat3 object. Mat3 Mat3

The matrix to copy.

mat4 row1 row2 row3 row4
Creates a Mat4 object. Mat4 table of number

The first row of elements (must contain exactly 4 elements).

table of number

The second row of elements (must contain exactly 4 elements).

table of number

The third row of elements (must contain exactly 4 elements).

table of number

The fourth row of elements (must contain exactly 4 elements).

mat4 m
Copies a Mat4 object. Mat4 Mat4

The matrix to copy.

lerp number1 number2 parameter
Linearly interpolates between two numbers. When the parameter is 0, the result will be number1. When the parameter is 1, the result will be number2. number number

The 0-parameter number.

number

The 1-parameter number.

number

The parameter value, between 0 and 1.

lerp vector1 vector2 parameter
Linearly interpolates between two vectors. When the parameter is 0, the result will be vector1. When the parameter is 1, the result will be vector2. Vector2/Vector3/Vector4 Vector2/Vector3/Vector4

The 0-parameter vector.

Vector2/Vector3/Vector4

The 1-parameter vector.

number

The parameter value, between 0 and 1.

pairs vector
Allows iterating over a vector object. Used in place of the regular "pairs" function. The returned key will be a string containing "x","y","z" or "w", and the value will be the associated component in the vector. string,number Vector2/Vector3/Vector4

The vector to iterate over.

pairs matrix
Allows iterating over a matrix object. Used in place of the regular "pairs" function. The returned key will be a table containing the indices into the matrix, and the value will be the associated value in the matrix. table of number,number Mat2/Mat3/Mat4

The matrix to iterate over.