Xcode Flappy Bird 复刻工程：从零搭建到二次开发

简介：这份资源是面向 iOS 游戏开发初学者与进阶者的 Flappy Bird 复刻工程源码，基于 Xcode 环境构建，围绕 2D 休闲游戏的核心玩法展开，可用于学习物理模拟、触摸交互与得分判定等完整开发流程。压缩包共 58 个文件，约 507KB，包含 15 个 png 图像素材、8 个 m 与 6 个 h 源码文件、7 个 json 配置、3 个 mp3 与 1 个 wav 音效、2 个 sks 场景文件及 plist、strings 等工程配置，覆盖代码、资源与项目结构三类内容。已有 180 人学习下载。工程按 Player、Pipe、GameScene 等模块拆分，配合 SpriteKit 物理引擎与场景文件，读者可据此理解小鸟飞行、管道生成、碰撞检测与计分逻辑的实现方式，并借助 Xcode 调试工具排查问题，适合作为游戏开发入门实践与二次创作的参考模板。

1. 从一份 Xcode 工程看 Flappy Bird 复刻：它到底能帮你省掉哪段路

很多人第一次在 Xcode 里手搓 Flappy Bird，卡住的不是玩法，而是工程骨架：场景怎么切、物理体怎么挂、管道怎么循环、分数怎么存。这份 flappy bird（xcode）资源包，本质是一份可直接在 Xcode 里打开的完整工程，把「新建项目 → 搭场景 → 写碰撞 → 做循环 → 收尾」这条链路一次性铺好。它适合两类人：刚学完 Swift 语法、想找一个能跑起来的小项目练手的开发者，以及需要一份可改可拆的 2D 小游戏模板、拿去做课程作业或 Demo 的从业者。你拿到手不是一堆散装代码，而是一个能编译、能玩、能顺着改的起点，省掉的正是从零搭工程结构那段最耗耐心的路。

2. 工程结构与运行链路：先让它在模拟器里跑起来

2.1 打开工程前先确认的三件事

拿到一个 Xcode 工程，别急着点 Run。先看目录里有没有.xcodeproj或.xcworkspace，这决定了你是直接开工程还是先处理依赖。这份资源是纯原生工程，没有第三方包管理器介入，所以打开.xcodeproj即可。第二件事是看Deployment Info里的最低系统版本，如果它高于你本机模拟器的版本，编译会直接报错，常见做法是把iOS Deployment Target调到你能覆盖的区间。第三件事是确认Bundle Identifier没有和本机已装的 App 冲突，冲突时签名阶段会失败，改一个后缀就行。

我一般会先做一次「空跑」：不改任何代码，直接选一个 iPhone 模拟器编译。能起来，说明工程完整；起不来，错误信息会告诉你缺的是签名、SDK 还是资源文件。这一步的价值在于把「工程本身的问题」和「你改出来的问题」分开，后面调试时心里有底。

# 查看工程结构，确认入口与资源目录 find . -maxdepth 2 -name "*.xcodeproj" -o -name "*.xcworkspace" # 列出资源目录，确认图片、音效是否齐全 ls -R Assets.xcassets 2>/dev/null | head -40

上面两条命令一条定位工程入口，一条确认资源是否随包提供。-maxdepth 2是为了避免在深层目录里翻太久；head -40只是防止输出刷屏，实际排查时可以去掉。资源缺失是这类小游戏工程最常见的「能编译但画面空白」原因，先确认再谈逻辑。

2.2 场景、节点与游戏循环的分工

Flappy Bird 这类 2D 小游戏，结构上就三层：场景（Scene）负责生命周期，节点（Node）负责显示与物理体，游戏循环负责每帧推进。这份工程用的是 SpriteKit 的经典组织方式，GameScene承担主逻辑，didMove(to:)里做初始化，update(_:)里做逐帧更新，touchesBegan里处理点击。理解这个分工，你才知道该往哪加东西：加一只新鸟是加节点，改重力是改物理世界参数，改难度是改管道生成间隔。

物理部分靠SKPhysicsBody挂到节点上，配合categoryBitMask、collisionBitMask、contactBitMask三个掩码区分「鸟、管道、地面、分数线」。这三个掩码是新手最容易写乱的地方，写错的表现是鸟穿墙或者一碰就死。常见做法是给每类物体分配一个二进制位，用位移运算定义，再用按位或组合。

