love2d-ios

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Love2D iOS Development

Love2D iOS 开发

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

使用Love2D构建游戏并将其部署到iOS设备——从原型开发到上线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:

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.
Screen size is a variable, not a constant: Hard-coded coordinates break on different devices. Think in percentages and relative positions.
The build pipeline is fragile: Xcode projects, code signing, and bundle resources have many failure points. Understand the system, don't just copy commands.
Iterate on device early: The simulator lies. Test on real hardware as soon as possible.

Love2D 起源于桌面平台，但如今玩家更多聚集在移动平台。我们面临的挑战不只是“让游戏在iOS上运行”，而是为触摸操作重新设计游戏。

在为iOS构建游戏前，请先思考：

玩家没有键盘时该如何与游戏互动？
应该支持哪些屏幕尺寸和方向？
游戏的节奏是否适合移动端的碎片化游戏时长？
哪些手势操作对这款游戏的交互来说更自然？

核心原则：

触摸不是键盘的替代品：设计原生感的触摸控制，而非生硬移植。虚拟方向键是最后的选择，而非首选方案。
屏幕尺寸是变量而非常量：硬编码的坐标会在不同设备上失效。请使用百分比和相对位置进行布局。
构建流程较为脆弱：Xcode项目、代码签名和资源打包存在很多可能出错的环节。请理解整个系统的原理，不要只是复制命令。
尽早在真机上迭代：模拟器会“说谎”。请尽快在真实硬件上进行测试。

Development Workflow

开发工作流

Desktop Development First

先在桌面端完成开发

Develop and test on desktop before touching iOS:

bash

undefined

在接触iOS开发前，先在桌面端完成游戏的开发与测试：

bash

undefined

macOS: Love2D isn't in PATH by default

macOS：Love2D 默认不在PATH中

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

Or create an alias in ~/.zshrc

或者在~/.zshrc中创建别名

alias love="/Applications/love.app/Contents/MacOS/love"

undefined

alias love="/Applications/love.app/Contents/MacOS/love"

undefined

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.

my-game/
├── conf.lua          # 窗口尺寸、Love2D版本配置
├── main.lua          # 程序入口
├── touch.lua         # 移动端触摸控制（桌面端可选）
└── [game modules]    # 玩家、敌人等游戏模块

iOS Build Pipeline

iOS构建流程

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

Quick overview:

Download Love2D iOS source + Apple libraries
Copy libraries to Xcode project
Create
```
game.love
```
(zip of Lua files)
Add
```
game.love
```
to Xcode bundle resources
Configure signing and deploy

详细的设置步骤请参考 references/ios-setup.md。

快速概览：

下载Love2D iOS源码 + Apple相关库
将库文件复制到Xcode项目中
创建
```
game.love
```
（Lua文件的压缩包）
将
```
game.love
```
添加到Xcode的打包资源中
配置签名并部署

Update Workflow

更新工作流

Every code change requires rebuilding:

bash

undefined

每次代码变更都需要重新构建：

bash

undefined

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)

然后在Xcode中构建（Cmd+R）

---

---

Touch Control Patterns

触摸控制模式

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

具体实现细节请参考 references/touch-controls.md。

Choosing the Right Pattern

选择合适的控制模式

Game Type	Recommended Control
Platformer	Virtual joystick + action buttons
Puzzle	Direct touch/drag on game objects
Endless runner	Tap/swipe gestures
Turn-based	Tap to select, tap to confirm
Twin-stick	Dual virtual joysticks

游戏类型	推荐控制方式
平台跳跃类	虚拟摇杆 + 动作按钮
益智解谜类	直接触摸/拖拽游戏对象
无尽跑酷类	点击/滑动手势
回合制类	点击选择，点击确认
双摇杆射击类	双虚拟摇杆

Touch Event Basics

触摸事件基础

lua

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

lua

function love.touchpressed(id, x, y, dx, dy, pressure)
    -- id: 每个手指的唯一标识（支持多点触摸）
    -- x, y: 屏幕坐标
end

function love.touchmoved(id, x, y, dx, dy, pressure)
    -- 追踪手指移动
end

function love.touchreleased(id, x, y, dx, dy, pressure)
    -- 清理触摸状态
end

Platform Detection

平台检测

lua

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

lua

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

-- 根据平台条件加载触摸控制
if isMobile() then
    touchControls = require("touch")
end

Screen Adaptation

屏幕适配

Dynamic Sizing

动态尺寸适配

Never hard-code 800x600. Always query dimensions:

lua

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

永远不要硬编码800x600这类固定尺寸，请始终查询当前屏幕尺寸：

lua

local screenW, screenH

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

