Setting Up Love2D #

Installing #

Love2D has a standard installer for Windows, as well as a zipped version. You can choose whichever you prefer, things will basically work the same either way.

• Love2D 11.4 Windows 64-bit Installer
• Love2D 11.4 Windows 64-bit Zipped

The Windows installer will install to C:\Program Files\LOVE by default.

Alternatively, you can grab the zipped version and unpack the files into C:\learn-lua\bin\love\ if you want to keep everything related to this tutorial in one place.

You can also find downloads for 32-bit Windows, MacOS or Linux from the Love2D homepage.

This tutorial was written for Love2D 11.4

It will likely continue to work with any 11.x version, but may not work with newer major versions. There are often breaking changes between major versions, which can cause code written for a different version to work incorrectly, or fail to run at all.

If you’re reading this in The Future and need to find an installer for Love2D 11.4, you should be able to find it on the Love2D github Releases page.

Running Love2D #

If you find and run the program love.exe from the directory you installed it to (or by running LOVE from the Start menu, if you used the Installer), you should see this screen:

This is the “no game” screen for version 11, which Love2D will display when you haven’t loaded any game. The engine by itself has no user interface to load games or do anything else, so in order to get started we’ll need to create a game script to be loaded into the engine.

Hello Love2D #

Instead of a single .lua script, each Love2D game is actually a directory containing at least one, but usually many files. There may be config files, Lua scripts, images, music and sound files, and so on.

To try this out, create a new directory C:\learn-lua\source\hello-love2d.

Create a new text file in your editor and save it as run.bat inside the hello-love2d directory.

If you used the Windows Installer, put this line into run.bat:

@"C:\Program Files\LOVE\love.exe" --console .

Otherwise, if you unpacked the zipped version of Love2D into the C:\learn-lua\bin\love directory, use this instead:

@..\..\bin\love\love.exe --console .

Hopefully the point is clear: just make sure that the path to love.exe is correct, wherever it happens to be.

The --console command line option tells Love2D to output debugging information to the text console, which will allow us to see debug output printed from the game.

And the dot . refers to the current directory (the same directory the run.bat file is contained in). Love2D will try and load the current directory as a Love2D game. You could also pass in the full path instead: C:\learn-lua\source\hello-love2d, but that would get annoying if you moved or renamed the directory containing the game.

If you try and run run.bat now, you should see something like this:

This slightly misleading error message includes:

Make sure main.lua is at the top level of the zip.

In addition to loading a game from a directory, Love2D can also load games which have been packaged into zip files for distribution, which is where the wording in the error message is coming from.

The engine is looking for the file main.lua in the current directory (the . in the command line) and not finding it, so let’s create one.

Create a new empty text file and save it as main.lua inside the hello-love2d directory.

Now when we launch run.bat, you should see a blank black screen, titled Untitled:

This is progress! Our game is actually loading now, but we’re not drawing anything to the screen.

To start with, let’s change the background colour. Add this function to main.lua:

function love.draw()
    love.graphics.clear(0.545, 0.439, 0.678)
end

Save the file and launch the game again… you should see this nice shade of amethyst:

You may have noticed that we aren’t calling love.draw() anywhere, and yet the screen is still being cleared with the colour values we specified.

When using plain Lua, we wrote our own main loop which controlled the main flow of the game. With Love2D however, the game main loop is built in to the engine, and we add functionality by creating callbacks, functions with specific names that the Love2D engine calls at specific times.

The Love2D game loop is constantly running, and each time it loops, each frame, it calls our callback love.draw() to do the actual work of drawing the contents of the game onto the screen.

Printing The Mouse Position #

Before we move on, let’s get some simple output on the screen, more than just a flat colour.

function love.draw()
    love.graphics.clear(0.545, 0.439, 0.678)
    
    local x, y = love.mouse.getPosition()
    local str = string.format("mouse pos: %i, %i", x, y)
    print(str)
end

Calling the function love.mouse.getPosition() returns two values, the X and Y positions of the mouse relative to the top left corner of the game window, which we store in the variables x and y.

Then we format a string and print it out to… where exactly?

Calling print() like we’ve been doing in Lua programs until this point will actually output the string to the debug console, which we enabled with --console when we launched love.exe. You should see a stream of messages in the console window which is launched behind the game window:

Move your mouse cursor around above the game window, and you should see the X and Y values change to reflect the position of the each time the Love2D engine calls our love.draw() function, once per frame.

This is an excellent way to output debugging information for our own use, but to actually make a game we’ll want things to show up on the game screen.

We can draw text on the screen using love.graphics.print(), like so:

function love.draw()
    love.graphics.clear(0.545, 0.439, 0.678)
    
    local x, y = love.mouse.getPosition()
    local str = string.format("mouse pos: %i, %i", x, y)
    print(str)
    love.graphics.print(str)
end

Which will draw the text with a default font, default colour (white), at the default coordinates 0, 0 (top left corner):

We can make the text follow the mouse cursor, by passing in the coordinates of the cursor as the coordinates to draw the text…

function love.draw()
    love.graphics.clear(0.545, 0.439, 0.678)
    
    local x, y = love.mouse.getPosition()
    local str = string.format("mouse pos: %i, %i", x, y)
    print(str)
    love.graphics.print(str, x, y)
end

And now the text will be drawn at the same x, y coordinates as the cursor:

Move the cursor around to the different corners of the window and observe the coordinates that are shown. You should see that the top left corner is 0, 0, the top right corner is 800, 0, bottom right is 800, 600, and bottom left is 0, 600. These coordinates reflect the default window size of 800 x 600.

It may be hard to see the coordinates exactly at the right and bottom of the screen, as the text will be printed past the edge, but it should still be visible in the debug console.

All Set #

Alright, now that we can set up a basic Love2D script, print out some debugging information, and draw a few things to the screen, let’s get back to making games!