Basic LÖVE concepts

LÖVE's homepage is:

The current LÖVE version at the time this document was last updated is 0.10.2.

LÖVE uses LuaJIT 2.0. You don't need to install this or any other Lua version to use LÖVE.

What LÖVE can run on

LÖVE projects can be run on Windows, Linux, Mac OS, Android, iOS and (unofficially) web browsers.

What LÖVE provides

LÖVE provides a way of displaying graphics, playing sound, and getting user input, among other things.

LÖVE doesn't provide things which can be written in Lua code, unless it would be too slow.

For example, LÖVE doesn't provide anything specifically for animations, because animations can be made with Lua code that uses what LÖVE provides.

However, LÖVE does provide a particle system and a physics system, because they are significantly faster than if they were made with Lua code.

Running LÖVE projects

A LÖVE project is a directory or zip file containing a main.lua file and any other files used.

A project can be run via the command line by love.exe path_to_love_project on Windows, love path_to_love_project on Linux, or open -n -a love path_to_love_project on Mac OS.

Or, it can be run by dragging and dropping the LÖVE project on to love.exe on Windows or on Mac OS.

Zip files with the extension .love will be opened automatically by LÖVE. Files with the extension .love can be renamed to have the extension .zip and unzipped.

For more information on running LÖVE projects, see this page:


LÖVE projects can be made into .exe files for Windows, .app files for Mac OS, and so on. For more information, see this page:

Control flow

When a LÖVE project is run, LÖVE runs conf.lua and the function love.conf (if they exist), then runs main.lua, then runs the function, then closes.

A default function is used if it isn't overwritten by the project's code, and this default is what calls the rest of the callbacks mentioned below.

For more information on, see this page:

main.lua is intended for the main code.


Control flow in LÖVE uses callbacks.

LÖVE's callbacks are functions which you create and LÖVE runs at specific times.

For example, love.load is run once LÖVE has loaded.

Every frame, love.update is run, which is intended for updating the state of the program, then love.draw is run, which is intended for drawing to the screen.

love.update is given the time since it was last run in seconds as a parameter.

love.keypressed is run when a key on the keyboard is pressed, and is given which key it was as a parameter.

For example:

function love.load()
    randomNumber = love.math.random()
    totalTime = 0
    x = 15

function love.update(dt)
    totalTime = totalTime + dt
    x = x + (10 * dt)

function love.draw()'The random number is '..randomNumber, 15, 15)'The program has been running for '..totalTime..' seconds', 15, 30)'This text is moving right at 10 pixels per second', x, 45)

function love.keypressed(key)
    if key == 'r' then
        randomNumber = love.math.random()
    elseif key == 'x' then
        x = 15

LÖVE has around 35 callbacks.

For information on all of the callbacks, see this page:


love.conf is a callback defined in conf.lua which is called before modules are loaded and before main.lua is run.

It can set the initial window properties and disable modules among other things.

For more information on configuration, see this page:


LÖVE provides functions which you can call to do things. is an example of a function, so is love.math.random.

LÖVE has around 255 functions.

For information on all of the functions, see each module's page:

Convenience functions

Some functions provide a quicker way of doing something which could be done in another way.

For example, this code creates a new Font with and sets the internal state to use this font with

function love.load()'font.ttf', 20))
end is a convenience function which does the same thing.

function love.load()'font.ttf', 20)

Internal state

LÖVE has state in a running program which affects the behavior of the program and can be changed/retrieved by functions. Functions for changing state often start with set and functions for retrieving state often start with get.

For example, changes the state of the drawing color, and retrieves it.

function love.draw(), 255, 255)
    red, green, blue =
        'The color state currently has a red value of '
        ' and a green value of '
        ' and a blue value of ',
        15, 15
    ), 51, 133)
    red, green, blue =
        'The color state currently has a red value of '
        ' and a green value of '
        ' and a blue value of ',
        15, 30


Objects are returned by "constructor" functions, and can be used by other functions to do things. Constructor functions generally start with new.

For example, Image objects are returned by They can be drawn to the screen with

function love.load()
    image1 ='image1.png')
    image2 ='image2.png')

function love.draw(), 15, 15), 15, 100)

LÖVE has around 47 object types, 22 of which are in the physics module.

For information on all of the objects, see each module's page:

Object state and functions

Objects have their own individual state.

Objects have functions which change or retrieve the object's state, or have external effects based on the object's state.

For example, Image:setFilter changes the way an Image looks when it is drawn scaled, and Image:getFilter retrieves it.

function love.load()
    image1 ='image1.png')

function love.draw()
    image1:setFilter('linear')'The image filter is '..image1:getFilter(), 15, 15), 15, 35, 0, 2)

    image1:setFilter('nearest')'The image filter is '..image1:getFilter(), 15, 115), 15, 135, 0, 2)

LÖVE has around 518 object functions, 232 of which are in the physics module.


LÖVE's internal code is divided into modules.

Modules can be disabled in love.conf.

LÖVE's functions are within tables named after the module they are in. For example, is in the graphics module.

LÖVE has around 17 modules.