Awesome
brinevector
A simple vector lua library for everyone!
Motivation
While looking for vector libraries for lua, I noticed most of them use tables to store the vectors themselves. This might be fine for most applications, but for games and high-performance uses, creating a table for every vector is simply too much overhead. Using C data to store and create vectors with the ffi
library in luajit is a much more efficient method that can produce code that performs much faster and consumes a lot less memory. (Depending on the application, around 35x less memory, and 20x better performance!)
So I wrote this vector library to take advantage of that fact, and made it extremely beginner-friendly and easy for everybody to use. It's also designed to be lightweight and very portable; it's only really a single file!
And if the library detects that you're on a platform that does not fully support the ffi
library, then it will automatically fall back to using your standard lua tables, meaning there are no downsides to sticking with brinevector when developing for mobile compared to other vector libraries.
Compatibility
BrineVector was written for LOVE2D and is accelerated by the ffi module in luajit, but can be used for any luajit program.
Fallback to standard lua tables
This library takes advantage of the JIT compiler on desktop targets for LOVE2D. This gives a great performance boost to desktop applications, but for mobile and console platforms, the JIT is disabled because they do not allow execution of arbitrary runtime code.
The ffi
library still works, but it takes much longer to call functions and marshal values between lua and C. Even longer than if brinevector used tables instead. This means that a mobile or console app would be better off falling back to a table implementation of vectors rather than using the ffi
library.
Fortunately, brinevector is aware of this limitation, and will automatically fall back to tables if it detects that it's running on mobile or consoles. This gives you the same amount of performance as any other table-based vector library on mobile and consoles, but also gives you a tremendous boost to desktop games, all without having to do anything on your end.
installation
Paste the brinevector.lua
file and its accompanying BRINEVECTOR_LICENSE
into your project.
Simply require
the file in your projects and give the returned table a name
Vector = require "brinevector"
Or,
local Vector = require "brinevector"
You can replace Vector
with any name you wish to use. Even V
, for brevity. If you gave it any other name than Vector
, in all code examples that follow, replace Vector
with whatever name you gave it in the require
call.
usage
Here is an overview of all the features, properties, and methods of this library all in one place, and for most people, is everything they need to use this library.
For beginners, or for anyone who wants more details, read the sections down below.
Contents
- Instantiating a vector
- Accessing a vector's components
- Printing a Vector
- Vector Arithmetic
- Vector Properties
- Vector Methods
- Method Shortcuts
- Comparing Vectors with
==
- Checking if a variable is a Vector
Instantiating a vector
To create a new vector, just call the module directly
local myVec = Vector(3,4)
where
- the first argument will be the x-component of the new vector,
- and the second argument will be the y-component of the new vector.
If no arguments are given, then it defaults to creating a zero-vector. (x component equals 0
and y component equals 0
). Thus
local zVec = Vector()
is equivalent to
local zVec = Vector(0,0)
Accessing a vector's components
Getting
Getting the x and y components of a vector works as you expect.
If you have
local myVec = Vector(3,4)
then myVec.x
and myVec.y
will return the x and y components of myVec
, respectively.
(3
and 4
)
print ( myVec.x ) -- prints "3"
print ( myVec.y ) -- prints "4"
Setting
Assigning and modifying the x and y components is also straightforward
myVec.x = 10
myVec.y = 20
will set the x component of myVec
to 10
and the y component to 20
Printing a vector
When using tostring
or print
on a vector, it will display in a readable format with 4 decimal places for each component. Thus,
local myVec = Vector(3,4)
print(myVec)
Outputs "Vector{3.0000,4.0000}"
, and
local myOtherVec = Vector(1.123456,-3.141592)
local myStr = "the vector is " .. tostring(myOtherVec)
print(myStr)
Outputs "the vector is Vector{1.1235,-3.1416}"
.
You can also concatenate strings with vectors with the ..
operator, thus
local velocity = Vector(123, 456)
print("my velocity is: " .. velocity)
Vector Arithmetic
Addition and Subtraction
You can add and subtract vectors using +
and -
If you have
local a = Vector(3,4)
local b = Vector(1,2)
then
a + b -- returns a vector <4,6>
a - b -- returns a vector <2,2>
b - a -- returns a vector <-2,-2>
a = a + b -- a then becomes <4,6>
Multiplication with a scalar
There are a few different types of vector multiplication. The simplest is multiplication of a vector with a number.
local a = Vector(3,4)
a * 5 -- returns <15,20>
a * -1 -- returns <-3,-4>
3.1415 * a -- returns <9.4245,12.5660>
local c = a * 2 -- instantiates a new vector with values <6,8>
Multiplication with another vector
In some cases, you might want to get a vector whose x component is the product of two other vectors' x components, and whose y component is the product of their y components. (ie. "Component-wise" or "Freshman" multiplication). This is supported with a simple * syntax
local a = Vector(3,4)
local b = Vector(4,-2)
local c = a * b -- c becomes <12,-8>
You can also do a:hadamard(b)
if you care about accurate mathematical terminology. It works the same.
Division with a scalar
Dividing a vector V
with a scalar x
, is exactly equivalent to multiplying V
with 1/x
. Thus,
local a = Vector(3,4)
a / 5 -- returns <0.6,0.8>
Division with a vector
In mathematics, there is no rule for dividing a vector with another vector, but because this library is mainly used in games, a division between vectors vecA
and vecB
produces a new vector whose components are the component-wise division of vecA
and vecB
local a = Vector(1,1)
local b = Vector(5,5)
a / b -- equivalent to Vector(a.x / b.x, a.y / b.y)
NaN handling
If either of the divisor's components are 0
then vector division will produce a NaN
, which this library treats as an error, because in LOVE2D, many bugs are caused by hidden NaN
s allowed to propagate.
Negation
A vector preceded by the unary minus operation (like -v
, where v
is a vector) is exactly equivalent to v * -1
local a = Vector(3,4)
-a -- returns <-3,-4>
-a * 5 -- returns <-15,-20>
Modulo
A vector can be made to undergo a modulo operation with either a scalar or another vector.
-- with scalar
local a = Vector(10, 4)
local b = a % 3 -- b is <1, 1>
local c = 33 % a -- c is <3, 1>
-- with vector
local x = Vector(13, 17)
local y = Vector(2, 3)
x % y -- result is <1, 2>
Note that the result will be different if you swap the values of the two operands. (In other words, x % y is not the same as y % x, and this is also applies to vectors under this operation)
Vector properties
For maximum convenience and ease of use, the most common properties of a vector are accessed just like any members of a table, without having to call any methods like in other libraries.
These are:
length
angle
normalized
length2
inverse
copy
length
You can access the length of a vector with .length
or by using the lua #
operator.
Thus if you have
local myVec = Vector(3,4)
then
myVec.length
produces 5
.
#myVec
will also produce 5
Even if you edit the vector later on, accessing the length
property automatically computes the new length. This makes code shorter and more understandable. This is true for all the other special properties. They are generated on the fly when you ask for them.
local myVec = Vector(3,4)
local a = myVec.length -- a becomes '5'
myVec = myVec * 3 -- myVec is now <9,12>
local b = myVec.length -- b becomes '15'
Notice how you don't need to use a method like a:length()
or a:getLength()
.
You simply use a.length
angle
Using .angle
gives the angle of a vector in radians
local myVec = Vector(1,1)
myVec.angle -- produces PI/4 radians, or 0.78539816339744828
normalized
Using .normalized
gives the normalized vector of a given vector. That is, a vector with the same angle as the original, but whose length is 1
.
local myVec = Vector(3,4)
local myVecN = myVec.normalized -- myVecN becomes <0.6,0.8>
myVecN.length -- is '1'
length2
For most purposes (like comparing the lengths of vectors) you only need to compare the squares of the lengths of the vectors. This is because to get the length, any library needs to call math.sqrt
. This can be slow, and so if you're conscious about performance, you can use .length2
, which returns the length of a vector squared
-- compare the lengths of two vectors
local bakery = Vector(3,4)
local restaurant = Vector(10,10)
if bakery.length2 < restaurant.length2 then
print("The bakery is closer")
elseif bakery.length2 > restaurant.length2 then
print("The restaurant is closer")
end
-- outputs "The bakery is closer"
inverse
Gets the component-wise multiplicative inverse of the vector. For a vector (x, y)
, it's inverse will be (1 / x, 1 / y)
local newVec = myVec.inverse
is the same as
local newVec = Vector(1 / myVec.x, 1 / myVec.y)
copy
Produces a copy of the vector with the same x and y values, but with a different memory address. This allows passing vectors by copy instead of by reference.
Lua by default passes cdata like these vectors by reference, which can cause many kinds of bugs. To avoid these, when assigning vectors, try using vecA = vecB.copy
.
floor
Gives the vector that would be formed by taking the math.floor
results of the x
and y
components of a vector
local myVec = Vector(1.123, 5.234)
print( myVec.floor )
-> Vector{1.0000, 5.0000}
ceil
Gives the vector that would be formed by taking the math.ceil
results of the x
and y
components of a vector
local myVec = Vector(1.123, 5.234)
print( myVec.ceil )
-> Vector{2.0000, 6.0000}
Vector methods
Property methods
If you prefer getting the above properties with methods instead like in other libraries, you can always still use the following:
myVec:getLength()
-- equivalent tomyVec.length
myVec:getAngle()
-- equivalent tomyVec.angle
myVec:getNormalized()
-- equivalent tomyVec.normalized
myVec:getLengthSquared()
-- equivalent tomyVec.length2
myVec:getInverse()
-- equivalent tomyVec.inverse
myVec:getCopy()
-- equivalent tomyVec.copy
myVec:getFloor()
-- equivalent tomyVec.floor
myVec:getCeil()
-- equivalent tomyVec.ceil
dot
myVec:dot( vector )
This returns a scalar which is the "dot" product with another vector. The formula is as follows:
-- A dot product of two vectors A and B is equal to (A.x * B.x) + (A.y * B.y)
local a = Vector(3,4)
local b = Vector(6,3)
local result = a:dot(b) -- result is 30
assert(result == a.x * b.x + a.y * b.y)
angled
myVec:angled( angle )
This returns a vector whose length is the same as myVec
but whose angle is set to angle
(in radians). For example,
local a = Vector(3,4)
local b = a:angled(0)
will set b
to a vector with length 5
and whose angle is 0
. ie. <5,0>
This is equivalent to
local a = Vector(3,4)
local b = Vector(a.length*math.cos(0), a.length*math.cos(0))
rotated
myVec:rotated( angle )
This returns a vector whose angle is equal to the current angle of myVec
plus angle
.
For instance, if myVec
has a length of 5
and whose angle is PI
radians, then myVec:rotated( math.pi )
will give a vector whose length is still 5
but whose angle is 2 * PI
radians.
-- vector pointing 45 degrees with length sqrt(2)
local myVec = Vector(1, 1)
-- rotate it +45 degrees more
local rotatedVec = myVec:rotated(math.pi / 4)
print(rotatedVec)
> "Vector{0.0000,1.4142}" -- length is same, but angle is now 90 degrees
trim
myVec:trim( length )
This returns a vector with the same angle as myVec
, but whose length is "trimmed" down to length
only if it is longer than length
.
That is, if the length of myVec
is greater than length
, then the returned vector will have length length
. If the length of myVec
is less than length
then it will return a vector identical to myVec
local a = myVec:trim( 10 )
is equivalent to the following code:
local a = Vector(myVec.x, myVec.y)
if a.length > 10 then
a = a.normalized * 10
end
This is useful for applying max velocity to an accelerating object. For example if you're updating the velocity vel
of an object with acceleration acc
, and whose speed must be capped to MAXSPEED
, you can write,
vel = (vel + acc):trim(MAXSPEED)
instead of
vel = vel + acc
if vel.length > MAXSPEED then
vel = vel.normalized * MAXSPEED
end
hadamard
myVec:hadamard( otherVec )
This returns a vector that is the result of a component-wise multiplication between myVec
and otherVec
. Thus a = b:hadamard(c)
is equivalent to
a = Vector( b.x * c.x, b.y * c.y )
Alternatively, you can use a = b * c
.
split
myVec:split( )
This returns two values: the x component of the vector, and the y component of the vector. Thus,
local x, y = myVec:split()
is equivalent to
local x, y = myVec.x, myVec.y
clamp
myVec:clamp(min, max)
This clamps the vector myVec
per component between min
and max
That is,
myVec:clamp(vecA, vecB)
is equivalent to
myVec = Vector(
clamp(myVec, vecA.x, vecB.x),
clamp(myVec, vecA.y, vecB.y)
)
where clamp
is defined as follows:
-- if value is less than min, returns min
-- if value is greater than max, returns max
-- else, returns value
local function clamp(value, min, max)
return math.min(math.max(min, value), max)
end
Think of it like you're clamping a vector to be within a rectangle whose top left edge is at vecA
and whose bottom right edge is at vecB
. This is very common when implementing cameras with set limits as to how far it can go.
Method Shortcuts
Vectors can also be directly modified through their length
and angle
properties. This makes for some very short code.
If you have
myVec = Vector(3,4)
, and you want to modify it such that it keeps its direction but its length changes to 20
, then you can simply do
myVec.length = 20
And now if you inspect myVec
,
"Vector{12.0000,16.0000}"
This is equivalent to
myVec = myVec.normalized * 20
Similarly, if you have a vector
myUnitVec = Vector(1,0)
And you want it to point to an angle called someangle
, but still have a length of 1, then simply do
myUnitVec.angle = someangle
This is equivalent to
myUnitVec = myUnitVec:angled(someangle)
Comparing vectors with ==
Vectors can be compared with any other data using ==
.
myVec == something
will only return true
if
something
is another vector andsomething.x
==myVec.x
andsomething.y
==myVec.y
Otherwise, it will return false
Checking if a variable is a vector
Use Vector.isVector(x)
to check if x
is a vector instantiated from the table returned by require "brinevector"
.
license
Copyright 2018 'novemberisms'
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.