Love2d Ios

Love2D iOS Development

Build games with Love2D and deploy them to iOS devices—from first prototype to App Store.

Philosophy: Mobile-First Game Development

Love2D was born on desktop, but mobile is where players are. The challenge isn't just "making it run on iOS"—it's rethinking the game for touch.

Before building for iOS, ask:

• How will players interact without a keyboard?
• What screen sizes and orientations should be supported?
• Is the game's pacing appropriate for mobile sessions?
• What gestures feel natural for this game's actions?

Core principles:

1. Touch is not a keyboard substitute: Design touch controls that feel native, not bolted-on. A virtual d-pad is a last resort, not a first choice.

2. Screen size is a variable, not a constant: Hard-coded coordinates break on different devices. Think in percentages and relative positions.

3. The build pipeline is fragile: Xcode projects, code signing, and bundle resources have many failure points. Understand the system, don't just copy commands.

4. Iterate on device early: The simulator lies. Test on real hardware as soon as possible.

---

Development Workflow

Desktop Development First

Develop and test on desktop before touching iOS:

# macOS: Love2D isn't in PATH by default
/Applications/love.app/Contents/MacOS/love /path/to/game

# Or create an alias in ~/.zshrc
alias love="/Applications/love.app/Contents/MacOS/love"

Project Structure

my-game/
├── conf.lua          # Window size, Love2D version
├── main.lua          # Entry point
├── touch.lua         # Mobile touch controls (optional on desktop)
└── [game modules]    # Player, enemies, etc.

iOS Build Pipeline

See references/ios-setup.md for detailed setup steps.

Quick overview: 1. Download Love2D iOS source + Apple libraries 2. Copy libraries to Xcode project 3. Create game.love (zip of Lua files) 4. Add game.love to Xcode bundle resources 5. Configure signing and deploy

Update Workflow

Every code change requires rebuilding:

# From game directory
rm -f game.love
zip -9 -r game.love *.lua [assets/]
cp game.love /path/to/xcode/ios/
# Then build in Xcode (Cmd+R)

---

Touch Control Patterns

See references/touch-controls.md for implementation details.

Choosing the Right Pattern

Touch Event Basics

function love.touchpressed(id, x, y, dx, dy, pressure)
    -- id: unique per finger (for multitouch)
    -- x, y: screen coordinates
end

function love.touchmoved(id, x, y, dx, dy, pressure)
    -- Track finger movement
end

function love.touchreleased(id, x, y, dx, dy, pressure)
    -- Clean up touch state
end

Platform Detection

local function isMobile()
    local os = love.system.getOS()
    return os == "iOS" or os == "Android"
end

-- Use this to conditionally show touch controls
if isMobile() then
    touchControls = require("touch")
end

---

Screen Adaptation

Dynamic Sizing

Never hard-code 800x600. Always query dimensions:

local screenW, screenH

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

function love.resize(w, h)
    screenW, screenH = w, h
    -- Reposition UI, regenerate layouts
end

Positioning Strategies

Percentage-based:

local buttonX = screenW * 0.85  -- 85% from left
local buttonY = screenH * 0.9   -- 90% from top

Anchor-based:

local margin = 20
local rightEdge = screenW - margin
local bottomEdge = screenH - margin

Aspect-ratio aware:

local targetAspect = 16/9
local currentAspect = screenW / screenH
-- Add letterboxing or adjust game area

---

Anti-Patterns to Avoid

❌ Hard-coded coordinates

-- BAD: Breaks on different screens
player.x = 400
button.y = 550

Why bad: iPhone SE and iPad Pro have very different dimensions. Better: Use percentages or anchor points relative to screen size.

❌ Ignoring the "No-game screen" Why bad: Your game.love wasn't bundled—the app is working, your game isn't loaded. Better: Verify game.love is in "Copy Bundle Resources" build phase.

❌ Testing only on simulator Why bad: Simulator has different performance, touch behavior, and screen characteristics. Better: Deploy to a real device early and often.

❌ Giant virtual joysticks Why bad: Obscures gameplay, feels clunky. Better: Semi-transparent, appropriately sized (60-80px radius), positioned in thumb-reach zones.

