LÖVE for Newbies

You will need ruby to be installed for rendering the book, and node, npm and luajit for the livecode examples with punchdrunk currently.

Make sure you have bundler installed:

then instal the dependencies:

To render the ebook and pdf you can run render.sh:

but the preferred way to work on the project is by running Guard:

this will automatically render the HTML ebook as you change the files. You can use any LiveReload extension in a browser to have it automaically refresh as you modify the book.

Whenever a significant portion of the book has changed and is ready for release, stage the files on master and run release.sh. Make sure that book/code is at the correct revision and staged before releasing.

Thank you for helping create this :)

The spaceship is the main thing the player can control in our game. The player can use two keys to accelerate or decelerate in the direction the ship is currently facing. He can also turn the spaceship with two other keys. Lastly the player can press a button to fire a shot.

When the spaceships leaves the screen on one side, it will enter from the opposite side, keeping it’s velocity.

We can see that the spaceship needs to have a position, velocity and rotation. In World 1-5 we will see that the actual way of saving the information we use differs, but we could as well do with this "definition".

Asteroids move in a straight line, also wrapping around the Screen in the same way the spaceship does. They larger an asteroid is, the slower it should move. Therefore all we need to know about every asteroid is his position, size and his rotation.

Whenever an asteroid is hit, we split it into two smaller ones, unless it is already the smallest possible size. In that case we remove it altogether.

Bullets travel along a straight path, much like asteroids. However they are removed from the game as soon as they hit an asteroid or leave the screen.

All bullets share the same speed, we only need to know the bullet’s position and rotation.

So, what makes a LÖVE Project?
At core a LÖVE Project is just a folder containing everything needed to make the game; Code, Images, Sound and Video files and everything else you might need.

In the last Level we learned that our main code goes in a file called main.lua and that we are supposed to define Callback Routines there.

A Callback Routine is nothing but a function with a specific name the LÖVE framework knows. For example, whenever a key is pressed, LÖVE will attempt to call a function called love.keypressed. If you have not written than function (yet), the keypress will be ignored, but if you choose to write one, you can do something in reaction to that Event.

One of the most important Callbacks is love.draw. As the name implies, this is where any drawing to the screen should take place.

Inside this function we can now draw everything we want the player to be able to see. To get started, let’s draw a circle. To draw a circle, we will use the function love.graphics.circle. Go and see what you can find on the wiki page now!

As you can see, love.graphics.circle accepts five parameters:

So, to draw a filled 30px circle at (100, 100) and then a stroked one 20px further down, this is what we need to do:

Quite similarly, we can also draw rectangles using love.graphics.rectangle. The six parameters are:

Another function you will use in probably every game is love.graphics.setColor. It accepts three numbers in the range of 0 to 255, specifying the intensity of red, green and blue respectively. A fourth value, used as alpha (transparency) can optionally be supplied.

The last drawing function for now is love.graphics.line. You can pass it four values, each representing the x and y values of a point.

Putting it all together, we can draw a little stickman:

LÖVE provides a lot more drawing operations and related functions, but for now we will stick with those above. You can find the whole list on the wiki.

As we are working towards an Asteroids clone, let’s start out with a spaceship. Before we can make a spaceship move, we need a spaceship though:

I know, I know, that doesn’t look very aerodynamic. But I’ll tell you what, there’s no air resistance in space anyway - at least there’s a line to indicate which direction we are facing.

Alright, so how do we make this thing move? We will obviously need a variable to keep track of it’s current position. In fact we will be using two, one for each coordinate we are going to simulate the ship on:

Now we only need to change the values of x and y and the ship will follow. We could for example make them always point to the current mouse position:

Wait, what happened here? First of all, I introduced a new LÖVE callback: love.update. As the name implies, this is where we update the current game state. love.update is where things happen; This is where the player moves, the enemies shoot and the lighting is calculated. One thing you might notice immediately is that unlike love.draw, love.update receives a parameter: dt.

