LÖVE (Love2D) Core
Build and debug a LÖVE game. New code targets LÖVE 11.5, the current stable release; 12.0 is unreleased and changes APIs, so do not copy 12.0 examples into an 11.x game.
When to use
- Starting a LÖVE game, or fixing its loop, timing, input, drawing, scaling, saving or screen flow.
- Any folder with
main.luacallinglove.*, aconf.lua, or a.lovearchive.
When not to use: Defold (also Lua, but game.project and .script files); physics
joints, shaders and networking beyond pointers; portable design owned by related skills.
Workflow
- Read
conf.luafirst.t.versionnames the target LÖVE version andt.identitythe save folder. Keep the project's version; ask before porting between 0.10, 11 and 12. - Load once, draw often. Create images, fonts, canvases and sounds in
love.load(or a loader), never insidelove.draworlove.update. - Simulate in steps. Scale motion by
dt; for physics, collisions or replays use the fixed-step accumulator below. - Wrap world drawing in
push/popand draw the HUD afterpop, in screen space. - Verify. Add the
--framescheck below and run it under a timeout; read the output and open the screenshot in the save directory. Report what you ran. Input feel and sound need a person: ask the user to play briefly and report speed, controls and audio.
Pattern: conf.lua with an error-exit hook
function love.conf(t)
t.version = "11.5" -- warns when run on another LÖVE version
t.identity = "my-game" -- save folder name; set it before the first release
t.window.width, t.window.height = 960, 540
end
-- Under --frames, print errors and exit 1 instead of showing the blue error screen.
-- conf.lua runs before main.lua, so this also catches syntax errors in main.lua.
if arg and table.concat(arg, " "):find("--frames", 1, true) then
function love.errorhandler(msg)
print("ERROR: " .. tostring(msg) .. debug.traceback("", 2))
return function() return 1 end
end
endPattern: fixed step and a scripted run
local STEP = 1 / 60
local acc = 0
local check = { frames = nil, shot = nil, count = 0 }
local player
function love.load(args) -- args: command-line arguments after the game folder
for i, a in ipairs(args) do
if a == "--frames" then check.frames = tonumber(args[i + 1]) end
if a == "--shot" then check.shot = args[i + 1] end
end
love.graphics.setDefaultFilter("nearest", "nearest") -- before any newImage/newCanvas
player = { x = 100, y = 100, speed = 120 } -- pixels per second
end
local function step(dt)
local dx = (love.keyboard.isDown("right") and 1 or 0)
- (love.keyboard.isDown("left") and 1 or 0)
player.x = player.x + dx * player.speed * dt
end
function love.update(dt)
acc = acc + math.min(dt, 0.25) -- clamp stalls so the loop cannot spiral
while acc >= STEP do
step(STEP)
acc = acc - STEP
end
check.count = check.count + 1
if check.frames and check.count == check.frames and check.shot then
love.graphics.captureScreenshot(check.shot) -- saved in the save directory
elseif check.frames and check.count > check.frames then
print("RUN OK frames=" .. check.frames .. " save=" .. love.filesystem.getSaveDirectory())
love.event.quit(0)
end
endUse love.keypressed(key, scancode, isrepeat) for one-off actions and
love.keyboard.isDown inside step for held movement.
Pattern: pixel-art canvas and camera
local W, H = 320, 180
local canvas -- create in love.load, after setDefaultFilter
function love.draw()
love.graphics.setCanvas(canvas)
love.graphics.clear(0.1, 0.1, 0.12)
love.graphics.push()
love.graphics.translate(-math.floor(cam.x), -math.floor(cam.y)) -- whole pixels
drawWorld()
love.graphics.pop() -- every push needs a pop, even on an early return
drawHud() -- screen space, after pop
love.graphics.setCanvas()
local w, h = love.graphics.getDimensions()
local s = math.max(1, math.floor(math.min(w / W, h / H))) -- integer scale only
love.graphics.draw(canvas, math.floor((w - W * s) / 2), math.floor((h - H * s) / 2), 0, s, s)
endSave with love.filesystem.write("save.lua", text) and read back with
love.filesystem.read or love.filesystem.load; files land in the save directory.
The check to run
love --version
timeout 30 love . --frames 120 --shot frame.png; echo "exit=$?"Expect RUN OK and exit 0; exit 1 prints the Lua error and traceback; exit 124 means the
game hung or the error hook is missing. The PNG is in the printed save directory, not the
project folder. On a Linux machine without a display, run xvfb-run -a love . …; if OpenAL
cannot open a sound device there, point ALSA_CONFIG_PATH at a file containing
pcm.!default { type null }.
Gotchas
- Pixel art looks blurry → images default to linear filtering. Call
love.graphics.setDefaultFilter("nearest", "nearest")before creating images, fonts or canvases (earlier objects keeplinear), draw to a low-resolution canvas, scale it by a whole number, and round camera offsets. Maximum stack depth reached (more pushes than pops?)→ apushwithout a matchingpop, often skipped by an earlyreturninlove.draw. The stack survives across frames, so the error appears a few frames later.Minimum stack depth reachedis the reverse.- Save file missing from the project folder →
love.filesystem.writeonly writes to the save directory (love.filesystem.getSaveDirectory(), named byt.identity; on Linux~/.local/share/love/<identity>). The game folder is read-only. Changingt.identityafter release orphans players' saves. - A module's state resets or is duplicated → it was required with two spellings.
require("screens.menu")andrequire("screens/menu")load two separate copies. Always use dotted paths from the game root. - Same "random" level every run → LuaJIT's
math.randomis not seeded at startup, whilelove.math.randomis. Uselove.math.random(orlove.math.newRandomGenerator(seed)for replayable runs). - Speed changes with frame rate, or objects tunnel after a stall → scale by
dt, clampdt, and step physics and collisions at a fixed rate. - The game freezes on the blue error screen in a scripted run → the default error
handler waits for the user. Use the
conf.luahook above so errors print and exit 1. - Colours come out white or fully opaque → 11.x colours are 0–1.
setColor(128, 234, 255)draws white; uselove.math.colorFromBytes(128, 234, 255)for byte values. - Everything is tinted after one
setColor→ colour is global state. Reset withlove.graphics.setColor(1, 1, 1)before drawing images and text. love.confhas no effect → it must be inconf.lua, which runs beforemain.lua.- Holding a key fires
love.keypressedonce → key repeat is off by default.love.keyboard.setKeyRepeat(true)enables it; repeats arrive withisrepeat == true. - Memory climbs and frames slow down →
newFont,newImageornewCanvasis called every frame. Create them once and reuse them.
References
- Read
references/state-stack.mdwhen the game needs menus, pause overlays or several screens: a complete push/pop screen manager with delegated callbacks and example screens.
Related skills
save-systems— save formats, slots and migration;input-systems— rebinding and gamepads.defold-core— the other Lua engine in this catalog;pygame-core— the same loop in Python.
Version notes
Last verified: 2026-11-11.
- LÖVE 11.5 (2023-12-03) is the latest stable release; 12.0 has no stable release yet.
- The patterns, the check commands and the behaviour in Gotchas (filters,
requirespellings, seeding, push/pop errors across frames, save directory, error hook,colorFromBytes, key repeat) were run with the official LÖVE 11.5 x86_64 AppImage under Xvfb. Taken from the wiki only:t.window.vsyncis a number since 11.0 andlove.math.colorFromBytesarrived in 11.3. - Sources: LÖVE releases,
love2d.org, 11.5
love.runsource, love.filesystem, love.graphics.setDefaultFilter, Config Files.