VectR.lua

THIS DOCUMENTATION IS A WORK IN PROGRESS. PLEASE COME BACK WHEN IT IS COMPLETE

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 = loadAPI("vectr");

This will load the VectR API.

Example

local vectr = loadAPI("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

Classes

These are classes contained within this library

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 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: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 plane 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.

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.