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!

~~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.