❌ Copying Xcode project changes blindly Why bad: You won't know how to fix it when it breaks differently. Better: Understand the project.pbxproj structure—PBXBuildFile, PBXFileReference, build phases.

❌ Forgetting to rebuild game.love Why bad: You're testing old code and wondering why changes don't work. Better: Script the rebuild process. Make it one command.

---

Common Issues and Solutions

Deployment Target Errors

Error: IPHONEOS_DEPLOYMENT_TARGET is set to 8.0, but range is 12.0 to X.X

Fix:

find . -name "*.pbxproj" -exec sed -i '' \
  's/IPHONEOS_DEPLOYMENT_TARGET = 8.0/IPHONEOS_DEPLOYMENT_TARGET = 15.0/g' {} \;

"No-game screen" on Device

Cause: game.love not in bundle resources.

Fix: Add game.love to Xcode project: 1. Right-click ios folder → Add Files 2. Select game.love 3. Ensure "Add to targets: love-ios" is checked

If that fails, see references/xcode-project-structure.md for manual pbxproj editing.

Signing Errors

Fix: In Xcode: 1. Select love-ios target 2. Signing & Capabilities → Select your Team 3. Change Bundle Identifier to something unique

Touch Not Responding

Causes:

• Not implementing touch callbacks
• Touch area too small (minimum 44x44 points recommended)
• Touch being consumed by wrong element

---

Variation Guidance

Touch control layouts should vary based on:

• Game genre (platformer vs puzzle vs action)
• Screen size (phone vs tablet)
• Player handedness (consider offering options)
• Game complexity (fewer buttons for simpler games)

Avoid converging on:

• Always using virtual joystick (sometimes gestures are better)
• Always putting fire button bottom-right (context matters)
• Fixed button sizes (adapt to screen)

---

File Locations Reference

---

Remember

Love2D makes game development joyful. iOS deployment adds friction, but understanding the pipeline—not just following steps—makes you resilient when things break.

The goal isn't "run on iOS." The goal is "feel great on iOS."

Touch controls that feel native, layouts that adapt gracefully, and a build process you understand—that's the standard.

Claude is capable of building complete, polished mobile games. These guidelines illuminate the path from desktop prototype to iOS deployment.

iOS Build Setup

Complete setup guide for building Love2D games on iOS.

Prerequisites

• macOS with Xcode installed (16+ recommended)
• Apple Developer Account (free works for personal device testing)
• iOS device connected via USB
• Love2D desktop app for testing

Step 1: Download Required Files

From https://love2d.org/ or https://github.com/love2d/love/releases:

1. `love-X.X-ios-source.zip` - Xcode project and source 2. `love-X.X-apple-libraries.zip` - Required iOS libraries

Step 2: Extract and Setup Libraries

# Extract both archives
unzip love-11.5-ios-source.zip
unzip love-11.5-apple-libraries.zip

