name: love2d-gamedev
description: >
Complete Love2D game development from prototype to polished release.
Covers core architecture, graphics, animation, tiles, collision, audio,
and iOS deployment. Use when building Love2D games, implementing game
mechanics, or deploying to mobile platforms.

Love2D Game Development

Build polished 2D games with the Love2D framework—from first prototype to iOS release.

Quick Reference

The Love2D Game Loop

Every Love2D game follows this pattern:

function love.load()
    -- Called once at startup
    -- Load assets, initialize state
end

function love.update(dt)
    -- Called every frame
    -- dt = time since last frame (seconds)
    -- Update game logic here
end

function love.draw()
    -- Called every frame after update
    -- All rendering happens here
end

Key insight: dt (delta time) ensures consistent speed across frame rates.

-- WRONG: Speed varies with frame rate
player.x = player.x + 5

-- RIGHT: 200 pixels per second, regardless of FPS
player.x = player.x + 200 * dt

Essential Patterns

Loading and Drawing Images

function love.load()
    playerImage = love.graphics.newImage("player.png")
end

function love.draw()
    love.graphics.draw(playerImage, x, y)
    -- Full signature: draw(image, x, y, rotation, scaleX, scaleY, originX, originY)
end

Input Handling

-- Polling (check every frame)
function love.update(dt)
    if love.keyboard.isDown("left") then
        player.x = player.x - 200 * dt
    end
end

-- Event-based (fires once per press)
function love.keypressed(key)
    if key == "space" then
        player:jump()
    end
end

Screen-Adaptive Positioning

Never hard-code screen dimensions:

function love.load()
    screenW, screenH = love.graphics.getDimensions()
end

function love.resize(w, h)
    screenW, screenH = w, h
end

function love.draw()
    -- Position relative to screen
    local centerX = screenW / 2
    local bottomY = screenH - 50
end

Core Modules

Project Setup

Minimal Project

my-game/
├── main.lua      # Entry point (required)
└── conf.lua      # Configuration (optional but recommended)

conf.lua Template

function love.conf(t)
    t.window.title = "My Game"
    t.window.width = 800
    t.window.height = 600
    t.version = "11.5"              -- Love2D version
    t.console = true                -- Enable console on Windows

    -- Disable unused modules for faster startup
    t.modules.joystick = false
    t.modules.physics = false
end

Running the Game

# macOS
/Applications/love.app/Contents/MacOS/love /path/to/game

# Create alias in ~/.zshrc
alias love="/Applications/love.app/Contents/MacOS/love"

Common Patterns

State Management

local gameState = "menu"  -- menu, playing, paused, gameover

function love.update(dt)
    if gameState == "playing" then
        updateGame(dt)
    end
end

function love.draw()
    if gameState == "menu" then
        drawMenu()
    elseif gameState == "playing" then
        drawGame()
    end
end

Object-Oriented Entities

local Player = {}
Player.__index = Player

function Player:new(x, y)
    return setmetatable({
        x = x, y = y,
        speed = 200,
        image = love.graphics.newImage("player.png")
    }, Player)
end

function Player:update(dt)
    if love.keyboard.isDown("right") then
        self.x = self.x + self.speed * dt
    end
end

function Player:draw()
    love.graphics.draw(self.image, self.x, self.y)
end

return Player

Camera/Viewport

local camera = { x = 0, y = 0 }

function love.draw()
    love.graphics.push()
    love.graphics.translate(-camera.x, -camera.y)

    -- Draw world objects here
    drawWorld()

    love.graphics.pop()

    -- Draw UI here (not affected by camera)
    drawUI()
end

Anti-Patterns to Avoid

iOS Development

For iOS deployment, see the iOS Overview which covers:

• Build Setup - Xcode project, libraries, signing
• Touch Controls - Virtual joysticks, buttons, gestures
• Xcode Project Structure - Manual pbxproj editing

Quick iOS checklist:
1. Download Love2D iOS source + Apple libraries
2. Copy libraries to Xcode project
3. Fix deployment target (8.0 → 15.0)
4. Create game.love (zip of Lua files)
5. Add game.love to Xcode bundle resources
6. Configure signing and deploy

Philosophy

Love2D makes game development joyful through simplicity:

1. Lua is approachable - Dynamic typing, clean syntax, fast iteration
2. The API is consistent - Functions follow predictable patterns
3. You own the game loop - No hidden magic, full control
4. Cross-platform by default - Same code runs on Windows, macOS, Linux, iOS, Android

The goal isn't just "make it work." The goal is "make it feel great."

Smooth animations, responsive controls, adaptive layouts—that's the standard for polished games.