The Box2D library uses two-dimensional vectors in a form of its own native data type called b2Vec2. It's used in many places of the Box2D library so it's better to stick with this one.
This data type can be used to specify the position in a 2D space, directional vector with unit size or a speed vector. Keep in mind that Box2D doesn't know the difference between the uses of this vector.
This recipe expects the user to have a basic knowledge of vector math.
The LuaBox2D library contains the b2Vec2 object interface called Vec2. You can create one simply by calling its constructor function. Almost all object constructors are available via the LuaBox2D interface:
local box2d = require 'LuaBox2D' local Vec2 = box2d.Vec2
This will define a shortcut for the Vec2 object constructor.
You can create a new Vec2 vector object by calling the constructor in one of the following ways:
-- create zero vector local vector1 = Vec2() -- create a vector with x=1 and y=2 local vector2 = Vec2(1, 2)
The first case uses the Vec2 object constructor without a parameter that will create a vector with both coordinates set to zero. This is also known as a zero vector. The second case uses the constructor parameters to set initial coordinate values.
Each Vec2 vector object contains two coordinates: x and y. You can access and modify them directly as shown in the following sample code:
local vector = Vec2(1, 2) vector.x = 10.5 vector.y = 13.25 + vector.x
The Vec2 object provides the following set of mathematical operations: addition, subtraction, negation, scalar multiplication, dot product, and cross product. All operations are immutable, which means that each mathematical operation on vectors results in a new Vec2 object. Unused vector objects are automatically cleaned with a garbage collection mechanism. This behavior is a part of the Lua language design.
The following table will show the usage of basic mathematical operations on the Vec2 object where v1 and v2 variables present valid Vec2 objects:
|
Operation |
Lua notation |
|---|---|
|
The addition of two Vec2 vectors |
|
|
The addition of the Vec2 vector with a scalar number |
|
|
The subtraction of two Vec2 vectors |
|
|
The subtraction of the Vec2 vector with a scalar number |
|
|
The Vec2 vector negation |
|
|
The scalar multiplication of the Vec2 vector |
|
|
The dot product of two Vec2 vectors |
|
|
The cross product of two Vec2 vectors |
|
There are other operations available on vectors such as: vector equality comparison, the minimum and maximum of two vectors, vector normalization, vector length determination, the distance between two positional vectors, and the clamping of a vector.
|
Operation |
Lua notation |
|---|---|
|
Compare two vectors |
|
|
Get a minimum of two vectors |
|
|
Get a maximum of two vectors |
|
|
Get the vector length |
or
|
|
Obtain a distance between two positional vectors |
|
|
Clamp a vector |
|
The Vec2 object presents an interface between the Lua and Box2D world for the b2Vec2 object. Its purpose is to make using 2D vectors easier.
Keep in mind that the Vec2 object adds a small overhead because it must create the b2Vec2 object before use, and with each call of the mathematical operator, it has to do an input validation.