// 物理类别用二进制位定义，避免互相干扰 struct PhysicsCategory { static let bird: UInt32 = 1 << 0 // 0001 static let pipe: UInt32 = 1 << 1 // 0010 static let ground: UInt32 = 1 << 2 // 0100 static let score: UInt32 = 1 << 3 // 1000 } // 鸟：会与管道、地面发生碰撞，并检测与分数线的接触 bird.physicsBody?.categoryBitMask = PhysicsCategory.bird bird.physicsBody?.collisionBitMask = PhysicsCategory.pipe | PhysicsCategory.ground bird.physicsBody?.contactTestBitMask = PhysicsCategory.pipe | PhysicsCategory.ground | PhysicsCategory.score

这段的关键在三个掩码的语义差别：categoryBitMask是「我是谁」，collisionBitMask是「我会被谁弹开」，contactTestBitMask是「碰到谁会通知我」。鸟的collisionBitMask里不放score，是因为分数线只做检测不做物理阻挡；如果误放进去，鸟会在分数线上被弹一下，手感立刻变怪。管道和地面则要设置对应的categoryBitMask，否则碰撞判定不成立。

2.3 管道循环与难度曲线的实现位置

管道循环是这类游戏的核心机制：每隔固定时间生成一对上下管道，向左移动，移出屏幕后回收。工程里通常用一个SKAction序列完成「移动 + 移除」，再用Timer或update里的累计时间控制生成节奏。难度曲线不靠改移动速度，而是缩短生成间隔、加大管道间距的随机范围，这样玩家感知到的是「越来越密」而不是「越来越快」。

// 管道生成：间隔随分数收紧，间距随机 func spawnPipePair() { let gap = CGFloat.random(in: 120...180) // 上下管道间隙 let centerY = CGFloat.random(in: 200...500) // 间隙中心高度 // 上管道与下管道分别定位，注意锚点与屏幕坐标系 let topPipe = makePipe(height: scene!.size.height - (centerY + gap / 2)) let bottomPipe = makePipe(height: centerY - gap / 2) // 移动 + 回收，避免节点无限堆积 let move = SKAction.moveBy(x: -scene!.size.width - 100, y: 0, duration: 4.0) let remove = SKAction.removeFromParent() topPipe.run(SKAction.sequence([move, remove])) bottomPipe.run(SKAction.sequence([move, remove])) }

gap控制难度，centerY控制随机性，duration控制横向速度。三者要一起调：只缩gap会让游戏变成纯反应测试，只加随机centerY会让新手频繁撞墙。我的经验是把gap从 180 逐步收到 130 左右，duration保持在 3.5 到 4.5 秒之间，手感比较接近原版。回收用removeFromParent()而不是隐藏，是为了防止节点树越积越大导致帧率下滑，这一点在长时间游玩时特别明显。

3. 把玩法拆成可改的参数：物理、输入与状态机

3.1 重力、冲量与手感三件套

Flappy Bird 的手感几乎全由三个数决定：重力加速度、点击冲量、最大下落速度。工程里通常在didMove里设置physicsWorld.gravity，在点击回调里给鸟一个向上的速度或冲量。新手常犯的错是把冲量设得太大，鸟一飞冲天，或者重力太小，鸟飘着不掉，两种都会让游戏「不像」。

// 物理世界与鸟的初始参数 physicsWorld.gravity = CGVector(dx: 0, dy: -9.8) // 重力 bird.physicsBody?.allowsRotation = false // 禁止旋转，保持朝向 bird.physicsBody?.linearDamping = 0.0 // 不加空气阻力 // 点击：直接设速度比加冲量更可控 func flap() { bird.physicsBody?.velocity = CGVector(dx: 0, dy: 320) }

这里用「直接设速度」而不是applyImpulse，原因是设速度能保证每次点击的起跳高度一致，手感更稳定；冲量会受当前速度影响，连点时容易叠出不可控的高度。allowsRotation = false是为了避免鸟头朝下翻转，视觉上更接近原版。linearDamping归零则是让下落曲线干净，不被阻尼拖慢。这三个参数建议先照抄，跑起来后再微调dy的数值，每次改 20 左右，改太多会失去参照。

3.2 输入响应与游戏状态切换

小游戏的输入就一个点击，但状态不止一个：准备、进行中、结束。工程里一般用一个枚举管理状态，点击回调根据当前状态分流。准备态点击开始，进行态点击起跳，结束态点击重开。状态没管好，典型表现是「死了还能点着飞」或者「重开后分数没清零」。