# Copy iOS libraries to correct location
cp -r love-apple-dependencies/iOS/libraries/* \
      love-11.5-ios-source/platform/xcode/ios/libraries/

Verify libraries installed:

ls love-11.5-ios-source/platform/xcode/ios/libraries/
# Should see: freetype, lua, openal-soft, etc.

Step 3: Fix Deployment Target

Modern Xcode requires iOS 12.0+ deployment target. Love2D ships with 8.0.

cd love-11.5-ios-source/platform/xcode

# Update all project files
find . -name "*.pbxproj" -exec sed -i '' \
  's/IPHONEOS_DEPLOYMENT_TARGET = 8.0/IPHONEOS_DEPLOYMENT_TARGET = 15.0/g' {} \;

# Also fix any 12.0 targets if needed
find . -name "*.pbxproj" -exec sed -i '' \
  's/IPHONEOS_DEPLOYMENT_TARGET = 12.0/IPHONEOS_DEPLOYMENT_TARGET = 15.0/g' {} \;

Why 15.0? Balances broad device compatibility with modern iOS features.

Step 4: Create game.love

cd /path/to/your/game

# Bundle all Lua files
zip -9 -r game.love *.lua

# Include assets if you have them
zip -9 -r game.love *.lua assets/ sounds/ images/

Step 5: Add game.love to iOS Project

cp game.love love-11.5-ios-source/platform/xcode/ios/

Important: Copying the file is not enough. You must add it to Xcode's bundle resources.

Method A: Xcode UI (Preferred)

1. Open love.xcodeproj in Xcode 2. In project navigator, right-click the ios folder 3. Select "Add Files to 'love'..." 4. Navigate to and select game.love 5. Check "Add to targets: love-ios" 6. Click Add

Method B: Manual pbxproj Edit

If Xcode UI doesn't work, see xcode-project-structure.md for manual editing.

Step 6: Configure Signing

1. Select love-ios target (not love-macosx) 2. Go to Signing & Capabilities tab 3. Select your Team from dropdown 4. Change Bundle Identifier to something unique:

• Example: com.yourname.yourgame
• Must be globally unique

Step 7: Build and Deploy

1. Connect iOS device via USB 2. Select your device as run destination (not simulator) 3. Press ⌘R or Product → Run 4. Trust the developer certificate on device if prompted:

• Settings → General → VPN & Device Management

Troubleshooting

"No-game screen"

game.love not bundled. Verify in Xcode: 1. Select love-ios target 2. Build Phases → Copy Bundle Resources 3. Confirm game.love is listed

Build succeeds but app crashes

Check Console.app on Mac for crash logs. Common causes:

• Missing assets referenced in Lua
• Syntax errors in Lua files
• Library incompatibilities

"Signing requires a development team"

Select your Apple ID team in Signing & Capabilities.

Simulator vs Device

The simulator is x86/ARM translated and doesn't perfectly match iOS behavior. Always verify on real hardware before considering the build "done."

Touch Controls Implementation

Patterns and code for implementing touch controls in Love2D iOS games.

Touch Event System

Love2D provides three touch callbacks:

function love.touchpressed(id, x, y, dx, dy, pressure)
    -- Finger touched screen
    -- id: unique identifier for this finger (multitouch support)
    -- x, y: position in screen coordinates
    -- pressure: 0-1 on devices that support it
end

function love.touchmoved(id, x, y, dx, dy, pressure)
    -- Finger moved while touching
    -- dx, dy: delta from last position
end

function love.touchreleased(id, x, y, dx, dy, pressure)
    -- Finger lifted from screen
end

Important: Track touch IDs for multitouch. Don't assume single touch.

Virtual Joystick Implementation

Basic Structure

local Touch = {}
Touch.__index = Touch

function Touch:new(screenW, screenH)
    local self = setmetatable({}, Touch)

    self.screenW = screenW
    self.screenH = screenH

    -- Joystick state
    self.joystick = {
        active = false,
        touchId = nil,
        baseX = 0,
        baseY = 0,
        knobX = 0,
        knobY = 0,
        radius = 60,
        knobRadius = 25,
        deadzone = 0.15
    }

    -- Output values (-1 to 1)
    self.moveX = 0
    self.moveY = 0

    return self
end

Floating Joystick Pattern

Joystick appears where you touch (more intuitive than fixed position):

function Touch:touchpressed(id, x, y)
    local js = self.joystick

    -- Left third of screen, bottom half = joystick zone
    if x < self.screenW / 3 and y > self.screenH / 2 then
        js.active = true
        js.touchId = id
        js.baseX = x
        js.baseY = y
        js.knobX = x
        js.knobY = y
    end
end

function Touch:touchmoved(id, x, y)
    local js = self.joystick

    if js.active and js.touchId == id then
        local dx = x - js.baseX
        local dy = y - js.baseY
        local dist = math.sqrt(dx * dx + dy * dy)

        -- Clamp knob to radius
        if dist > js.radius then
            dx = dx / dist * js.radius
            dy = dy / dist * js.radius
            dist = js.radius
        end

        js.knobX = js.baseX + dx
        js.knobY = js.baseY + dy

        -- Normalize to -1 to 1 with deadzone
        local normalizedDist = dist / js.radius
        if normalizedDist < js.deadzone then
            self.moveX = 0
            self.moveY = 0
        else
            -- Remap deadzone to full range
            local scale = (normalizedDist - js.deadzone) / (1 - js.deadzone)
            self.moveX = (dx / dist) * scale
            self.moveY = (dy / dist) * scale
        end
    end
end

function Touch:touchreleased(id)
    local js = self.joystick

    if js.touchId == id then
        js.active = false
        js.touchId = nil
        self.moveX = 0
        self.moveY = 0
    end
end

Drawing the Joystick

function Touch:draw()
    local js = self.joystick

    if js.active then
        -- Base circle (semi-transparent)
        love.graphics.setColor(1, 1, 1, 0.3)
        love.graphics.circle("fill", js.baseX, js.baseY, js.radius)
        love.graphics.setColor(1, 1, 1, 0.5)
        love.graphics.circle("line", js.baseX, js.baseY, js.radius)

        -- Knob
        love.graphics.setColor(0.2, 0.6, 1, 0.8)
        love.graphics.circle("fill", js.knobX, js.knobY, js.knobRadius)
    end

    love.graphics.setColor(1, 1, 1, 1)  -- Reset color
end

Action Buttons

Button Structure

function Touch:new(screenW, screenH)
    -- ... joystick setup ...

    -- Action buttons (right side of screen)
    local btnSize = 70
    local margin = 30

    self.fireButton = {
        x = screenW - margin - btnSize,
        y = screenH - margin - btnSize,
        radius = btnSize / 2,
        active = false,
        touchId = nil,
        label = "FIRE",
        color = {0.8, 0.2, 0.2}
    }

    self.jumpButton = {
        x = screenW - margin - btnSize,
        y = screenH - margin - btnSize * 2 - 20,
        radius = btnSize / 2,
        active = false,
        touchId = nil,
        label = "JUMP",
        color = {0.2, 0.7, 0.3}
    }

    self.shooting = false
    self.jumped = false
end

Button Touch Handling

local function pointInCircle(px, py, cx, cy, r)
    local dx = px - cx
    local dy = py - cy
    return (dx * dx + dy * dy) <= (r * r)
end

function Touch:touchpressed(id, x, y)
    -- Check fire button
    local fb = self.fireButton
    if pointInCircle(x, y, fb.x, fb.y, fb.radius * 1.2) then
        fb.active = true
        fb.touchId = id
        self.shooting = true
        return
    end

    -- Check jump button
    local jb = self.jumpButton
    if pointInCircle(x, y, jb.x, jb.y, jb.radius * 1.2) then
        jb.active = true
        jb.touchId = id
        self.jumped = true  -- Single press, not held
        return
    end

    -- ... joystick handling ...
end

function Touch:touchreleased(id)
    if self.fireButton.touchId == id then
        self.fireButton.active = false
        self.fireButton.touchId = nil
        self.shooting = false
    end

    if self.jumpButton.touchId == id then
        self.jumpButton.active = false
        self.jumpButton.touchId = nil
    end

    -- ... joystick handling ...
end

Drawing Buttons

function Touch:drawButton(btn)
    -- Button background
    if btn.active then
        love.graphics.setColor(btn.color[1], btn.color[2], btn.color[3], 0.9)
    else
        love.graphics.setColor(btn.color[1], btn.color[2], btn.color[3], 0.5)
    end
    love.graphics.circle("fill", btn.x, btn.y, btn.radius)

    -- Button border
    love.graphics.setColor(1, 1, 1, 0.7)
    love.graphics.circle("line", btn.x, btn.y, btn.radius)

    -- Label
    love.graphics.setColor(1, 1, 1, 0.9)
    local font = love.graphics.getFont()
    local textW = font:getWidth(btn.label)
    local textH = font:getHeight()
    love.graphics.print(btn.label, btn.x - textW/2, btn.y - textH/2)
end

function Touch:draw()
    self:drawButton(self.fireButton)
    self:drawButton(self.jumpButton)
    -- ... joystick drawing ...
end

Integrating with Game Logic

In main.lua

local Touch = require("touch")
local touchControls

function love.load()
    local w, h = love.graphics.getDimensions()

    if love.system.getOS() == "iOS" or love.system.getOS() == "Android" then
        touchControls = Touch:new(w, h)
    end
end

function love.update(dt)
    if touchControls then
        -- Pass touch input to player
        player:setTouchInput(
            touchControls.moveX,
            touchControls.moveY,
            touchControls.shooting,
            touchControls.jumped
        )

        -- Clear single-press flags
        touchControls.jumped = false
    end
end

function love.draw()
    -- Draw game...

    -- Draw touch controls on top
    if touchControls then
        touchControls:draw()
    end
end

function love.touchpressed(id, x, y, dx, dy, pressure)
    if touchControls then
        touchControls:touchpressed(id, x, y)
    end
end

function love.touchmoved(id, x, y, dx, dy, pressure)
    if touchControls then
        touchControls:touchmoved(id, x, y)
    end
end

function love.touchreleased(id, x, y, dx, dy, pressure)
    if touchControls then
        touchControls:touchreleased(id, x, y)
    end
end

In player.lua

function Player:setTouchInput(moveX, moveY, shooting, jump)
    self.touchMoveX = moveX or 0
    self.touchMoveY = moveY or 0
    self.touchShooting = shooting or false

    if jump then
        self.touchJump = true
    end
end

function Player:update(dt)
    -- Combine keyboard and touch input
    local moveX = 0

    if love.keyboard.isDown("left", "a") then moveX = -1 end
    if love.keyboard.isDown("right", "d") then moveX = 1 end

    -- Touch overrides if active
    if math.abs(self.touchMoveX) > 0.1 then
        moveX = self.touchMoveX
    end

    self.x = self.x + moveX * self.speed * dt

    -- Jumping
    if self.onGround and (love.keyboard.isDown("space", "w", "up") or self.touchJump) then
        self.vy = self.jumpForce
        self.onGround = false
        self.touchJump = false
    end

    -- Shooting
    local shooting = love.mouse.isDown(1) or self.touchShooting
    if shooting then
        self:shoot()
    end
end

Gesture Patterns

Tap Detection

local tapState = {
    startTime = 0,
    startX = 0,
    startY = 0,
    maxTapDuration = 0.3,  -- seconds
    maxTapDistance = 20     -- pixels
}

function love.touchpressed(id, x, y)
    tapState.startTime = love.timer.getTime()
    tapState.startX = x
    tapState.startY = y
end

function love.touchreleased(id, x, y)
    local duration = love.timer.getTime() - tapState.startTime
    local dx = x - tapState.startX
    local dy = y - tapState.startY
    local distance = math.sqrt(dx*dx + dy*dy)

    if duration < tapState.maxTapDuration and distance < tapState.maxTapDistance then
        onTap(x, y)  -- Handle tap
    end
end

Swipe Detection

local swipeState = {
    startX = 0,
    startY = 0,
    minSwipeDistance = 50
}

function love.touchpressed(id, x, y)
    swipeState.startX = x
    swipeState.startY = y
end

function love.touchreleased(id, x, y)
    local dx = x - swipeState.startX
    local dy = y - swipeState.startY
    local distance = math.sqrt(dx*dx + dy*dy)

    if distance > swipeState.minSwipeDistance then
        -- Determine direction
        if math.abs(dx) > math.abs(dy) then
            if dx > 0 then onSwipe("right")
            else onSwipe("left") end
        else
            if dy > 0 then onSwipe("down")
            else onSwipe("up") end
        end
    end
end

Best Practices

1. Touch target size: Minimum 44x44 points (Apple HIG recommendation) 2. Deadzone: 10-20% to prevent drift from resting thumb 3. Visual feedback: Show button press states clearly 4. Transparency: Don't obscure gameplay with opaque controls 5. Thumb reach: Place controls where thumbs naturally rest 6. Multitouch: Always track touch IDs, never assume single touch

Xcode Project Structure

Understanding project.pbxproj for manual game.love bundling.

When You Need This

When Xcode's "Add Files" UI doesn't work or you need to automate the process, you'll need to manually edit love.xcodeproj/project.pbxproj.

project.pbxproj Overview

The pbxproj file is a structured text file (OpenStep plist format) containing:

• PBXBuildFile: Files that get compiled or copied
• PBXFileReference: All files known to the project
• PBXGroup: Folder structure in Xcode navigator
• PBXNativeTarget: Build targets (love-ios, love-macosx)
• PBXResourcesBuildPhase: Files copied to app bundle (this is key!)

Adding game.love Manually

You need to add entries to four sections:

1. PBXBuildFile Section

Find /* Begin PBXBuildFile section */ and add:

