How to use
- Copy the installation command and review the source package before installing it in your own agent environment.
- Check the source document for required tools, credentials and supported hosts.
- Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/gamedev-skills/awesome-gamedev-agent-skills --skill love2d-coreBefore you start
- Installation does not include a model subscription, API allowance or permission to access your files.
- Repository stars and installation counts describe activity, not an independent quality or security test.
Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.
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.lua` first.
t.versionnames the target LÖVE version andt.identity
the 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 inside love.draw or love.update.
- Simulate in steps. Scale motion by
dt; for physics, collisions or replays use the
fixed-step accumulator below.
- Wrap world drawing in `push`/`pop` and draw the HUD after
pop, 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 keep linear), draw to a low-resolution canvas, scale it by a whole number, and round camera offsets.
- `Maximum stack depth reached (more pushes than pops?)` → a
pushwithout a matching
pop, often skipped by an early return in love.draw. The stack survives across frames, so the error appears a few frames later. Minimum stack depth reached is the reverse.
- Save file missing from the project folder →
love.filesystem.writeonly writes to the
save directory (love.filesystem.getSaveDirectory(), named by t.identity; on Linux ~/.local/share/love/<identity>). The game folder is read-only. Changing t.identity after release orphans players' saves.
- A module's state resets or is duplicated → it was required with two spellings.
require("screens.menu") and require("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, while
love.math.random is. Use love.math.random (or love.math.newRandomGenerator(seed) for replayable runs).
- Speed changes with frame rate, or objects tunnel after a stall → scale by
dt, clamp
dt, 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.lua hook 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; use love.math.colorFromBytes(128, 234, 255)` for byte values.
- Everything is tinted after one `setColor` → colour is global state. Reset with
love.graphics.setColor(1, 1, 1) before drawing images and text.
- `love.conf` has no effect → it must be in
conf.lua, which runs beforemain.lua. - Holding a key fires `love.keypressed` once → key repeat is off by default.
love.keyboard.setKeyRepeat(true) enables it; repeats arrive with isrepeat == 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,
require
spellings, 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.vsync is a number since 11.0 and love.math.colorFromBytes arrived in 11.3.
- Sources: LÖVE releases,
love2d.org, 11.5 `love.run` source, love.filesystem, love.graphics.setDefaultFilter, Config Files.