enum GameState { case ready, playing, gameOver } var state: GameState = .ready override func touchesBegan(_ touches: Set<UITouch>, with event: UIEvent?) { switch state { case .ready: state = .playing startSpawning() flap() case .playing: flap() case .gameOver: resetGame() // 重置节点、分数、状态 state = .ready } }

状态机的价值在于把「什么时候能做什么」显式化。resetGame()里要清的不只是分数，还有残留的管道节点、鸟的位置与速度、生成计时器，漏一个就会出现「重开后管道还在飞」的玄学现象。我一般会在重置里把removeAllActions()和removeAllChildren()走一遍，再重建鸟和地面，虽然粗暴但不会留尾巴。

3.3 分数、最高分与本地持久化

分数逻辑本身简单：鸟通过一对管道加一分，撞到管道或地面结束。真正容易翻车的是最高分的存取。工程里通常用UserDefaults存最高分，键名固定，读取时给默认值 0。这里有个细节：加分要在「通过」时触发一次，而不是每帧都触发，否则分数会疯涨。

// 通过管道时加分，用节点标记防止重复计分 func didPassPipe(_ pipe: SKNode) { guard pipe.userData?["scored"] == nil else { return } pipe.userData = ["scored": true] score += 1 scoreLabel.text = "\(score)" if score > bestScore { bestScore = score UserDefaults.standard.set(bestScore, forKey: "bestScore") } }

userData在这里当「已计分」标记用，比额外维护一个数组轻量。UserDefaults的写入时机放在破纪录时，而不是每加一分都写，减少无谓的磁盘操作。读取最高分放在didMove里，给integer(forKey:)一个默认值，避免首次运行时拿到 0 以外的脏数据。这套写法不复杂，但能避开「分数重复加」和「最高分丢失」两个高频坑。

4. 避坑与排查：这类工程最容易翻车的五处

4.1 编译过了但画面全黑

现象是模拟器启动后只有黑屏，没有鸟也没有地面。原因多半是场景没有正确呈现，或者GameViewController里的scaleMode与场景尺寸不匹配。解决方式是检查presentScene的调用，确认scene.scaleMode = .resizeFill或.aspectFill与你的布局假设一致；再确认资源目录里的图片确实被 target 勾选，没勾选的图片不会进包。

4.2 鸟一碰管道就穿过去

现象是碰撞判定完全不生效。原因通常是某一方的physicsBody没设置，或者categoryBitMask与collisionBitMask没有交集。解决方式是逐类打印掩码值，确认鸟的collisionBitMask包含管道的categoryBitMask；同时检查管道节点是否真的挂了SKPhysicsBody，只设了尺寸没设物理体是常见疏漏。

4.3 管道越玩越卡

现象是玩一两分钟后帧率明显下降。原因是移出屏幕的管道只做了隐藏没有移除，节点树持续膨胀。解决方式是在移动动作后接removeFromParent()，并确认生成逻辑没有在每次点击时重复启动计时器。计时器重复启动会让生成频率翻倍，这也是「越玩越密」的隐藏原因。

4.4 重开后状态错乱

现象是游戏结束后点击重开，鸟的位置或分数不对。原因是重置函数只清了部分状态。解决方式是把重置拆成「清节点、复位变量、重建场景元素」三步，按顺序执行；状态枚举在重置完成后才切回.ready，避免重置过程中又被点击打断。

4.5 真机与模拟器表现不一致

现象是模拟器上正常，真机上帧率或手感不同。原因是模拟器与真机的渲染性能、屏幕刷新率存在差异，固定时长的动作在低帧率下会显得更快。解决方式是尽量用基于时间的更新而不是基于帧的计数，动作时长留出余量，并在真机上实测一遍再定参数。

5. 二次开发与验证：把模板改成你自己的小游戏

拿到这份工程，最值的用法不是原样跑一遍，而是把它当骨架改出一个自己的变体。我一般的改法是先动「视觉层」再动「规则层」：换鸟的贴图、换背景色、换管道样式，这一步只碰资源和节点初始化，风险低；确认画面正常后，再改gap、duration、重力这些参数，最后才动状态机和计分逻辑。顺序反了，一旦出问题你分不清是资源问题还是逻辑问题。

验证方面，我习惯用一张「参数-现象」对照表来定位改动效果，比盲调快得多：

这张表不是标准答案，而是给你一个「改哪个数看哪个现象」的索引。真正定参数时，我会连续玩五局，记录每局死因：撞上管道、撞下管道、落地，三种死因的比例能反推出是间隙问题还是重力问题。撞上管道多，说明起跳太高或间隙偏低；撞下管道多，说明重力偏大或间隙偏高；落地多，说明起跳不够。这个方法比盯着代码猜有效得多。

还有一个容易被忽略的点：把「最高分」和「当前分数」的显示节点与逻辑变量分开管理。显示归显示，变量归变量，中间用一次赋值同步。这样你以后想加「连击」「金币」之类的扩展，不会因为显示和逻辑耦合而牵一发动全身。从那以后我每次改这类小游戏，都强制先跑一遍「空工程编译 → 改视觉 → 调参数 → 真机验证」这条线，不跳步。希望帮到你。

本文还有配套的精品资源，点击获取