简介这份压缩包围绕 cocos2d-x 实现糖果消除类游戏面向希望练手三消玩法、熟悉二维游戏开发流程的初学者与中级开发者。内容以完整工程源码为核心配合可直接运行的程序、工程文件以及糖果贴图、配置表和字体等美术资源便于对照理解棋盘布局、相邻糖果交换、三连及以上消除判定、消除动画反馈、计分规则与关卡状态管理等基础模块。整包共四十三个文件以 C 源码与头文件、图像素材、动态链接库、配置表和字体为主压缩后约三点四六兆体积轻便适合在本地编译调试、运行验证或拆解学习。已有二百一十人学习浏览可作为 cocos2d-x 二点二点六版本下三消游戏原型的参考样例也能为后续扩展特殊糖果、道具系统与关卡设计提供可复用的代码骨架和排错思路。1. 三消棋盘看着规整真正动手改才知道坑在坐标上三消游戏的棋盘看着规整真正动手改才知道坑在坐标上。接触过一份用 cocos2d-x 写的三消工程跑起来第一感觉是「能玩」元素能点、能换、能消、能掉分数往上跳连锁还会顿一下再消下一波一个最小可玩的闭环是完整的。它干的事说起来不复杂——初始化棋盘保证不出三连点击或拖拽判定相邻交换交换有解就消除、下落、补新元素一路连锁到没有可消为止走不动了就重排。但拿 C 和 Action 队列把这条链路串起来同时不出现重复消除、动画比逻辑慢半拍这类问题是另一回事。这套工程适合两类人一类是想学 cocos2d-x 但不想啃引擎源码的棋盘逻辑就是最好的练手场另一类是手里已经有个三消原型想看看别人的棋盘数据结构和动画编排怎么写的。下面的内容按「结构 → 数据 → 动画 → 踩坑 → 改造」走一遍。2. 工程结构与启动链路从 AppDelegate 到 GameScene 到底走了几步cocos2d-x 项目的目录结构基本是引擎定好的想改也改不出花样但每个目录里放什么、哪些代码该抽出 Layer、哪些不该直接决定后面加关卡时你改一处还是改五处。这份工程的分法比较克制没有搞 ECS也没有搞组件化就是老老实实按「引擎入口 场景 棋盘 数据」四层切。2.1 目录怎么分Classes、Resources 与平台工程三块先看 Classes 这一层它决定了你打开工程后先读哪个文件Classes/ AppDelegate.h/.cpp # 引擎入口GLView、图集预加载、启动场景 GameScene.h/.cpp # 场景层分层、触摸、HUD 更新 Board.h/.cpp # 棋盘逻辑生成、交换、消除、下落、重排 Tile.h # 纯数据结构类型、行列、精灵指针 LevelData.h/.cpp # 关卡配置读取目标分数、步数、元素种类 Resources/ res/tile.plist tile.png # 元素图集所有元素共用一张图 res/ui/ # 分数条、步数、结算面板 res/sound/ # 交换、消除、连锁音效 proj.android/ proj.ios_mac/ # 平台工程一般不改Board 单独抽出来是有原因的。三消最容易写崩的地方就是「逻辑状态」和「表现状态」搅在一起——Sprite 一边在播下落动画逻辑数组已经被改掉了下一轮扫描就会出现同一个元素被消两次。把 Board 做成不依赖任何 Sprite 的纯数据类GameScene 只负责「把 Board 的变化翻译成动画」这个问题从结构上就被掐掉了大半。资源这边元素图集必须打成 plist png。13 种元素如果各自一张图一轮连锁下来几十个 Sprite 各自一次纹理切换draw call 直接起飞低端安卓机上肉眼可见地掉帧。打成图集后同一批 Sprite 共享一次纹理绑定是这套工程在中低端机上还能跑顺的主要原因。提示图集别按「一个元素一张大图」的思路做元素尺寸小、数量多2 的幂次方排布、留 2px 内边距防采样串色就够了。2.2 启动链路AppDelegate 里三件必须做对的事引擎入口是所有 cocos2d-x 项目的第一个交叉点写错这里后面全是玄学问题bool AppDelegate::applicationDidFinishLaunching() { // 1. 拿导演初始化 GLView分辨率要和设计分辨率对齐 auto director Director::getInstance(); auto glview director-getOpenGLView(); if (!glview) { glview GLViewImpl::create(Match3); glview-setFrameSize(960, 640); // 设计分辨率不是窗口像素尺寸 director-setOpenGLView(glview); } director-setContentScaleFactor(1.0f); // 2. 预加载图集必须在任何 createWithSpriteFrameName 之前 SpriteFrameCache::getInstance()-addSpriteFramesWithFile(res/tile.plist); // 3. 只创建一次场景并交给导演跑 auto scene GameScene::create(); director-runWithScene(scene); return true; }三行关键调用各自对应一个常见翻车点。setFrameSize给的是设计分辨率不是手机实际像素分辨率策略在glview-setDesignResolutionSize()里另配两者混用会导致棋盘在不同机型上偏一边。图集加载必须早于任何createWithSpriteFrameName否则拿到的是空指针——cocos2d-x 不会报错只是画面上什么都没有新手最容易在这里怀疑人生。第三步的runWithScene只对第一个场景用之后切换一律走replaceScene// 结算后回主菜单用带过渡的场景切换避免黑一帧 auto next MenuScene::create(); Director::getInstance()-replaceScene(TransitionFade::create(0.3f, next));TransitionFade的第一个参数是过渡秒数0.2 到 0.3 之间比较自然超过 0.5 玩家会觉得卡了一下。2.3 场景内分层背景、棋盘、HUD 与触摸谁先谁后棋盘层的组织方式决定了触摸有没有响应、HUD 会不会被压在棋盘下面bool GameScene::init() { if (!Layer::init()) return false; auto bg Sprite::create(res/bg.png); bg-setPosition(Vec2(480, 320)); addChild(bg, 0); // zOrder 0背景垫底 _boardLayer Layer::create(); addChild(_boardLayer, 10); // zOrder 10棋盘触摸事件挂在这一层 _hudLayer Layer::create(); addChild(_hudLayer, 20); // zOrder 20分数、步数、结算面板 auto listener EventListenerTouchOneByOne::create(); listener-setSwallowTouches(true); // 吞掉事件避免穿透到下层 listener-onTouchBegan CC_CALLBACK_2(GameScene::onTouchBegan, this); listener-onTouchEnded CC_CALLBACK_2(GameScene::onTouchEnded, this); _eventDispatcher-addEventListenerWithSceneGraphPriority(listener, _boardLayer); return true; }zOrder 是分层顺序数字越大越靠上。触摸监听器用addEventListenerWithSceneGraphPriority绑定到_boardLayer上意味着这一层被移除时监听器自动跟着销毁不用手动removeEventListener——这一点在反复进出关卡时非常关键否则监听器会越积越多一次点击触发三四次交换。setSwallowTouches(true)是另一条血泪经验。不吞事件的话点击棋盘的同时下层的背景层或者关卡的按钮也可能收到触摸表现为「点一次消两次」。吞了之后这一层就是黑匣子外面谁也别想拿到。3. 棋盘数据结构一个二维数组怎么撑起整局玩法棋盘是整局游戏唯一的状态源。这份工程里 Board 只做三件事生成、交换、结算。表现层从头到尾只读它不改它。这条边界守住了后面加关卡、加特殊元素都不会互相牵扯。3.1 Tile 结构与初始化生成时就要掐掉三连Tile 是个非常轻的结构逻辑字段和表现指针分开static const int kRows 8; static const int kCols 8; static const int kTypeCount 6; // 元素种类数直接影响难度 struct Tile { int type -1; // -1 表示空位0..kTypeCount-1 是正常元素 Sprite* sprite nullptr; }; std::vectorstd::vectorTile _grid; // 访问方式 _grid[row][col]用-1表示空位是刻意设计。结算过程中会出现「中间被消掉、上面还没落下来」的瞬时状态如果只用 type 有效值表示那这个瞬间在数据上就是合法的完整棋盘下一轮扫描会把它当成真实棋盘处理。留一个空位值扫描函数自然就会跳过。初始化时直接避免三连比生成完再检测重排省事得多int Board::pickType(int row, int col) { std::vectorint banned; // 左侧已经有两个同类就禁掉这一类型 if (col 2 _grid[row][col-1].type _grid[row][col-2].type) banned.push_back(_grid[row][col-1].type); // 上方已经有两个同类同理 if (row 2 _grid[row-1][col].type _grid[row-2][col].type) banned.push_back(_grid[row-1][col].type); int t 0, guard 0; do { t RandomHelper::random_int(0, kTypeCount - 1); } while (guard 50 std::find(banned.begin(), banned.end(), t) ! banned.end()); return t; // guard 兜底防止类型数过少时死循环 }guard那个计数不是多余。当kTypeCount被调到 3 的时候banned 很可能同时包含三个类型理论上无解do-while会永远转下去——游戏在进入关卡那一刻直接卡死。加一个上限最坏情况退化成允许一次三连总比卡住强。这也是后面加关卡时最容易忽略的参数关卡配置改元素种类一定要顺手验一遍这个下限。3.2 交换判定先算数据再播动画触摸换算成行列是第一个容易错的地方。cocos2d-x 坐标系原点在左下角、y 轴向上而棋盘习惯从左上角数行这里必须翻一次bool GameScene::onTouchBegan(Touch* touch, Event* event) { Vec2 p _boardLayer-convertTouchToNodeSpace(touch); // _origin 是棋盘左上角在 _boardLayer 中的坐标 int col static_castint((p.x - _origin.x) / kTileSize); int row static_castint((_origin.y kRows * kTileSize - p.y) / kTileSize); if (row 0 || row kRows || col 0 || col kCols) return false; _selected {row, col}; return true; }convertTouchToNodeSpace把屏幕坐标转成节点局部坐标这一步不能省直接用touch-getLocation()会在棋盘层有位移时全部错位。行列算完后必须做边界校验否则点到棋盘外面的留白也会被当成合法格子后面交换时数组越界直接崩。按下和抬起是两个格子时才走交换void GameScene::onTouchEnded(Touch* touch, Event* event) { auto second toGrid(convertTouchToNodeSpace(touch)); if (second _selected) return; // 原地点击不处理 if (!isAdjacent(_selected, second)) return; // 不相邻不处理 if (board-canSwap(_selected, second)) { board-swap(_selected, second); // 先改数据 playSwapAnim(_selected, second, true); // 再播动画 } else { playSwapAnim(_selected, second, false); // 换回去的动画 } }顺序很重要先改数据再播动画。反过来的话动画播到一半玩家又点了一下逻辑和数据就对不上了。canSwap里做的是交换后跑一次匹配检测有匹配才算有效交换否则弹回原位——这也是三消里「无效交换」的标准处理方式。3.3 消除与下落一次扫描跑完整条链路匹配检测用标记数组而不是边扫边删void Board::findMatches(std::vectorstd::vectorbool mark) { // 横向扫描 for (int r 0; r kRows; r) { int run 1; for (int c 1; c kCols; c) { bool same (c kCols _grid[r][c].type 0 _grid[r][c].type _grid[r][c-1].type); if (same) { run; } else { if (run 3) for (int k c - run; k c; k) mark[r][k] true; run 1; } } } // 纵向扫描逻辑与横向一致只是行列互换 }mark是kRows × kCols的布尔矩阵。不直接删的原因是一个元素可能同时处在横向三连和纵向 T 型交叉里边扫边删会让第二次扫描读到已经被清空的格子判定就乱了。先全部标记、再统一清空一次结算只跑一遍逻辑干净。下落用双指针从底往上扫把空位压缩到顶部void Board::dropDown() { for (int c 0; c kCols; c) { int writeRow kRows - 1; // 从最底下一行开始写 for (int r kRows - 1; r 0; --r) { if (_grid[r][c].type 0) continue; // 空位直接跳过 if (r ! writeRow) { _grid[writeRow][c] _grid[r][c]; // 元素往下落 _grid[r][c].type -1; // 原位置置空 } --writeRow; } // writeRow 以上全是新补的元素 for (int r writeRow; r 0; --r) { _grid[r][c].type RandomHelper::random_int(0, kTypeCount - 1); } } }这个双指针写法的好处是移动次数最少每个元素只被搬一次。如果按行逐格往上找同类往下拉写出来的代码会长一倍还容易在「连续三个空位」这种边界上算错偏移量。补新元素时不要在这里做三连规避否则一次下落补完全部合法后面的连锁就没得玩了——连锁感正是从这里来的。4. 动画与连锁节奏三消的手感是在这几十行里定下来的逻辑跑通只说明这游戏能玩能不能玩得下去看的是动画节奏。三消的爽点很大一部分来自「消掉的瞬间有反馈、掉落有停顿、连锁有递进」这三件事全是 Action 编排的事。4.1 Action 编排MoveTo 和 CallFunc 的顺序不能乱交换动画的标准写法是一去一回中间插入回调void GameScene::playSwapAnim(const GridPos a, const GridPos b, bool keep) { auto spA _grid[a.row][a.col].sprite; auto spB _grid[b.row][b.col].sprite; auto moveA MoveTo::create(0.12f, posOf(b)); // A 移动到 B 的位置 auto moveB MoveTo::create(0.12f, posOf(a)); if (keep) { // 有效交换两个精灵同时移动结束后不处理 spA-runAction(EaseSineOut::create(moveA-clone())); spB-runAction(EaseSineOut::create(moveB-clone())); SimpleAudioEngine::getInstance()-playEffect(sound/swap.mp3); } else { // 无效交换来回一趟再归位用 Sequence 串起来 auto back Sequence::create( moveA, MoveTo::create(0.12f, posOf(a)), nullptr); auto back2 Sequence::create( moveB, MoveTo::create(0.12f, posOf(b)), nullptr); spA-runAction(EaseSineOut::create(back)); spB-runAction(EaseSineOut::create(back2)); } }EaseSineOut是缓动函数让元素起手快、收尾慢比线性移动柔和得多。这个细节看着小但把整局的MoveTo换成线性之后手感会立刻从「有人做过的游戏」掉成「Demo」。持续时间 0.12 秒是试出来的低于 0.08 玩家看不清在换什么高于 0.2 又觉得拖沓。CallFunc是这类动画里最容易翻车的地方。在动画结束的CallFunc里改棋盘数据然后立刻发起下一轮resolve看上去很顺实际会在低帧率设备上出问题——CallFunc是在该节点的 Action 更新里触发的此时同一帧的其他节点动作还没走完紧接着resolve读到的状态就是半新半旧的。稳妥做法是数据先改完、再去播动画CallFunc里只负责清理和推进状态机。4.2 连锁用状态机推不要写递归连锁消除最直觉的写法是递归——消完检测、有就再调自己。但这个写法在一轮五连的时候会把调用栈压到十几层而且递归里没法优雅地插入「等一下再消」这种节奏控制。工程的写法是一个显式状态机void GameScene::resolveStep() { std::vectorstd::vectorbool mark(kRows, std::vectorbool(kCols, false)); board-findMatches(mark); if (board-isAllFalse(mark)) { _state State::Idle; // 没有可消的回到可操作状态 checkDeadLock(); // 顺便查一次死局 return; } _combo; updateComboLabel(_combo); // 连锁数越高飘字越大 playClearAnim(mark); // 播消除动画0.2 秒 board-clearMarked(mark); // 数据层立刻清空 board-dropDown(); // 立刻下落 playDropAnim(); // 下落动画 // 关键延迟再进下一轮给动画留出时间 scheduleOnce(CC_SCHEDULE_SELECTOR(GameScene::resolveStep), 0.28f); }_combo在每次进入resolveStep且检测到匹配时累加回到Idle时清零。连锁数和分数倍率挂钩也是音效音调上浮的依据——很多三消的「爽」就是从这两处来的。scheduleOnce的 0.28 秒是整个节奏的核心参数。它必须大于消除动画和下落动画的总时长否则会出现「上一波动画还在播下一波已经开始消」的鬼畜画面。这个值在 0.22 到 0.35 之间调整调小了画面打架调大了连锁拖沓。注意scheduleOnce的回调里不要判空场景。玩家在连锁过程中点了返回场景被replaceScene销毁但延迟回调仍可能触发一帧访问已释放的成员是必崩的。4.3 死局检测与重排不能让玩家卡在没有走法的棋盘上没有可行交换的棋盘是个死局玩家点半天没反应会直接判定游戏坏了。检测方式很朴素枚举所有相邻交换换完跑一次匹配bool Board::hasPossibleMove() { for (int r 0; r kRows; r) { for (int c 0; c kCols; c) { // 只往右和往下试避免重复 if (c 1 kCols _trySwapHasMatch(r, c, r, c 1)) return true; if (r 1 kRows _trySwapHasMatch(r, c, r 1, c)) return true; } } return false; } bool Board::_trySwapHasMatch(int r1, int c1, int r2, int c2) { std::swap(_grid[r1][c1].type, _grid[r2][c2].type); bool ok _matchAt(r1, c1) || _matchAt(r2, c2); // 只查交换的两个点 std::swap(_grid[r1][c1].type, _grid[r2][c2].type); // 换回来纯查询不改状态 return ok; }8×8 的棋盘一共 112 次相邻判定每次只查两个点的四邻域在手机上耗时不到一毫秒放在结算的最后一帧跑完全没问题。真的发现无解就整套重排void Board::reshuffle() { do { for (int r 0; r kRows; r) for (int c 0; c kCols; c) _grid[r][c].type pickType(r, c); } while (!hasPossibleMove() || hasAnyMatch()); // 既要有走法又不能自带三连 }这里的do-while理论上有极小概率转很多次但 6 种元素、8×8 的规模下实际几乎一轮就过。真要保险可以加个迭代上限超了就换一套元素配置再试。5. 避坑排查这套三消最容易翻车的五个地方下面五条是我在这类工程里真实撞过的每条都能复现。5.1 真机上点不准往左上偏现象模拟器上点哪消哪打到手机上整体往左上偏半个格子越往右下偏得越狠。原因棋盘层挂了一个缩放或位移动画比如入场时的ScaleTo触摸换算还在用设计分辨率下的固定偏移_origin被写死成常量没有跟着节点变换走。解决一律用_boardLayer-convertTouchToNodeSpace(touch)取局部坐标_origin也从节点当前的getPosition()和getContentSize()推别写死。5.2 第一次进关卡明显卡一下现象启动到主菜单很顺一点「开始」进入棋盘画面停半秒才出来。原因图集、音效都是在GameScene::init()里当场加载的第一次进关就得同步读几十兆资源主线程直接堵住。解决图集在AppDelegate里预加载音效预加载走SimpleAudioEngine::preloadEffectGameScene里只取缓存。切场景用TransitionFade也能把这段等待藏掉一部分。5.3 元素被消了两次分数虚高现象偶尔一次 T 型消除同一批元素音效播两遍分数按两倍算。原因消除逻辑放在动画的CallFunc里执行两个 Sprite 的动画各自回调一次同一个mark区域被处理了两遍。解决数据处理和动画彻底解耦。findMatches出mark之后立刻clearMarked之后再统一播动画CallFunc里只做状态推进不再改棋盘。5.4 精灵帧名字拼错模拟器不炸真机炸现象电脑上跑着好好的打包上手机后某个元素显示成白色方块日志里什么都没有。原因createWithSpriteFrameName(tile_0.png)里的名字和图集里实际的帧名差一个大小写或者后缀。找不到帧时返回的 Sprite 是空尺寸不报错。解决图集帧名统一在一个const char* kFrameNames[]数组里维护加载完图集后用SpriteFrameCache::getInstance()-isSpriteFramesWithFileLoaded()自查一遍缺了就断言断在启动阶段。5.5 反复进出关卡内存一路涨现象进出关卡十几次内存曲线持续上扬低端机最终被杀。原因Sprite加进节点树后被父节点持有但音效、粒子、CallFunc里捕获的对象还挂在调度器上。场景被replaceScene后回调没清节点被释放时回调访问野指针。解决所有延迟回调在onExit()里用unscheduleAllCallbacks()清一次EventListener用addEventListenerWithSceneGraphPriority绑定到节点上随节点一起销毁不要手动retain。6. 二次开发加元素、换关卡、改判定拿到这套工程之后最常被改的三处是元素种类、关卡配置和匹配规则。加一种新元素改动点其实只有两个常量和一个数组// 1. 元素种类 1同时确认 kTypeCount 4否则 3.1 的 guard 会频繁兜底 static const int kTypeCount 7; // 2. 帧名数组按索引对齐顺序必须和图集里一致 const char* kFrameNames[] { tile_red.png, tile_blue.png, tile_green.png, tile_yellow.png, tile_purple.png, tile_orange.png, tile_rainbow.png }; // 3. Board::pickType 无需改动banned 逻辑自动适配关卡配置建议外置成 jsonLevelData只负责读bool LevelData::load(const std::string file) { auto content FileUtils::getInstance()-getStringFromFile(file); if (content.empty()) return false; rapidjson::Document doc; doc.Parse(content.c_str()); if (doc.HasParseError()) return false; _targetScore doc[targetScore].GetInt(); _moveLimit doc[moveLimit].GetInt(); _typeCount doc[typeCount].GetInt(); // 每关可以不同难度梯度全靠它 _colors.clear(); for (auto c : doc[colors].GetArray()) _colors.push_back(c.GetInt()); return true; }字段含义调整影响targetScore三星目标分直接决定关卡时长moveLimit步数上限和分数一起决定挫败感typeCount本关元素种类越多种越难消连锁概率低colors启用哪些元素可以用来做主题关加特殊元素比如四连生成炸弹是另一条路改动集中在findMatches之后扫到 run 长度等于 4 时不清这一组而是在中心格写一个特殊 type匹配时额外触发一次十字消除。我的建议是先只做一行消除跑通「特殊元素生成 → 触发 → 再次进入结算」这条链路再往上叠不要一上来就写五种特殊元素。从那以后我每次改棋盘逻辑都强制让一次三连、一次四连加一次连锁在同一局里跑一遍确认分数、步数、棋盘数组三者对得上才收工。这套工程的骨架不复杂改坏它的方式却很多希望你少走几步弯路。本文还有配套的精品资源点击获取
