tutorial_vector_math

Vector Math

Introduction

This small tutorial aims to be a short and practical introduction to vector math, useful for 3D but also 2D games. Again, vector math is not only useful for 3D but also 2D games. It is an amazing tool once you get the grasp of it and makes programming of complex behaviors much simpler.

It often happens that young programmers rely too much on the incorrect math for solving a wide array of problems, for example using only trigonometry instead of vector of math for 2D games.

This tutorial will focus on practical usage, with immediate application to the art of game programming.

Coordinate Systems (2D)

Typically, we define coordinates as an (x,y) pair, x representing the horizontal offset and y the vertical one. This makes sense given the screen is just a rectangle in two dimensions. As an example, here is a position in 2D space:

A position can be anywhere in space. The position (0,0) has a name, it's called the origin. Remember this term well because it has more implicit uses later. The (0,0) of a n-dimensions coordinate system is the origin.

In vector math, coordinates have two different uses, both equally important. They are used to represent a position but also a vector. The same position as before, when imagined as a vector, has a different meaning.

When imagined as a vector, two properties can be inferred, the direction and the magnitude. Every position in space can be a vector, with the exception of the origin. This is because coordinates (0,0) can't represent direction (magnitude 0).

Direction

Direction is simply towards where the vector points to. Imagine an arrow that starts at the origin and goes towards a position. The tip of the arrow is in the position, so it always points outwards, away from the origin. Imagining vectors as arrows helps a lot.

Magnitude

Finally, the length of the vector is the distance from the origin to the position. Obtaining the length from a vector is easy, just use the Pithagorean Theorem.

var len = sqrt( x*x + y*y )

But.. Angles?

But why not using an angle? After all, we could also think of a vector as an angle and a magnitude, instead of a direction and a magnitude. Angles also are a more familiar concept.

To say truth, angles are not that useful in vector math, and most of the time they are not dealt with directly. Maybe they work in 2D, but in 3D a lot of what can usually be done with angles does not work anymore.

Still, using angles is still not an excuse, even for 2D. Most of what takes a lot of work with angles in 2D, is still much more natural easier to accomplish with vector math. In vector math, angles are useful only as measure, but take little part in the math. So, give up the trigonometry already, prepare to embrace vectors!

In any case, obtaining an angle from a vector is easy and can be accomplished with trig.. er what was that? I mean, the atan2(x,y) function.

Vectors in Godot

To make examples easier, it is worth explaining how vectors are implemented in GDScript. GDscript has both Vector2 and Vector3, for 2D and 3D math respectively. Godot uses Vector classes as both position and direction. They also contain x and y (for 2D) and x, y and z (for 3D) member variables.

# create a vector with coordinates (2,5)
var a = Vector2(2,5)
# create a vector and assign x and y manually
var b = Vector2()
b.x=7
b.y=8

When operating with vectors, it is not necessary to operate on the members directly (in fact this is much slower). Vectors support regular arithmetic operations:

#add a and b
var c = a+b
# will result in c vector, with value (9,13)

It is the same as doing:

var c = Vector2()
c.x=a.x+b.x
c.y=a.y+b.y

Except the former is way more efficient and readable.

Regular arithmetic operations such as addition, subtraction, multiplication and division are supported. Vector multiplication and division can also be mixed with single-digit numbers, also named scalars.

# Multiplication of vector by scalar
var c = a*2.0
# will result in c vector, with value (4,10)

Which is the same as doing

var c = Vector2()
c.x = a.x*2.0
c.y = a.y*2.0

Except, again, the former is way more efficient and readable.

Normal Vectors

Ok, so we know what a vector is. It has a direction and a magnitude. We also know how to use them in Godot. The next step is learning about normal vectors (also called unit vectors or just normals). Any vector with magnitude of length 1 is considered a normal vector. In 2D, imagine drawing a circle of radius one. That circle contains all normal vectors in existence for 2 dimensions:

So, what is so special about normal vectors? Normal vectors are amazing. In other words, normal vectors have several, very useful properties.

Can't wait to know more about the fantastic properties of normal vectors, but one step at a time. So, how is a normal vector created from a regular vector?

Normalization

Taking any vector and reducing it's magnitude to 1.0 while keeping it's direction is called normalization. Normalization is performed by dividing the x and y (and z in 3D) components of a vector by it's magnitude:

