VectR.lua
Attention: This page contains dead links!
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.
Contents
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. |