dt is short for deltatime (time difference). dt is always the time (in seconds) since the last time love.update was called. In this small example dt is not used, but it is very useful, as we will see later on.

Secondly, another LÖVE function has come into play: love.mouse.getPosition. It should again be rather obvious what this function is doing for us; it returns the mouse’s current position along the x and y axis (in pixels).

Alright, now things are moving, but in our game we don’t want the ship to be controlled by the mouse. Also, with the current code players with a faster mouse would have an advantage, they could move around much more quickly. Instead, let’s introduce a fixed speed for our spaceship, and add keyboard controls:

Great, let’s go through the changes: You can immediately see that x and y have disappeared, instead there is now a table called player. player stores the position under the keys "x" and "y", so nothing has really changed except the varible names are longer, but I have done this so our code stays readable as we progress; As we add enemies and bullets we will need to keep track of a lot more `x`s and `y`s.

As we can see, I have also added a new variable called SPEED. SPEED is never changed in the code, so I could’ve also replaced every occurence further down with it’s value, 300 right away. However keeping it at the top like this makes it easy to modify the speed, also I cannot forget to modify it in all the places should I change it some time. SPEED is uppercased because I use this style to name constant values, but this is just a stylistic choice by me.

Now on to the actual keyboard code! There is another new LÖVE function used here: love.keyboard.isDown. Once again the name should make the purpose of the function very clear, you should start to see a pattern here. love.keyboard.isDown checks if the key given is down. In LÖVE keys are identified by a string, in this example we are using "up", "down" etc., but there are many more. You can view a table of all the keys on the wiki: KeyConstant.

Using if and love.keyboard.isDown we add or substract SPEED * dt from the fitting coordinates, when the left key is pressed, we substract from player.x; when down is pressed we add to the y-coordinate.

Now, why do we multiply SPEED with dt? As I said above, the time step between each love.update execution may vary; for example a scene that has to draw a lot of enemies might take longer do draw than one that just features a few. Other factors like the power of the graphics card and processor or how busy the computer is with other things might also impact the updaterate.

It is important that we care about this, a game that runs twice as fast on better hardware is unacceptable. By multiplying with dt we can scale the speed by the time that we are actually simulating.

Because dt is measured in seconds, it also makes specifying movement speeds etc. very convenient, SPEED is now measured in pixels per second. This gives it a workable size and something you can think about; if we had not used dt we would have to deal with tiny values in pixels per frame.

Imagine we are working on a Galaga-type fixed shooter. Every frame we have to simulate and draw all the enemies and the player. There are multiple types of enemies with different behaviours and graphics, but they all need to be drawn in love.draw and updated in love.update. We also need to handle all the bullets flying around.

The simples way to handle all of this is just storing all these things in a list, then iterate over it in the two callbacks:

So far, so obvious. But what happens when we need to remove things? Whenever the player shoots an enemy down, we will have to remove it from objects so we don’t use up all of the PCs memory in a matter of minutes. The problem with using table.remove() is that it will update all the indices, so that we can continue iterating over the list (which is a good thing), but because of this we will skip the next enemy, which is inacceptable.

The simplest solution iterating in reverse:

This is a good start, but let’s take it a step further.

Sets, in mathematics, are a like a bag of objects; the objects don’t have any order, nor names or labels associated with them. In Lua Sets are usually implemented as tables where key and value are the same:

You might ask what advantage this might have over a simple list. After all we lost the ability to order the objects! One advantage of handling the list like this is that we now only have to care about the objects themselves; whether we change, delete or add objects, we never have to know, let alone search for, the index of that object. This means that we can now delete objects from basically everywhere in code (though that generally may hurt your code structure).

Another cool thing about this way of handling Sets is that we can actually add labels to some objects in the table if we want to. For example there is no need to treat the player as an exception anymore:

As always, this concept is explained here on a very small scale. In an actual game project you would usually need multiple object pools for different things or layers. Still, Sets and Object Pools are going to be a building block of more or less every game you will ever encounter, so these small tricks might still be valuable information to you.