var a = Vector2(2,4)
var m = sqrt( a.x*a.x + a.y*a.y )
a.x/=m
a.y/=m

As you might have guessed, if the vector has magnitude 0 (meaning, it's not a vector but the origin), a division by zero occurs and the universe goes through a second big bang, except in reverse polarity and then back. As a result, humanity is safe but Godot will print an error. Remember! Vector(0,0) can't be normalized! No, Unity can't normalize it either, so don't switch back engines yet.

Of course, Vector2 and Vector3 already provide a method to do this:

a = a.normalized()

Dot Product

OK, the dot product is the most important part of vector math. Without the dot product, Quake would have never been made. This is the most important section of the tutorial, so make sure to grasp it properly. Most people trying to understand vector math give up here because, despite how simple it is, they can't make head or tails from it. Why? Here's why, it's because..

The dot product takes two vectors and returns a scalar:

var s = a.x*b.x + a.y*b.y

Yes, pretty much that. Multiply x from vector a by x from vector b. Do the same with y and add it together. In 3D it's pretty much the same:

var s = a.x*b.x + a.y*b.y + a.z*b.z

I know, it's totally meaningless! you can even do it with a built-in function:

var s = a.dot(b)

This is where despair begins and books and tutorials show you this formula:

And you realize it's time to give up making 3D games or complex 2D games. How can something so simple be so complex?. Someone else will have to make the next Zelda or Call of Duty. Top down RPGs don't look so bad after all. Yeah I hear someone did pretty will with one of those on Steam..

So this is your moment, this is your time to shine. DO NOT GIVE UP! At this point, this tutorial will take a sharp turn and focus on what makes the dot product useful. This is, why it is useful. We will focus one by one in the use cases for the dot product, with real-life applications. No more formulas that don't make any sense. Formulas will make sense once you learn why do they exist for.

Siding

The first useful and most important property of the dot product is to check what side stuff is looking at. Let's imagine we have any two vectors, a and b. Any direction or magnitude (neither origin). Does not matter what they are, but let's imagine we compute the dot product between them.

var s = a.dot(b)

The operation will return a single floating point number (but since we are in vector world, we call them scalar, will keep using that term from now on). This number will tell us the following:

If the number is greater than zero, both are looking towards the same direction (the angle between them is < 90° degrees).
If the number is less than zero, both are looking towards opposite direction (the angle between them is > 90° degrees).
If the number is zero, vectors are shaped in L (the angle between them is 90° degrees).

So let's think of a real use-case scenario. Imagine Snake is going through a forest, and then there is an enemy nearby. How can we quickly tell if the enemy has seen discovered Snake? In order to discover him, the enemy must be able to see Snake. Let's say, then that:

Snake is in position A.
The enemy is in position B.
The enemy is facing towards direction vector F.

So, let's create a new vector BA that goes from the guard (B) to Snake (A), by subtracting the two:

var BA = A-B

Ideally, if the guard was looking straight towards snake, to make eye to eye contact, it would do it in the same direction as vector BA.

If the dot product between F and BA is greater than 0, then Snake will be discovered. This happens because we will be able to tell that the guard is facing towards him:

if ( BA.dot(F) > 0 ):
    print("!")

Seems Snake is safe so far.

Siding with Normal Vectors

Ok, so now we know that dot product between two vectors will let us know if they are looking towards the same side, opposite sides or are just perpendicular to each other.

This works the same with all vectors, no matter the magnitude so normal vectors are not the exception. However, using the same property with normal vectors yields an even more interesting result, as an extra property is added:

If both vectors are facing towards the exact same direction (parallel to each other, angle between them is 0°), the resulting scalar is 1.
If both vectors are facing towards the exact opposite direction (parallel to each other, but angle between them is 180°), the resulting scalar is -1.

This means that dot product between normal vectors is always between the range of 1 and -1. So Again..

If their angle is 0° dot product is 1.
If their angle is 90°, then dot product is 0.
If their angle is 180°, then dot product is -1.

Uh.. this is oddly familiar.. seen this before.. where?

Let's take two normal vectors. The first one is pointing up, the second too but we will rotate it all the way from up (0°) to down (180° degrees)..

..while plotting the resulting scalar!

Aha! It all makes sense now, this is a Cosine function!

We can say that, then, as a rule..

The dot product between two normal vectors is the cosine of the angle between those two vectors. So, to obtain the angle between two vectors, we must do:

var angle_in_radians = acos( a.dot(b) )

What is this useful for? Well obtaining the angle directly is probably not as useful, but just being able to tell the angle is useful for reference. One example is in the Kinematic Character demo, when the character moves in a certain direction then we hit an object. How to tell if what we hit is the floor? By comparing the normal of the collision point with a previously computed angle.

The beauty of this is that the same code works exactly the same and without modification in 3D. Vector math is, in a great deal, dimemsion-amount-independent, so adding or removing an axis only adds very little complexity.

Planes

The dot product has another interesting property with normal vectors. Imagine that perpendicular to that vector (and through the origin) passes a plane. Planes divide the entire space into positive (over the plane) and negative (under the plane), and (contrary to popular belief) you can also use their math in 2D:

It's as simple as it looks. The plane passes by the origin and the surface of it is perpendicular to the normal vector. The side towards the vector points to is the positive half-space, while the other side is the negative half-space. In 3D this is exactly the same, except that the plane is an infinite surface (imagine an infinite, flat sheet of paper that you can orient and is pinned to the origin) instead of a line.

Distance to Plane

Now that it's clear what a plane is, let's go back to the dot product. The dot product between a normal vector and any point in space (yes, this time we do dot product between vector and position), returns the distance from the point to the plane:

var distance = normal.dot(point)

But not just the absolute distance, if the point is in the negative half space the distance will be negative, too:

This allows us to tell which side of the plane a point is.

Away from the Origin

I know what you are thinking! So far this is nice, but real planes are everywhere in space, not only passing through the origin. You want real plane action and you want it now.

Remember that planes not only split space in two, but they also have polarity. This means that it is possible to have perfectly overlapping planes, but their negative and positive half-spaces are swapped.

With this in mind, let's describe a full plane as a normal vector N and a distance from the origin scalar D. Thus, our plane is represented by N and D. For example:

For 3D math, Godot provides a Plane built-in type that handles this.

Basically, N and D can represent any plane in space, be it for 2D or 3D (depending on the amount of dimensions of N) and the math is the same for both. It's the same as before, but D id the distance from the origin to the plane, travelling in N direction. As an example, imagine you want to reach a point in the plane, you will just do:

var point_in_plane = N*D

This will stretch (resize) the normal vector and make it touch the plane. This math might seem confusing, but it's actually much simpler than it seems. If we want to tell, again, the distance from the point to the plane, we do the same but adjusing for distance:

var distance = N.dot(point) - D

This will, again, return either a positive or negative distance.

Flipping the polarity of the plane is also very simple, just negate both N and D. this will result in a plane in the same position, but with inverted negative and positive half spaces:

N = -N
D = -D

Of course, Godot implements this operator in Plane, so doing:

var inverted_plane = -plane

Will work as expected.

So, remember, a plane is just that and it's main practical use is calculating the distance to it. So, why is it useful to calculate the distance from a point to a plane? It's extremely useful! Let's see some simple examples..

Constructing a Plane

Some Examples of Planes

Here is a simple example of what planes are useful for. Imagine you have a convex polygon. For example, a rectangle, a trapezoid, a triangle, or just any polygon where faces that don't bend inwards.

For every segment of the polygon, we compute the plane that passes by that segment. Once we have the list of planes, we can do neat things, for example checking if a point is inside the polygon.

We go through all planes, if we can find a plane where the distance to the point is positive, then the point is outside the polygon. If we can't, then the point is inside.

Code should be something like this:

var inside=true
for p in planes:
   #check if distance to plane is positive
   if ( N.dot(point) - D > 0): 
       inside=false
       break # with one that fails, it's enough

Pretty cool, huh? But this gets much better! With a little more effort, similar logic will let us know when two convex polygons are overlapping too. This is called the Separating Axis Theorem (or SAT) and most physics engines use this to detect collision.

The idea is really simple! With a point, just checking if a plane returns a positive distance is enough to tell if the point is outside. With another polygon, we must find a plane where all the other polygon points return a positive distance to it. This check is performed with the planes of A against the points of B, and then with the planes of B against the points of A: