VectR.lua
This is the archived page of the old LunaLua documentation The rest of LunaLua related articles in this wiki contain a lot of outdated documentation preserved for historical purposes and may be used with legacy versions of the LunaLua.
Please visit the SMBX2 Documentation Page to access the latest documentation for the LunaLua scripting system of the SMBX2 Project. Adding LunaLua contents into this Wiki is not advised. |
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.
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. |