# VectR.lua

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 right2 Vector2 The vector (0,0) Vector2 The vector (1,0) Vector2 The vector (0,1) Vector3 The vector (0,0,0) Vector3 The vector (1,0,0) Vector3 The vector (0,1,0) Vector3 The vector (0,0,1) Vector4 The vector (0,0,0,0) Vector4 The vector (1,0,0,0) Vector4 The vector (0,1,0,0) Vector4 The vector (0,0,1,0) Vector4 The vector (0,0,0,1) Mat2 The 2x2 zero matrix. Mat2 The 2x2 identity matrix. Mat3 The 3x3 zero matrix. Mat3 The 3x3 identity matrix. Mat4 The 4x4 zero matrix. Mat4 The 4x4 identity matrix. string The current VectR version.

### Classes

These are classes contained within this library

## VECTORS

#### Vector2

Values

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

Functions

Vector2:normalise Vector2:normalize Vector2:dot vector Calculates the normalised direction vector. Vector2 Equivalent to "normalise". Vector2 Calculates the dot product between two vectors. number Vector2 The other vector. Projects the vector onto the line defined by the other vector. Vector2 Vector2 The other vector. Rotates the vector by a given angle. Vector2 number The rotation angle in degrees. 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. Rotates a vector to point in the direction of the other vector. Vector2 Vector2 The other vector. Converts a vector to a 3 dimensional vector. The z-value will be set to 0. Vector3 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. Subtracts one vector from another, element-wise. Either vector can be substituted with a number to subtract from all elements in the vector. Multiplies two vectors together, element-wise. Either vector can be substituted with a number to multiply by all elements in the vector. Divides two vectors by each other, element-wise. Either vector can be substituted with a number to divide all elements in the vector. Negates a vector. Equivalent to "v*-1". Computes the dot product of two vectors. Equivalent to "v1:dot(v2)". Computes the projection of one vector onto another. Equivalent to "v1:project(v2)". Checks if two vectors hold the same value. Converts a vector to a string representation.

#### Vector3

Values

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

Functions

Vector3:normalise Vector3:normalize Vector3:dot vector Vector3:cross Calculates the normalised direction vector. Vector3 Equivalent to "normalise". Vector3 Calculates the dot product between two vectors. number Vector3 The other vector. Calculates the cross product between two vectors. Vector3 Vector3 The other vector. Projects the vector onto the line defined by the other vector. Vector3 Vector3 The other vector. 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. 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. Rotates the vector using a given rotation matrix Vector3 Mat3 The rotation matrix. 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. Rotates a vector to point in the direction of the other vector. Vector3 Vector3 The other vector. Projects a vector onto the 2D plane defined by the given normal vector. Vector3 Vector3 The normal vector. Converts a vector to a 2 dimensional vector. The z-value will be discarded. Vector2 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. Subtracts one vector from another, element-wise. Either vector can be substituted with a number to subtract from all elements in the vector. Multiplies two vectors together, element-wise. Either vector can be substituted with a number to multiply by all elements in the vector. Divides two vectors by each other, element-wise. Either vector can be substituted with a number to divide all elements in the vector. Negates a vector. Equivalent to "v*-1". Computes the dot product of two vectors. Equivalent to "v1:dot(v2)". Computes the cross product of two vectors. Equivalent to "v1:cross(v2)". Computes the projection of one vector onto another. Equivalent to "v1:project(v2)". Checks if two vectors hold the same value. Converts a vector to a string representation.

#### Vector4

Values

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

Functions

Vector4:normalise Vector4:normalize Vector4:dot vector Vector4:project Calculates the normalised direction vector. Vector4 Equivalent to "normalise". Vector4 Calculates the dot product between two vectors. number Vector4 The other vector. Projects the vector onto the line defined by the other vector. Vector4 Vector4 The other vector. 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. 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. 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. Rotates the vector using a given rotation matrix, in 4D space. Vector4 Mat4 The rotation matrix. 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. 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. Projects a vector onto the 3D hyperplane defined by the given normal vector. Vector4 Vector4 The normal vector. Converts a vector to a 2 dimensional vector. The z-value and w-value will be discarded. Vector2 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. Subtracts one vector from another, element-wise. Either vector can be substituted with a number to subtract from all elements in the vector. Multiplies two vectors together, element-wise. Either vector can be substituted with a number to multiply by all elements in the vector. Divides two vectors by each other, element-wise. Either vector can be substituted with a number to divide all elements in the vector. Negates a vector. Equivalent to "v*-1". Computes the dot product of two vectors. Equivalent to "v1:dot(v2)". Computes the projection of one vector onto another. Equivalent to "v1:project(v2)". Checks if two vectors hold the same value. Converts a vector to a string representation.

## MATRICES

#### Mat2

Values

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

Functions

Mat2:tomat3 Mat2:tomat4 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 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. Subtracts one matrix from another, element-wise. Either matrix can be substituted with a number to subtract from all elements in the matrix. 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. 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. Negates a matrix. Equivalent to "m*-1". Checks if two matrices hold the same value. Converts a matrix to a string representation.

#### Mat3

Values

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

Functions

Mat3:tomat2 Mat3:tomat4 Converts a 3x3 matrix to a 2x2 matrix. The trailing row and column will be lost. Mat2 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. Subtracts one matrix from another, element-wise. Either matrix can be substituted with a number to subtract from all elements in the matrix. 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. 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. Negates a matrix. Equivalent to "m*-1". Checks if two matrices hold the same value. Converts a matrix to a string representation.

#### Mat4

Values

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

Functions

Mat4:tomat2 Mat4:tomat3 Converts a 4x4 matrix to a 2x2 matrix. The trailing rows and columns will be lost. Mat2 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. Subtracts one matrix from another, element-wise. Either matrix can be substituted with a number to subtract from all elements in the matrix. 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. 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. Negates a matrix. Equivalent to "m*-1". Checks if two matrices hold the same value. Converts a matrix to a string representation.

## MAIN

### External Use Functions

These are functions you will need to use the library

v2 x y v2 v v3 Creates a Vector2 object. Vector2 number The X component. number The Y component. Copies a Vector2 object. Vector2 Vector2 The vector to copy. Creates a Vector3 object. Vector3 number The X component. number The Y component. number The Z component. Converts a Vector2 object to a Vector3 object. The z-value will be set to 0. Vector3 Vector2 The vector to convert. Copies a Vector3 object. Vector3 Vector3 The vector to copy. Creates a Vector4 object. Vector4 number The X component. number The Y component. number The Z component. number The W component. 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. Converts a Vector3 object to a Vector4 object. The w-value will be set to 1. Vector4 Vector3 The vector to convert. Copies a Vector4 object. Vector4 Vector4 The vector to copy. 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). Copies a Mat2 object. Mat2 Mat2 The matrix to copy. 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). Copies a Mat3 object. Mat3 Mat3 The matrix to copy. 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). Copies a Mat4 object. Mat4 Mat4 The matrix to copy. 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. 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. 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. 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.