LÖVE (Love2D) Core
Set up and debug the foundation of a LÖVE game in Lua: the callback loop, frame-rate-
independent movement, input, and screen states. Targets LÖVE 11.5.
When to use
- Use when starting a LÖVE game, wiring up
main.lua/conf.lua, or fixing the core loop,
movement that runs at the wrong speed, input handling, or screen switching.
- Use when the workspace has
main.lua calling love.*, a conf.lua, or a .love file.
When not to use: Lua language questions unrelated to LÖVE; physics bodies/joints
(LÖVE uses Box2D via love.physics — a separate concern); shader code (love.graphics
GLSL is its own topic). For cross-engine save/load patterns, use save-systems.
Core workflow
- Confirm the entry points. A LÖVE game runs
main.lua; it should define
love.load() (one-time setup), love.update(dt) (state), and love.draw() (rendering).
Window/version setup goes in conf.lua (run before modules load).
- Pin the version. Set
t.version = "11.5" in conf.lua so LÖVE warns on mismatch.
- Drive all motion by
dt (delta time, in seconds) so speed is frame-rate independent.
- Handle input two ways: polled (
love.keyboard.isDown in update, for held keys) and
event (love.keypressed callback, for discrete presses).
- Manage screens (menu, game, pause) with a small state stack rather than a pile of
if flags — see Patterns and references/state-stack.md.
- Run and observe. Launch with
love . from the project folder; verify the window,
motion speed, and input on screen before assuming it works.
Patterns
1. main.lua skeleton (the callback loop + input)
-- main.lua — LÖVE calls these callbacks for you. Colors are 0–1 in LÖVE 11.x.
function love.load()
-- One-time setup. speed is in PIXELS PER SECOND, not per frame.
player = { x = 100, y = 100, size = 40, speed = 220 }
love.graphics.setBackgroundColor(0.1, 0.1, 0.12)
end
function love.update(dt)
-- Polled input: good for continuous movement while a key is held.
if love.keyboard.isDown("right") then player.x = player.x + player.speed * dt end
if love.keyboard.isDown("left") then player.x = player.x - player.speed * dt end
if love.keyboard.isDown("down") then player.y = player.y + player.speed * dt end
if love.keyboard.isDown("up") then player.y = player.y - player.speed * dt end
end
function love.draw()
love.graphics.setColor(0.2, 0.8, 1.0) -- tint ON
love.graphics.rectangle("fill", player.x, player.y, player.size, player.size)
love.graphics.setColor(1, 1, 1) -- reset tint before text/images
love.graphics.print("Arrow keys to move, Esc to quit", 10, 10)
end
function love.keypressed(key)
-- Event input: fires once per physical press. Use for menus, jumps, toggles.
if key == "escape" then love.event.quit() end
end
2. Frame-rate independence (the single most common bug)
-- RIGHT: scaled by dt → same real-world speed at 30 or 240 FPS.
player.x = player.x + player.speed * dt
-- WRONG: "pixels per frame" → moves twice as fast at double the frame rate.
player.x = player.x + player.speed
3. conf.lua (window + version; runs before main.lua)
-- conf.lua — must be its own file; love.conf will NOT run from main.lua.
function love.conf(t)
t.version = "11.5" -- the LÖVE version this game targets (string "X.Y")
t.window.title = "My LÖVE Game"
t.window.width = 800
t.window.height = 600
t.window.vsync = 1 -- number since 11.0: 1 = on, 0 = off, -1 = adaptive
t.window.resizable = false
t.modules.physics = false -- disable modules you don't use to trim startup/memory
end
4. Color is 0–1 in LÖVE 11.x (not 0–255)
-- LÖVE 11.x uses normalized floats. (Pre-11.0 code used 0–255 and will look wrong.)
love.graphics.setColor(1, 0, 0) -- opaque red
love.graphics.setColor(0.2, 0.8, 1.0, 0.5) -- translucent cyan (alpha 0.5)
-- Need to convert old byte values? Use the helper instead of dividing by hand:
love.graphics.setColor(love.math.colorFromBytes(128, 234, 255))
5. Screen states (brief — full manager in references)
-- A screen is a table with optional :update(dt), :draw(), :keypressed(key).
-- Keep the active screen on a stack so pause/menu overlays are trivial to pop.
local Stack = require("state_stack") -- see references/state-stack.md for the module
-- Call a method on the top screen only if it defines it (a menu may have no update).
local function forward(name, ...)
local screen = Stack.current()
if screen and screen[name] then screen[name](screen, ...) end
end
function love.load() Stack.push(require("screens.menu")) end
function love.update(dt) forward("update", dt) end
function love.draw() forward("draw") end
function love.keypressed(key) forward("keypressed", key) end
Pitfalls
- Speed varies with FPS → you forgot
* dt. Every per-frame change to position, timers,
or animation must be scaled by dt.
love.conf placed in main.lua → it silently does nothing. It must live in conf.lua,
which LÖVE runs before loading modules.
- Colors washed out or invisible → you used 0–255 values. 11.x does not rescale them;
every channel above 1 draws at full intensity, so
setColor(128, 234, 255) comes out
plain white and an alpha of 128 is fully opaque. Use 0–1 floats or
love.math.colorFromBytes (11.3+).
- Everything tinted after one
setColor → color is global and persists across draws.
Reset with love.graphics.setColor(1, 1, 1) before drawing text/images you want untinted.
- Holding a key fires
love.keypressed only once → key repeat is off by default.
Call love.keyboard.setKeyRepeat(true) (e.g. for text fields or menu scrolling); the
repeats then arrive with the third argument isrepeat set, so a jump handler can
ignore them. Releases go to love.keyreleased(key).
References
- For a complete push/pop screen-state manager (menu → game → pause, with delegated
callbacks), read
references/state-stack.md.
Related skills
save-systems — saving/loading game state (engine-agnostic).
input-systems — rebindable, multi-device input architecture.
pygame-core / phaser-core — the same loop concepts in other lightweight engines.
1---2name: love2d-core3description: >4 Structure and debug a LÖVE (Love2D) game in Lua: the love.load/update/draw loop,5 delta-time movement, input, and screen states. Use when building a LÖVE 11.x game6 (main.lua, conf.lua, .love).7metadata:8 source: https://skillmd.com/skills/junmystery/love2d-core9---1011# LÖVE (Love2D) Core1213Set up and debug the foundation of a LÖVE game in Lua: the callback loop, frame-rate-14independent movement, input, and screen states. Targets **LÖVE 11.5**.1516## When to use1718- Use when starting a LÖVE game, wiring up `main.lua`/`conf.lua`, or fixing the core loop,19 movement that runs at the wrong speed, input handling, or screen switching.20- Use when the workspace has `main.lua` calling `love.*`, a `conf.lua`, or a `.love` file.2122**When *not* to use:** Lua *language* questions unrelated to LÖVE; physics bodies/joints23(LÖVE uses Box2D via `love.physics` — a separate concern); shader code (`love.graphics`24GLSL is its own topic). For cross-engine save/load patterns, use `save-systems`.2526## Core workflow27281. **Confirm the entry points.** A LÖVE game runs `main.lua`; it should define29 `love.load()` (one-time setup), `love.update(dt)` (state), and `love.draw()` (rendering).30 Window/version setup goes in `conf.lua` (run *before* modules load).312. **Pin the version.** Set `t.version = "11.5"` in `conf.lua` so LÖVE warns on mismatch.323. **Drive all motion by `dt`** (delta time, in seconds) so speed is frame-rate independent.334. **Handle input** two ways: polled (`love.keyboard.isDown` in `update`, for held keys) and34 event (`love.keypressed` callback, for discrete presses).355. **Manage screens** (menu, game, pause) with a small state stack rather than a pile of36 `if` flags — see Patterns and `references/state-stack.md`.376. **Run and observe.** Launch with `love .` from the project folder; verify the window,38 motion speed, and input on screen before assuming it works.3940## Patterns4142### 1. `main.lua` skeleton (the callback loop + input)4344```lua45-- main.lua — LÖVE calls these callbacks for you. Colors are 0–1 in LÖVE 11.x.46function love.load()47 -- One-time setup. speed is in PIXELS PER SECOND, not per frame.48 player = { x = 100, y = 100, size = 40, speed = 220 }49 love.graphics.setBackgroundColor(0.1, 0.1, 0.12)50end5152function love.update(dt)53 -- Polled input: good for continuous movement while a key is held.54 if love.keyboard.isDown("right") then player.x = player.x + player.speed * dt end55 if love.keyboard.isDown("left") then player.x = player.x - player.speed * dt end56 if love.keyboard.isDown("down") then player.y = player.y + player.speed * dt end57 if love.keyboard.isDown("up") then player.y = player.y - player.speed * dt end58end5960function love.draw()61 love.graphics.setColor(0.2, 0.8, 1.0) -- tint ON62 love.graphics.rectangle("fill", player.x, player.y, player.size, player.size)63 love.graphics.setColor(1, 1, 1) -- reset tint before text/images64 love.graphics.print("Arrow keys to move, Esc to quit", 10, 10)65end6667function love.keypressed(key)68 -- Event input: fires once per physical press. Use for menus, jumps, toggles.69 if key == "escape" then love.event.quit() end70end71```7273### 2. Frame-rate independence (the single most common bug)7475```lua76-- RIGHT: scaled by dt → same real-world speed at 30 or 240 FPS.77player.x = player.x + player.speed * dt78-- WRONG: "pixels per frame" → moves twice as fast at double the frame rate.79player.x = player.x + player.speed80```8182### 3. `conf.lua` (window + version; runs before `main.lua`)8384```lua85-- conf.lua — must be its own file; love.conf will NOT run from main.lua.86function love.conf(t)87 t.version = "11.5" -- the LÖVE version this game targets (string "X.Y")88 t.window.title = "My LÖVE Game"89 t.window.width = 80090 t.window.height = 60091 t.window.vsync = 1 -- number since 11.0: 1 = on, 0 = off, -1 = adaptive92 t.window.resizable = false93 t.modules.physics = false -- disable modules you don't use to trim startup/memory94end95```9697### 4. Color is 0–1 in LÖVE 11.x (not 0–255)9899```lua100-- LÖVE 11.x uses normalized floats. (Pre-11.0 code used 0–255 and will look wrong.)101love.graphics.setColor(1, 0, 0) -- opaque red102love.graphics.setColor(0.2, 0.8, 1.0, 0.5) -- translucent cyan (alpha 0.5)103-- Need to convert old byte values? Use the helper instead of dividing by hand:104love.graphics.setColor(love.math.colorFromBytes(128, 234, 255))105```106107### 5. Screen states (brief — full manager in references)108109```lua110-- A screen is a table with optional :update(dt), :draw(), :keypressed(key).111-- Keep the active screen on a stack so pause/menu overlays are trivial to pop.112local Stack = require("state_stack") -- see references/state-stack.md for the module113114-- Call a method on the top screen only if it defines it (a menu may have no update).115local function forward(name, ...)116 local screen = Stack.current()117 if screen and screen[name] then screen[name](screen, ...) end118end119120function love.load() Stack.push(require("screens.menu")) end121function love.update(dt) forward("update", dt) end122function love.draw() forward("draw") end123function love.keypressed(key) forward("keypressed", key) end124```125126## Pitfalls127128- **Speed varies with FPS** → you forgot `* dt`. Every per-frame change to position, timers,129 or animation must be scaled by `dt`.130- **`love.conf` placed in `main.lua`** → it silently does nothing. It must live in `conf.lua`,131 which LÖVE runs *before* loading modules.132- **Colors washed out or invisible** → you used 0–255 values. 11.x does not rescale them;133 every channel above 1 draws at full intensity, so `setColor(128, 234, 255)` comes out134 plain white and an alpha of `128` is fully opaque. Use 0–1 floats or135 `love.math.colorFromBytes` (11.3+).136- **Everything tinted after one `setColor`** → color is global and persists across draws.137 Reset with `love.graphics.setColor(1, 1, 1)` before drawing text/images you want untinted.138- **Holding a key fires `love.keypressed` only once** → key repeat is off by default.139 Call `love.keyboard.setKeyRepeat(true)` (e.g. for text fields or menu scrolling); the140 repeats then arrive with the third argument `isrepeat` set, so a jump handler can141 ignore them. Releases go to `love.keyreleased(key)`.142143## References144145- For a complete push/pop screen-state manager (menu → game → pause, with delegated146 callbacks), read `references/state-stack.md`.147148## Related skills149150- `save-systems` — saving/loading game state (engine-agnostic).151- `input-systems` — rebindable, multi-device input architecture.152- `pygame-core` / `phaser-core` — the same loop concepts in other lightweight engines.