GAMELOVE000200000000001 /* game.love in Resources */ = {isa = PBXBuildFile; fileRef = GAMELOVE000100000000001 /* game.love */; };

This tells Xcode "game.love should be copied as a resource."

2. PBXFileReference Section

Find /* Begin PBXFileReference section */ and add:

GAMELOVE000100000000001 /* game.love */ = {isa = PBXFileReference; lastKnownFileType = file; name = game.love; path = ios/game.love; sourceTree = "<group>"; };

This defines the file reference—where the file lives and what it is.

3. PBXGroup (Resources or iOS folder)

Find the group that represents the ios folder. Look for something like:

/* ios */ = {
    isa = PBXGroup;
    children = (
        ...existing files...
    );

Add your file reference to the children array:

children = (
    ...existing files...,
    GAMELOVE000100000000001 /* game.love */,
);

4. Copy Bundle Resources Build Phase

Find the /* Copy Bundle Resources */ section for the love-ios target (not love-macosx). Look for:

/* Copy Bundle Resources */ = {
    isa = PBXResourcesBuildPhase;
    buildActionMask = 2147483647;
    files = (
        ...existing files...
    );

Add your build file:

files = (
    ...existing files...,
    GAMELOVE000200000000001 /* game.love in Resources */,
);

Important Notes

ID Format

The IDs (like GAMELOVE000200000000001) must be:

• Unique across the entire file
• 24 characters (hexadecimal typically, but any chars work)
• Consistent between PBXBuildFile fileRef and PBXFileReference

Finding the Right Target

There may be multiple "Copy Bundle Resources" sections:

• One for love-ios (iOS target) ✓
• One for love-macosx (macOS target)

Make sure you add to the love-ios target's build phase.

To identify which is which, look for nearby comments or trace the target's buildPhases array.

Trailing Commas

Xcode is forgiving about trailing commas in arrays. Adding a comma after your entry is safe.

Example: Complete Addition

Before:

/* Begin PBXBuildFile section */
...existing entries...
/* End PBXBuildFile section */

/* Begin PBXFileReference section */
...existing entries...
/* End PBXFileReference section */

After:

/* Begin PBXBuildFile section */
...existing entries...
GAMELOVE000200000000001 /* game.love in Resources */ = {isa = PBXBuildFile; fileRef = GAMELOVE000100000000001 /* game.love */; };
/* End PBXBuildFile section */

/* Begin PBXFileReference section */
...existing entries...
GAMELOVE000100000000001 /* game.love */ = {isa = PBXFileReference; lastKnownFileType = file; name = game.love; path = ios/game.love; sourceTree = "<group>"; };
/* End PBXFileReference section */

Automation Script

#!/bin/bash
# add-game-to-xcode.sh
# Run from xcode project directory

PBXPROJ="love.xcodeproj/project.pbxproj"

# Unique IDs for game.love
FILE_REF="GAMELOVE000100000000001"
BUILD_REF="GAMELOVE000200000000001"

# Check if already added
if grep -q "$FILE_REF" "$PBXPROJ"; then
    echo "game.love already in project"
    exit 0
fi

# Backup
cp "$PBXPROJ" "$PBXPROJ.backup"

# Add PBXBuildFile entry
sed -i '' "/\/\* Begin PBXBuildFile section \*\//a\\
$BUILD_REF /* game.love in Resources */ = {isa = PBXBuildFile; fileRef = $FILE_REF /* game.love */; };
" "$PBXPROJ"

# Add PBXFileReference entry
sed -i '' "/\/\* Begin PBXFileReference section \*\//a\\
$FILE_REF /* game.love */ = {isa = PBXFileReference; lastKnownFileType = file; name = game.love; path = ios/game.love; sourceTree = \"<group>\"; };
" "$PBXPROJ"

echo "Added game.love references. Manually add to group and build phase if needed."

Verifying Success

After editing:

1. Open Xcode—if it complains about project format, you made a syntax error 2. Check love-ios target → Build Phases → Copy Bundle Resources 3. game.love should appear in the list 4. Build and verify game loads on device

Troubleshooting

Xcode won't open project: Syntax error in pbxproj. Restore backup and try again.

game.love in project but not loading: Added to wrong target or wrong build phase. Verify it's in love-ios's "Copy Bundle Resources."

Duplicate symbol errors: You added the same ID twice. Each ID must be unique.