LÖVE is a Lua-based 2D engine / framework which is open sourced and freely available for home and commercial projects.
In other words, we can make and release our work with Love!
The objective of this tutorial is to introduce you to the basic Love concepts of creating a window and the functional basics of the framework.
You will hopefully start to see that Love does a lot of the heavy lifting for you, but gives you the freedom to accomplish the design you might be thinking of.
One day I’ll create a video showing how to setup LÖVE, but until then head over to love2d.org.
Before downloading anything, just take a quick look at this website. Notice how friendly, warm and welcoming the entire tone of the site is? LÖVE is designed from the ground up to be just as warm and welcoming to creators.
Okay, now notice how many platforms are supported. While it’s not “everywhere”, LÖVE provides support across all major platforms – you’re not “locked in” to any one of them.
This tutorial is written and created in both my Windows10 and MacOS environments.
Download the installer for your platform and run it.
Notes for Windows
Just accept all the installation default settings. Let LÖVE do its thang.
Notes for MacOS
The zip file you download will contain a
Love.appover to your
- In your home directory, open up either
.bashrc(or in my case
- Provided you put LOVE into your
Applications, you can add the following to make sure `Love` is in your system path: `export PATH=”/Applications/love.app/Contents/MacOS:$PATH”`
- Save and close the file
- Shutdown and restart any
Terminalconsole window you have open to get these changes
Testing and Running LÖVE
No matter the system, make sure to close and restart any open console / terminal windows to pick up the changes made by LÖVE to your path. This will let you run
Love from anywhere.
love --version and you should see something…
For another great test, just type
love by itself. You should see…
How super cute!
If you’ve been following along without issue, then I think it’s safe to make the assumption that your system is ready for LÖVE.
Running your first LÖVE game
All LÖVE games begin with a file called
main.lua (is it just me, or should the engine also accept something like
In any folder you want, create a file called
main.lua. Like I’ve previously stated, LÖVE takes care of a lot of the heavy lifting behind running your game. Your graphics and sound hardware (among others) is just “available” to you right away.
The core of LÖVE
There are 3 minimum functions that your game will need. Paste the following 3 into your
function love.load() end function love.update(dt) end function love.draw() end
Save the file and run it back in your console window with just
You should now just see…an empty black screen.
Yay? Actually it is Yay.
This is good reinforcement that Love is configured correctly on your system and that your
main.lua is being used properly.
At the heart of LÖVE is a function that you don’t have to really worry about. You just need to know that it’s there for you.
Upon starting up, LÖVE will execute a function called
function love.run() if love.math then love.math.setRandomSeed(os.time()) end if love.load then love.load(arg) end -- We don't want the first frame's dt to include time taken by love.load. if love.timer then love.timer.step() end local dt = 0 -- Main loop time. while true do -- Process events. if love.event then love.event.pump() for name, a,b,c,d,e,f in love.event.poll() do if name == "quit" then if not love.quit or not love.quit() then return a end end love.handlers[name](a,b,c,d,e,f) end end -- Update dt, as we'll be passing it to update if love.timer then love.timer.step() dt = love.timer.getDelta() end -- Call update and draw if love.update then love.update(dt) end -- will pass 0 if love.timer is disabled if love.graphics and love.graphics.isActive() then love.graphics.clear(love.graphics.getBackgroundColor()) love.graphics.origin() if love.draw then love.draw() end love.graphics.present() end if love.timer then love.timer.sleep(0.001) end end end
If a lot of this looks really strange to you, don’t worry about it. For now, it’s really not important and over time you will learn to understand what’s happening.
What you might notice is that from within
love.run the engine is calling
love.draw(). Tada! Magic!
So long as you have these 3 functions defined in your
main.lua, then they’ll be automagically run by LÖVE.
Each of these 3 have their core purpose –
- run only once during startup
- should be used to load all of your graphics, music and sound effects
- run every single “frame” of your game
- should be used to update the position of things in your game
- should be used to handle and process inputs from the keyboard, mouse and/or joystick
- should be used to play any music or sound
- run every single “frame” of your game
- should only be used to draw everything in your game
Adjusting the window of your heart
Before we wrap up this part of the series of LÖVE, let’s tackle a common need in any game – setting up our window “basics”. In other words, how to change the size of our window, how to give it a window title and how to start fullscreen or windowed.
In the same folder as your
main.lua, create a new file called
conf.lua. This is run by the LÖVE engine before anything else.
You can’t do anything here apart from setting up some configuration settings for your game, but that’s EXACTLY what we want to do!
In the file, you just need to define one single function
function love.conf(t) t.window.width = 1024 t.window.height = 768 end
So here we are adjusting the window size of our game. Play around with different window sizes here – don’t forget to save the file before running
love . to test it out.
When you’re finished, just leave it set to your favorite window size.
setting a window title
Setting a window title is now trivial within this function.
function love.conf(t) t.window.width = 1024 t.window.height = 768 t.window.title = "my first #love game" end
Save and run it again. Your application window should now be titled!
Starting in fullscreen mode
Running your game in a desktop window is best suited for development and testing. You might at some point want to release something — or you just want to run things in a fullscreen window.
This is also just as trivial to configure. Update
function love.conf(t) t.window.width = 1024 t.window.height = 768 t.window.title = "my first #love game" t.window.fullscreen = true t.window.fullscreentype = "desktop" end
Now when you save and run your game, you’re a “serious” game developer now — fullscreen!
Screenshot not posted here for hopefully obvious reasons…
That’s it for this tutorial!
Hopefully you’ve picked up a small tiny piece of the LÖVE engine. As we work and explore through more LÖVE, then you’ll start to piece together what is happening.