Love2D 11.x Development

Love2D 11.x (baseline: 11.1–11.5) with Lua. All code examples target Lua — not Fennel. This skill is for hobbyist developers; prefer vanilla Love2D first, community libraries as alternatives.

References

Project Structure

my-game/
├── conf.lua        -- window config, identity (runs before love.load)
├── main.lua        -- entry point; all callbacks defined here
└── assets/

conf.lua — configure the window and game identity before Love2D initializes:

function love.conf(t)
    t.identity = "my-game"          -- save directory name
    t.window.title = "My Game"
    t.window.width = 800
    t.window.height = 600
    t.window.resizable = false
end

main.lua — define the standard callbacks:

function love.load()
    -- one-time setup: load assets, initialize state
end

function love.update(dt)
    -- game logic; dt is seconds since last frame
end

function love.draw()
    -- rendering only; no state mutation here
end

Callback lifecycle order (per frame):

1. Event processing — love.keypressed, love.keyreleased, love.mousepressed, love.mousereleased, love.mousemoved fire here, before update
2. love.update(dt) — game logic, physics, timers
3. love.draw() — all rendering

love.run owns the main loop — you can override it for custom loop behavior (fixed timestep, etc.), but rarely need to.

Love2D Idioms

Graphics Stack

Use love.graphics.push() / love.graphics.pop() to isolate transforms. Transforms applied inside a push/pop block do not bleed out.

function love.draw()
    love.graphics.push()
        love.graphics.translate(player.x, player.y)
        love.graphics.rotate(player.angle)
        love.graphics.draw(player.sprite, -16, -16)  -- centered
    love.graphics.pop()
end

love.graphics.scale(sx, sy) scales from the current origin. Chain translate → rotate → scale in that order for predictable results.

Pixel Art

Set the default filter before loading any images:

function love.load()
    love.graphics.setDefaultFilter("nearest", "nearest")
    -- now load sprites; they'll use nearest-neighbor scaling
    player.sprite = love.graphics.newImage("assets/player.png")
end

Calling setDefaultFilter after images are loaded has no effect on already-loaded images.

Canvas (Off-Screen Rendering)

local canvas

function love.load()
    canvas = love.graphics.newCanvas(800, 600)
end

function love.draw()
    love.graphics.setCanvas(canvas)
        love.graphics.clear()
        -- draw scene to canvas
        love.graphics.draw(background)
    love.graphics.setCanvas()  -- restore to screen

    -- draw canvas to screen (apply post-processing shader here)
    love.graphics.draw(canvas, 0, 0)
end

Color Management

love.graphics.setColor(r, g, b, a) affects everything drawn after it. Values are 0–1. Always reset to white after drawing colored elements — forgetting this is the most common Love2D bug.

-- Draw a red health bar, then reset
love.graphics.setColor(1, 0, 0, 1)
love.graphics.rectangle("fill", 10, 10, hp_width, 20)
love.graphics.setColor(1, 1, 1, 1)  -- reset; sprites draw tinted otherwise
love.graphics.draw(sprite, x, y)

Drawing Primitives

love.graphics.draw(image, x, y)                    -- image at position
love.graphics.draw(image, x, y, r, sx, sy, ox, oy) -- with rotation, scale, origin
love.graphics.rectangle("fill", x, y, w, h)        -- filled rect
love.graphics.rectangle("line", x, y, w, h)        -- outline rect
love.graphics.print("text", x, y)                  -- text at position
love.graphics.printf("text", x, y, limit, "center") -- wrapped/aligned text

Shader Basics

For the full shader pipeline (uniforms, displacement, masking, reflections), see references/shaders.md.

Loading (inside love.load — shaders require an active graphics context):

local shader

function love.load()
    shader = love.graphics.newShader("shaders/effect.glsl")
    -- or inline:
    shader = love.graphics.newShader([[
        vec4 effect(vec4 color, Image tex, vec2 uv, vec2 screen) {
            return Texel(tex, uv) * color;
        }
    ]])
end

Applying:

love.graphics.setShader(shader)   -- enable
love.graphics.draw(image, 0, 0)
love.graphics.setShader()         -- reset to default

Sending uniforms:

-- Check before sending to avoid errors on unused/optimized-out uniforms
if shader:hasUniform("time") then
    shader:send("time", love.timer.getTime())
end

Love2D GLSL flavor — two differences from standard GLSL:

• Use Image instead of sampler2D for texture uniforms
• Use Texel(tex, uv) instead of texture2D(tex, uv) for sampling

Pattern Mapping (Quick Reference)

This skill takes precedence over game-patterns for Love2D implementation. For full Lua implementations, see references/love2d-pattern-mappings.md.

Common Pitfalls

Forgetting to reset color. After love.graphics.setColor(r, g, b, a), everything drawn afterward is tinted. Always call love.graphics.setColor(1, 1, 1, 1) after drawing colored elements.

Drawing outside push/pop. Transforms applied without a matching pop() bleed into subsequent draw calls. Wrap every entity's draw in push()/pop().

Loading resources in love.draw. love.graphics.newImage, love.graphics.newFont, etc. create new GPU objects every frame if called in love.draw. Load once in love.load, store in variables.

Calling setDefaultFilter after loading images. The filter must be set before any love.graphics.newImage calls. Put it as the first line of love.load.

Not using dt in love.update. Movement like x = x + speed is frame-rate-dependent. Always multiply by dt: x = x + speed * dt.