方块鸟冒险这个名字听起来像是Flappy Bird的换皮，但真要在Cocos Creator 2.x里把一个“点按跳跃 + 障碍碰撞 + 分数累积”的小游戏做成一套能直接复用的源码模板，里面牵扯的东西比大多数人想的多得多。这个模板项目解决的正是这样一个问题：怎么用最少的代码量，把休闲小游戏最核心的玩法循环、UI状态切换、素材资源管理、多端适配一次性打通。适合刚接触Cocos Creator的初学者用来理解游戏状态机，也很适合独立开发者拿来做快速原型验证，甚至可以直接在此基础上换美术、加道具、改数值，半天就能做出一个新玩法demo。
我最初拿到这套源码时大概翻了一遍，第一感觉是“结构比预期清爽”，第二感觉是“这里面的坑可能都替我先踩过了”。下面我就从玩法拆解、核心实现、复现步骤、排错实录这几个维度，把这套模板的里里外外讲透。
1. 模板整体设计与玩法拆解
1.1 核心玩法循环是怎么跑起来的
方块鸟的玩法循环一句话就能说清：玩家点击屏幕，小鸟获得一个向上的瞬时速度；松手或不做操作时，小鸟受重力影响持续下落；屏幕右侧不断生成带有空隙的管道，小鸟穿过空隙得分，碰到管道或地面即游戏结束。
这个循环看起来简单，但实现时要拆成几个独立模块才能保证后续改动灵活。模板把逻辑分成了四层：输入层负责接收触摸和鼠标事件，角色层只处理小鸟的位移和旋转表现，世界层管理管道生成、移动和回收，控制层则是一个全局状态机，统管开始、飞行中、死亡、结算这四个阶段。
我习惯把这种方式叫“单向依赖”：状态机可以调用角色和世界层的方法，但角色和世界层不反向引用状态机。这套源码基本遵循了这个原则，比如小鸟的物理模拟部分并不知道游戏当前是否结束，它只负责根据速度和重力去更新位置，而是否允许更新、是否要触发碰撞回调，由控制层在外部决定。
1.2 为什么方块鸟适合做成源码模板
休闲游戏千千万，但方块鸟这类玩法几乎是所有小游戏开发者的“必修课”，因为它覆盖了小游戏开发中所有常用能力点。
第一，它的交互只有“点按”这一个输入，这让输入系统可以做得非常干净，不需要考虑虚拟摇杆、拖拽、多点触控等复杂情况。第二，它的碰撞判定场景很典型：角色与管道之间的AABB检测、角色与地面的检测、角色超出屏幕上下边界的检测，这三种判定基本涵盖了2D小游戏的绝大多数碰撞需求。第三，它有明确的分数累积和游戏结束状态，天然需要一个可靠的状态机来处理UI切换和逻辑复位。第四，它还有无限生成的障碍物系统，这直接关系到对象池、内存复用、难度曲线设计，这些都是一款游戏能长期跑稳定的基本功。
把这几项能力都沉淀成一个源码模板，比单纯写一个游戏demo的价值高很多，因为你换一个玩法时，只需要保留状态机和对象池部分，替换掉角色和障碍生成逻辑就能复用一大部分代码。
1.3 设计分辨率与竖屏适配思路
模板选择的是竖屏720x1280的设计分辨率，这是目前休闲小游戏很常见的竖屏尺寸，尤其是微信小游戏平台，大部分手机用户习惯单手竖屏操作。选720x1280而不是更小的540x960，主要是为了适配主流手机的像素密度，同时给美术出图提供一个比较舒服的基准。
实际适配时使用Cocos Creator 2.x的Canvas组件，勾选适配高度，然后背景图按设计分辨率的比例制作，用Widget组件把背景四边固定到屏幕上。这样在屏幕比例接近16:9或者更长条的全面屏上，背景不会出现露出底边的情况。地面也是类似处理，只是地面本身需要水平滚动，所以它不会用Widget去锚定宽度，而是用两张首尾相接的图片循环位移。
关于全面屏适配我多说一句，很多新手直接把宽度适配也同时打开，结果画面左右被拉伸或者背景被裁切。模板只在竖屏下采用“适配高度+背景宽于屏幕”的方式，地面和背景图片本身留出了20%的横向冗余，这样即使屏幕宽度超过720的设计值，也不会露出边缘。这套处理比单纯依赖Widget的弹性布局要稳得多。
2. 核心实现原理与模块解析
2.1 玩家控制与重力模拟的取舍
模板里的小鸟控制没有使用Cocos Creator 2.x自带的物理引擎，而是自己写了一套轻量级的运动模拟。原因很简单：物理引擎对刚体碰撞、关节、力的模拟确实强，但方块鸟这类游戏需要的只是一个“重力加速度 + 点击冲量”，用物理引擎反而会带来两个问题。
第一个问题是碰撞回调的时序不稳定，物理引擎的接触回调发生在物理步进中，而游戏逻辑的更新可能在同一帧的不同时机读取位置，容易产生“明明碰到了管道但分数还是加上去了”的竞态问题。第二个问题是性能，虽然单个体物理引擎开销不大，但如果管道用刚体加碰撞体，几十个对象同时在场景里存在时，物理步进的开销会明显高于手动检测，特别是在低端安卓机上差距更明显。
模板的具体参数是这样的：重力加速度设为每帧多少会因为帧率不同而变化，所以它使用基于时间的公式，也就是每帧的位移增量等于速度乘以帧间隔时间。模板里小鸟的垂直速度初始为0，点击时速度设为每秒向上380像素，重力加速度为每秒每秒620像素。这个数值是配合720x1280分辨率调出来的，小鸟从屏幕底部飞到中间位置大概需要0.4秒，节奏足够轻快又不至于让人反应不过来。
2.2 管道生成与对象池的工程价值
管道系统的实现是模板里最值得反复看的部分。管道每隔一定时间间隔生成一组，每组包含上管道和下管道，中间留出固定高度的空隙。模板没有用简单的“生成后销毁”模式，而是用了一个对象池来复用管道节点，因为每1.6秒生成一次管道，一分钟要生成37组，如果不回收，十分钟游戏就会在场景里堆出370个节点，这对移动端设备的渲染和内存都是负担。
对象池的实现方式不复杂，维护一个数组，生成前先看池子里有没有空闲管道组，有就从池子里取出来重新设置位置和尺寸，没有才创建新的。管道移出屏幕左侧后，不是直接销毁，而是把节点设成不可见状态放回池子。这一做法的直接收益是游戏长时间运行后，场景节点数量稳定在20个左右，帧率不会越玩越卡。
管道之间的间距和移动速度也值得注意。模板在初始化时设定了基础速度每秒120像素，间距为1.6秒生成一组，也就是说管道在屏幕上的水平间距为192像素。当玩家得分超过10分后，速度逐步提升，最高到每秒220像素，但生成间隔会相应缩短，保证水平间距不会因为速度变化而变得太密或者太疏。
2.3 碰撞判定的三种场景与实现细节
模板里的碰撞检测有三种场景，代码上也做了区分。第一种是角色与上下管道的矩形碰撞，这是游戏失败的主要来源，采用AABB检测，即两个矩形的x轴区间和y轴区间是否同时重叠。第二种是角色与地面矩形碰撞，检测逻辑和管道一样，但处理上多了“如果角色的底部已经低于地面，就把角色位置强制拉回地面并立即进入死亡状态”的容错。第三种是角色超出屏幕顶部边界，这种情况不直接判死，而是给一个向上的速度减半的处理，避免玩家连续点击把角色顶出屏幕后瞬间摸不到节奏。
AABB检测在模板里没有用Cocos的Collider组件，而是直接读取节点的坐标和尺寸计算矩形范围。这里有一个细节，小鸟的实际碰撞矩形比图片显示尺寸要小一圈。模板里小鸟图片是60x60，但碰撞矩形只取46x46，上下左右各缩进7像素。这个设置必须做，不然玩家会感觉“明明没碰到管子却死了”。图片边缘往往有透明留白，碰撞矩形按图片全尺寸算的话，透明区域也算碰撞，体感会非常差。
2.4 游戏状态机与UI切换逻辑
状态机的核心是一个简单的状态枚举，包含Ready、Playing、Dead、Result四个状态。模板在UI层面只保留一个Canvas，通过节点的active属性来切换开始提示、分数显示、结算面板这三个UI块。这样做的好处是避免多个Canvas之间的事件穿透问题，也方便统一处理屏幕适配。
状态切换的关键在于“复位逻辑”。玩家死亡后点击结算面板的重玩按钮，需要把所有运行状态恢复成初始状态，包括归零分数、清空管道对象池里的所有活动管道、把小鸟放回初始位置、重置速度和重力参数。很多新手写重玩逻辑时只复位了部分变量，导致第二局开始时管道还残留、分数还在跳动，就是因为状态机和复位逻辑没有放到一个统一入口。
模板里专门提供了一个RestartAll循环复位，由状态机在收到重玩指令时统一调用。我在实际测试中验证过，连续重玩20次、每次玩到20分以上，场景节点数和内存占用都保持在稳定水平，没有出现明显的残留对象和计数错误。这一点对于模板类项目来说非常关键，因为别人拿去改的时候，最怕的就是复现你源码里的隐藏Bug。
3. 实操复现步骤与关键参数配置
3.1 创建工程与场景节点树搭建
如果你要从零搭建一个类似模板的工程，可以先按照下面这套步骤走一遍。我尽量按模板源码里的实际结构来还原。
第一步，在Cocos Creator 2.x里创建空工程，然后在项目设置里把设计分辨率改成竖屏720x1280。这一步一定在开发前就做好，因为后续所有节点坐标和资源尺寸都会围绕这个基准来设计，中途改分辨率大概率要重调一版。
第二步，创建场景Main，在Canvas下建立六个空节点：Background、Ground、PipeGroup、Bird、UI、GameController。Canvas需要开启适配高度，然后给Background节点添加一个Sprite组件，拖入一张背景图，尺寸建议做成本身宽900、高1280，这样即使用Widget把左右边缘固定到屏幕外侧，横向也不会露白。
第三步，搭建地面。地面节点下挂两个首尾相接的地面图片，两张图并排摆放，每张图宽度720、高度160。后续滚动动画就是对这两个子节点同时做x轴的平移，当其中一张完全移出屏幕左侧后，把它瞬间放到另一张的右侧。
第四步，创建小鸟节点，添加Sprite组件，并把锚点设为中心。模板默认小鸟是60x60的方形图片，为了后续旋转表现方便，节点原点在中心。
第五步，创建UI部分，用Label组件做三个文本：一个当前分数、一个最高分、一个结算面板上的最终分数。另外准备一张遮罩半透明图和两个按钮，一个“开始图标”一个“重玩按钮”，按钮用Button组件实现。
最终节点树我在下面列一个简表，方便对照检查。
| 节点名 | 组件 | 用途 |
|---|---|---|
| Canvas | Canvas、Widget | 屏幕适配根节点 |
| Background | Sprite、Widget | 背景显示 |
| Ground | 空节点 | 地面滚动容器 |
| PipeGroup | 空节点 | 管道生成与对象池容器 |
| Bird | Sprite | 玩家角色 |
| UI | 空节点 | 所有UI元素容器 |
| GameController | 自定义脚本 | 状态机与全局控制 |
3.2 玩家控制脚本Player.js逐步实现
在Bird节点上挂一个Player.js脚本。脚本里至少需要这几个属性：重力加速度、点击跳跃速度、当前垂直速度、是否锁定控制。我写一下核心逻辑的部分示意，重点是区分“不受控的坠落”和“玩家可操作的飞行”两个阶段。
cc.Class({ extends: cc.Component, properties: { gravity: 620, jumpSpeed: 380, borderPadding: 20 }, onLoad() { this.verticalSpeed = 0; this.isControlLocked = true; }, update(dt) { if (this.isControlLocked) return; this.verticalSpeed -= this.gravity * dt; this.node.y += this.verticalSpeed * dt; let halfHeight = this.node.height / 2; if (this.node.y > 1280 - halfHeight) { this.node.y = 1280 - halfHeight; this.verticalSpeed *= -0.5; } this.updateRotation(dt); }, handleJump() { if (this.isControlLocked) return; this.verticalSpeed = this.jumpSpeed; }, updateRotation(dt) { let targetAngle = cc.misc.clampf(this.verticalSpeed / this.jumpSpeed, -1, 1); let targetRotation = -45 + targetAngle * 90; this.node.rotation = cc.misc.lerp(this.node.rotation, targetRotation, 0.15); } });这里有几个细节值得展开。
先说旋转表现。模板为了让小鸟飞起来更生动，让它的机头仰角随着上升速度变化，下落时角度逐渐往下栽。这段代码用的是简单的插值，不是直接设置旋转值，这样每次点击后小鸟不会突然“咔”一下转过去，而是有一个快速但平滑的过渡，手感和视觉都自然得多。
再说屏幕顶部的反弹处理。很多方块鸟类游戏在顶部直接判死，但模板选择让小鸟速度减半弹回，这样做是故意的。因为玩家快速连续点击时，角色冲到屏幕顶部的频率很高，如果直接判死会让玩家觉得“明明还在飞怎么就死了”，体感像Bug。弹回处理虽然只是多做了几行代码，但对游戏体验的提升非常明显。
另外注意isControlLocked这个字段，它在Ready状态下是true，玩家无法通过点击让小鸟乱飞，只有状态机进入Playing后才会解锁。这种“输入锁”是模板类代码里很基本但很容易被忽略的设计，不加的话会出现第一局还没开始小鸟就飞走的情况。
3.3 管道生成器PipeSpawner.js的关键计算
管道生成器挂在GameController节点或者单独的PipeGroup节点上都可以，模板选择独立挂载，这样对象池逻辑可以单独复用。生成器的核心参数有三个：生成间隔、管道移动速度、空隙高度。
我推荐按下面这个思路来设置参数。空隙高度先定，模板是200像素，这个数值大约是小鸟尺寸的3.3倍，对普通玩家来说容错比较合理。移动速度定为120像素每秒，那么管道从屏幕右侧生成点到左侧消失点的距离大约是720加管道宽度再加两端冗余，约900像素，也就是说一组管道从出现到消失需要7.5秒。生成间隔1.6秒，所以屏幕上平均同时存在的管道组数是四到五组。这几个数字环环相扣，不能单独调一个而不考虑其他，否则要么管道太挤，要么屏幕太空。
管道生成后的位置设置是这样的：每组管道上下两根。上管道的底部边缘到下管道的顶部边缘之间留出200像素空隙，这200像素的垂直中心线在一定范围内随机偏移，偏移范围模板设为80像素到屏幕高度的35%之间。为了确保玩家不会遇到完全无法穿过的缝隙，模板额外做了一个约束：随机中心线的最高和最低位置不能超出屏幕上下各100像素的区间。
代码里还要处理“计分触发”的位置。模板没有设置真正的触发器，而是记录每组管道生成时的x坐标，当管道的x坐标小于小鸟的x坐标且该组管道的计分标记为false时，分数加一并把标记置true。这个逻辑在update里逐组检测，比用碰撞器做计分要省很多性能开销。
3.4 地面无限滚动与背景视差
地面滚动我上面提过，两张图并排往左移动。模板在这里用了一个小技巧，不是每一帧用代码设置position，而是干脆给地面容器挂一个组件，在update里对两个子节点的x坐标做累加。当某个子节点的x坐标小于负720时，把它移动到另一个子节点的右侧，也就是在共享变量lastRightX上加上720。这样做的好处是无论移动速度是快是慢，两张图永远首尾相接，不会出现缝隙。
背景部分模板做了一个轻微的视差处理。背景的滚动速度是地面速度的0.15倍，但方向相同，而且背景图片比屏幕宽很多，所以直接移动背景节点本身，不需要像地面那样做循环拼接。视差比例不宜设置过高，不然会让人产生眩晕感，15%这个数值是我见过比较舒服的档位。
移动速度统一由GameController里的speed属性控制，通过属性面板可以在编辑器里直接调。如果你想让难度曲线更陡，可以修改速度的递增公式，模板用的是每得一分速度提高1.5像素每秒，上限220。需要注意，速度提高后管道的生成间隔也要相应缩短，否则管道间距会越来越宽，难度反而下降。
4. 常见问题与排查技巧实录
4.1 碰撞判定不准：明明没碰到却死亡
这个问题几乎每个人都会遇到，根源多半在碰撞矩形上。我调试模板时曾经碰到过一个小鸟图片尺寸60x60，但图片本身四周有8像素透明留白的情况。直接用节点宽高去做AABB检测，透明留白也被算进去了，玩家会明显感觉到“还有空隙却被判定撞上”。
解决方法是给Player节点增加一个独立的碰撞框控制脚本，里面保存两个手动设置的偏移值，比如碰撞框为44x44，中心点比节点中心低2像素。计算AABB时用节点坐标加上偏移值后再计算，而不是直接读节点宽高。
4.2 微信小游戏上点击事件不响应
Cocos Creator 2.x在浏览器上触摸没问题，构建到微信小游戏后偶尔出现点击不响应的现象，原因是节点的触摸监听注册时机晚于场景加载，或者监听在了有穿透问题的UI节点上。模板在解决这个问题上做了两件事：第一，不依赖Button组件的点击事件来驱动游戏主循环，而是直接在Canvas节点上注册cc.Node.EventType.TOUCH_START事件；第二，在onLoad里就完成注册，而不是等到Ready动画播完后再注册。
如果你改模板时遇到了点击不响应，先确认你是否在某个被隐藏的节点上注册了事件，比如把监听挂在了结算面板上，而面板的active是false时监听也会失效。最稳的写法始终是挂到Canvas或GameController这类常驻节点上。
4.3 低端手机掉帧与物理引擎滥用的教训
模板最初的一个版本里管道、小鸟、地面都挂了Collider组件并启用了物理引擎，结果在五六年前的安卓手机上帧率不太稳定，尤其是管道同时存在五组以上时，物理步进时间明显拉长。后来我把所有碰撞检测改成手动AABB计算，小鸟和管道不再依赖物理组件，帧率立刻稳定在60帧左右。
这个改动带来的另一个额外收益是调试变得更加直观，你可以随时在节点上显示碰撞矩形，也可以暂停update一帧一帧检查碰撞结果。物理引擎适合做复杂交互，像方块鸟这种只需要矩形判定的玩法，手动计算永远是更优解。
4.4 重玩第二局分数残留
重玩时分数没清零、管道还剩在屏幕上的问题，几乎都是因为复位逻辑没有走到位。模板的RestartAll函数按固定顺序执行了三步：先停止所有移动逻辑并清空活动管道列表，再把分数归零并更新UI，最后才把小鸟复位并解锁输入。这个顺序很重要，颠倒任何两步都可能导致回调里读到旧状态。
我见过有不少人把清空管道和重置小鸟写在两个不同的函数里，然后在重玩按钮的回调里分两次调用。这样做非常容易漏，因为你下次加内容时可能只记得调用其中一个。模板的做法是在GameController里只提供一个重玩入口方法，所有复位逻辑都在这个入口内按固定顺序执行，其他地方一律禁止直接操作游戏对象。
4.5 帧率波动导致速度不稳的修正
如果移动速度是每帧固定减一个常量，那么帧率高时游戏会“加速”，帧率低时游戏会“减速”，体验差异很大。Cocos Creator 2.x的update回调会传入dt，模板里所有速度相关的位移都用dt做了修正，包括地面滚动、管道移动、小鸟上升下降。判断标准很简单：任何与速度相关的数值变化都必须乘以dt，任何与时间间隔相关的逻辑都用schedule计时器而不是自己累积帧数。
如果你在自己的项目里发现帧率波动时游戏一会儿快一会儿慢，就用这个原则去排查一遍所有update里的位移代码。我调试时遇到过因为一个对象的x坐标忘了乘以dt，导致其他所有对象看起来都在正确移动，只有那个对象像“闪现”一样跳动的情况。
4.6 常见问题速查表
| 现象 | 原因 | 解决方法 |
|---|---|---|
| 碰撞判定偏大 | 碰撞矩形沿用图片全尺寸 | 手动设置碰撞框并加偏移 |
| 点击无反应 | 事件注册在隐藏节点上 | 把触摸事件挂到Canvas常驻节点 |
| 重玩后残留管道 | 复位逻辑未统一入口 | 在GameController中提供RestartAll统一调用 |
| 帧率波动影响速度 | 位移未乘以dt | 所有速度相关运算乘上帧间隔时间 |
| 屏幕左右露白 | 适配宽高设置不当 | 只适配高度，背景宽度预留冗余 |
| 截图时小鸟旋转角度怪异 | 旋转插值目标值不收敛 | 使用clamp和lerp做角度过渡 |
5. 源码结构与工程化扩展建议
5.1 模板源码的目录组织方式
模板源码的assets目录用了按功能划分的文件夹结构：Prefabs下放小鸟和管道的预制体，Scripts下放Player、PipeSpawner、GameController、GroundScroll等脚本，Scenes下放主场景，Textures下按背景、地面、管道、UI分子目录存放图片资源。Audio文件夹单独放音效。
这种按功能划分的方式对模板来说比按层划分更合适，因为使用者经常要整体替换某一类资源，比如换一套UI皮肤，直接把Textures/UI整个文件夹替换掉就行。如果你的项目要长期迭代，可以在这个基础上再按模块拆分子目录，比如Bird目录下同时放小鸟图片、小鸟脚本、小鸟动画，内聚性更高。
模板里没有把脚本都挂到场景的同一个节点上，而是分散挂到对应的控制节点上。这个设计对学习更友好：你打开场景就知道小鸟节点管玩家操作，管道节点管生成器逻辑。如果你把脚本全部堆到GameController上，虽然代码集中了，但场景里的节点结构会失去直观性，改起来反而费劲。
5.2 从模板到完整小游戏的扩展路径
模板只提供最基础的功能，如果你想往里面加内容，我建议按优先级来做。
先加音效系统，用AudioSource组件挂到GameController上，在小鸟跳跃、得分、死亡三个时机播放不同音频。音效这块需要注意微信小游戏平台的音频文件格式要求，最好统一用m4a或mp3，并且控制单个音频文件大小，避免加载耗时过长。
再加道具系统。最常见的道具是磁铁和护盾，磁铁可以让小鸟靠近管道间隙时自动吸附到中心线，护盾可以抵挡一次碰撞。道具的实现要改的地方主要是碰撞检测逻辑和状态机，护盾生效期间标记一个布尔值即可。不建议把道具做成独立物理体，否则和手动AABB检测的框架就冲突了。
最后可以加一个简单的分享功能。微信小游戏的分享入口可以放在结算面板上，分享时带上当前分数。实现上只需要在小游戏适配层调用平台提供的分享接口，模板代码里留好了命名空间方便扩展。
5.3 构建与发布的平台配置
模板默认构建目标是微信小游戏，因为休闲小游戏的主要流量就在这个平台。构建前需要打开项目设置里的“模块设置”，确认勾选了Canvas、Sprite、Label、Button这些基础模块，去掉3D、物理、Spine这些用不到的模块，可以明显减小包体。
微信小游戏有主包体积限制，模板图片不多时一般不会有问题，但如果换了一套高清美术素材，建议把背景图和音频放到分包或者远程资源列表里。Cocos Creator 2.x的资源远程加载需要把资源标记为Remote Bundle，然后在代码里通过cc.assetManager加载，这部分模板里预留了一个简单的资源管理器脚本，你可以参考它的写法去扩展。
高分榜功能如果要长期保存，可以用本地缓存存储一个最高分变量。模板里默认用本地存储保存最高分，每次游戏结束对比当前分与存储值并更新。如果你后续要做排行榜，可以在这个基础上对接后端接口，把本地变量的读写替换成树结构数据接口的调用。
写在最后的小经验
这套模板最值得学习的部分不是某段代码写得多么巧妙，而是它把“无限循环小游戏”的工程骨架搭得非常清楚。我在实际测试中试过改它的状态机来支持双难度模式，也试过替换成飞机躲避子弹的玩法，真正需要大改的只有角色控制逻辑和碰撞对象类型，其他部分基本没动。方块鸟这个品类看起来小，但它把输入、碰撞、对象池、状态机、UI切换、平台适配全都串了一遍，能把这套逻辑吃透，再去做飞行射击、跑酷、跳跃过关，上手速度会快很多。如果你们真想拿这套源码做点什么，我的建议是先不动代码，照着场景把节点树画一遍，再把每段脚本的update都捋一遍，最后再考虑改玩法。等你把这条链路跑通了，这个模板就真的变成你自己的武器了。