function love.resize(w, h)
    screenW, screenH = w, h
    -- 重新定位UI，重新生成布局
end

Positioning Strategies

定位策略

Percentage-based:

lua

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

Anchor-based:

lua

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

Aspect-ratio aware:

lua

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

百分比定位:

lua

local buttonX = screenW * 0.85  -- 距离左侧85%的位置
local buttonY = screenH * 0.9   -- 距离顶部90%的位置

锚点定位:

lua

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

宽高比适配:

lua

local targetAspect = 16/9
local currentAspect = screenW / screenH
-- 添加黑边或调整游戏区域

Anti-Patterns to Avoid

需要避免的反模式

❌ Hard-coded coordinates

lua

-- 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.

❌ 硬编码坐标

lua

-- 错误写法：在不同屏幕上会失效
player.x = 400
button.y = 550

为什么不好：iPhone SE和iPad Pro的尺寸差异极大。更好的做法：使用百分比或基于屏幕尺寸的锚点定位。

❌ 忽略“无游戏画面”问题 为什么不好：你的game.love没有被正确打包——App能运行，但游戏没有加载。更好的做法：确认game.love已添加到“Copy Bundle Resources”构建阶段。

❌ 只在模拟器上测试 为什么不好：模拟器的性能、触摸行为和屏幕特性与真机不同。更好的做法：尽早并频繁地部署到真机测试。

❌ 过大的虚拟摇杆 为什么不好：遮挡游戏画面，操作手感笨重。更好的做法：使用半透明、尺寸合适（半径60-80px）的摇杆，放置在拇指易触及的区域。

❌ 盲目复制Xcode项目修改 为什么不好：当问题以不同形式出现时，你不知道如何修复。更好的做法：理解project.pbxproj的结构——PBXBuildFile、PBXFileReference和构建阶段的作用。

❌ 忘记重新构建game.love 为什么不好：你在测试旧代码，却疑惑为什么修改没有生效。更好的做法：将重新构建的过程写成脚本，一键完成。

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:

bash

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

错误提示：

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

修复方案:

bash

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:

Right-click ios folder → Add Files
Select game.love
Ensure "Add to targets: love-ios" is checked

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

原因：game.love未被包含在打包资源中。

修复方案：将game.love添加到Xcode项目：

右键点击ios文件夹 → 添加文件
选择game.love
确保“Add to targets: love-ios”选项已勾选

如果仍未解决，请参考 references/xcode-project-structure.md 手动编辑pbxproj文件。

Signing Errors

签名错误

Fix: In Xcode:

Select love-ios target
Signing & Capabilities → Select your Team
Change Bundle Identifier to something unique

修复方案：在Xcode中：

选择love-ios目标
进入Signing & Capabilities → 选择你的开发团队
将Bundle Identifier修改为唯一值

Touch Not Responding

触摸无响应

Causes:

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

可能原因:

未实现触摸回调函数
触摸区域过小（推荐最小尺寸为44x44点）
触摸事件被其他元素拦截

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)

触摸控制布局应根据以下因素调整:

游戏类型（平台跳跃类 vs 益智解谜类 vs 动作类）
屏幕尺寸（手机 vs 平板）
玩家用手习惯（考虑提供自定义选项）
游戏复杂度（简单游戏使用更少的按钮）

避免陷入固定思维:

不要总是使用虚拟摇杆（有时手势操作更合适）
不要总是将开火按钮放在右下角（根据场景调整）
不要使用固定尺寸的按钮（根据屏幕尺寸自适应）

File Locations Reference

文件位置参考

Purpose	Path
Xcode project	`love-X.X-ios-source/platform/xcode/love.xcodeproj`
iOS libraries	`love-X.X-ios-source/platform/xcode/ios/libraries/`
game.love destination	`love-X.X-ios-source/platform/xcode/ios/game.love`
Project config	`love.xcodeproj/project.pbxproj`

用途	路径
Xcode项目	`love-X.X-ios-source/platform/xcode/love.xcodeproj`
iOS相关库	`love-X.X-ios-source/platform/xcode/ios/libraries/`
game.love目标路径	`love-X.X-ios-source/platform/xcode/ios/game.love`
项目配置	`love.xcodeproj/project.pbxproj`

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.

Love2D让游戏开发充满乐趣。iOS部署会增加一些复杂度，但理解整个流程的原理——而非只是照搬步骤——能让你在遇到问题时更从容。

我们的目标不是“能在iOS上运行”，而是“在iOS上拥有出色的体验”。

原生感的触摸控制、自适应的布局、可掌控的构建流程——这才是我们追求的标准。

Claude能够构建完整、精致的移动游戏。这份指南为你照亮从桌面原型到iOS部署的路径。