1. 项目概述从零到一用Cocos Creator打造一款免费麻将游戏最近有不少朋友在后台私信问我有没有用Cocos Creator做棋牌类游戏的实战教程特别是麻将这种规则复杂、逻辑严谨的项目。正好我之前为了研究引擎的UI系统、状态管理和网络同步自己动手写过一个本地单机版的麻将游戏。整个过程踩了不少坑也积累了一些心得今天就把这个项目的核心思路、关键实现和避坑经验整理出来分享给大家。这个教程的目标很明确不依赖任何付费资源或插件完全基于Cocos Creator 3.x版本从零开始构建一个可运行的2D麻将游戏原型。麻雀虽小五脏俱全它会涵盖洗牌发牌、手牌管理、吃碰杠胡等核心规则判定、基本的AI出牌逻辑以及完整的UI交互。无论你是刚接触Cocos Creator想找个综合项目练手还是对棋牌游戏逻辑实现感兴趣这个教程都能给你提供一个清晰的实现路径。我会尽量把每个步骤背后的“为什么”讲清楚而不仅仅是贴代码让你知其然更知其所以然。2. 项目整体架构与核心模块设计在动手写第一行代码之前花点时间想清楚整体架构是至关重要的。对于麻将游戏我们不能一上来就埋头写胡牌算法那样很容易陷入逻辑混乱。我的设计思路是**“数据驱动状态分离”**将游戏分解为几个高内聚、低耦合的模块。2.1 核心模块划分与职责我把整个游戏分为五个核心模块它们之间的依赖关系是单向或松耦合的便于独立开发、测试和调试。数据模型模块这是游戏的心脏。它不关心画面如何显示只负责维护游戏的核心数据状态。主要包括MahjongData: 全局游戏数据单例管理牌墙剩余的牌、当前回合、玩家方向等。PlayerData: 玩家数据类存储手牌列表、碰杠牌组、状态是否听牌、胡牌等。MahjongTile: 单张麻将牌的数据对象包含其唯一ID、花色万、条、筒、字牌、点数、以及一个用于逻辑判定的“逻辑值”。比如“一万”的逻辑值可以是101“东风”可以是401这样便于后续的排序和计算。注意这里“逻辑值”的设计是关键。不要用纹理名称或精灵帧名作为判断依据而应该用一个独立的数字或枚举来代表牌型渲染层再根据这个值去匹配对应的图片资源。这是数据与视图分离的第一步。游戏逻辑控制器这是游戏的大脑。它接收UI或网络传来的操作指令调用数据模型进行计算并更新游戏状态。核心类是GameController它是一个常驻节点负责流程控制开局洗牌、发牌、通知玩家操作、判定吃碰杠胡的有效性、驱动AI逻辑等。UI视图模块这是游戏的脸面。它严格遵循MVC或MVVM模式中的“V”只负责显示。每个UI组件如手牌区、打出牌区、操作按钮面板都监听数据模型或控制器的状态变化然后更新自己的显示。例如HandTileView组件会监听所属PlayerData的手牌列表变化动态创建或销毁牌节点。AI玩家模块为了让单人可玩一个简单的AI是必要的。AIPlayer模块会模拟一个玩家的思考过程。它的核心是一个makeDecision()方法根据当前手牌、河里的牌其他玩家打出的牌以及基本麻将策略如优先听牌、避免点炮来决定是摸牌、打牌还是进行吃碰杠操作。初期可以实现一个基于规则的简单AI后期可以引入概率模型。资源与配置管理麻将牌面图片、音效、动画等资源需要统一管理。同时游戏规则如番种、底分、是否允许七对子应该放在可配置的JSON或ScriptableObject文件中而不是硬编码在逻辑里这样未来修改规则会非常方便。2.2 为什么选择这样的架构很多新手会习惯性地把UI显示和逻辑代码写在一起比如在牌被点击的回调函数里直接修改数据并判定胡牌。这在小型Demo中看似快捷但随着规则复杂化比如加入血流、血战模式代码会迅速变成一团乱麻调试一个Bug可能牵一发而动全身。采用上述分层架构的好处是可测试性你可以单独为MahjongData和胡牌算法写单元测试无需启动游戏界面。可维护性UI改版不会影响核心逻辑规则调整也不会波及UI显示。可扩展性未来如果想加入网络多人对战只需将GameController中本地驱动循环的部分替换为接收网络消息即可数据模型和UI视图几乎不用动。3. 核心实现细节与关键技术点拆解接下来我们深入几个最具挑战性也最核心的部分看看具体怎么实现。3.1 麻将牌的创建、管理与渲染优化麻将牌在游戏中会大量出现手牌最多14张牌墙上百张如何高效地创建和管理它们是第一个性能关卡。实现方案预制体设计创建一个MahjongTilePrefab。它应该包含一个Sprite组件用于显示牌面一个Button或EventTrigger组件用于处理点击事件以及一个挂载在上面的MahjongTileView脚本。这个脚本的作用是关联一个MahjongTile数据对象并根据该对象的数据更新Sprite的spriteFrame。// MahjongTileView.ts ccclass(MahjongTileView) export class MahjongTileView extends Component { property(Sprite) sprite: Sprite null!; private _data: MahjongTile null!; // 一个资源映射表例如 {101: spriteFrameOf一万, ...} private static _tileSpriteMap: Mapnumber, SpriteFrame new Map(); public init(data: MahjongTile) { this._data data; this.sprite.spriteFrame MahjongTileView._tileSpriteMap.get(data.logicValue); // 还可以根据状态设置灰度、遮罩等如不可出的牌变灰 } }对象池化绝对不要在每次需要显示牌时都instantiate预制体打牌后又destroy。这会造成严重的GC垃圾回收压力导致游戏卡顿。必须使用对象池。// TileManager.ts - 一个简单的牌对象池管理器 export class TileManager { private _pool: NodePool new NodePool(MahjongTileView); public getTile(data: MahjongTile, parent: Node): MahjongTileView { let tileNode: Node; if (this._pool.size() 0) { tileNode this._pool.get(); } else { tileNode instantiate(this.tilePrefab); } parent.addChild(tileNode); const view tileNode.getComponent(MahjongTileView); view.init(data); return view; } public recycleTile(tileNode: Node) { tileNode.removeFromParent(); this._pool.put(tileNode); } }实操心得对象池的prefab最好在游戏启动时就完成预加载和初始put一些实例避免在游戏过程中如发牌时首次实例化造成瞬时卡顿。牌面资源加载34种牌27种序数牌7种字牌的正反面图片。建议使用SpriteAtlas图集。将所有的牌面小图打包成一个或几个图集能显著减少Draw Call提升渲染效率。在Cocos Creator中创建图集非常简单将图片拖入assets目录下的一个文件夹然后在该文件夹上右键选择“创建SpriteAtlas”即可。3.2 核心游戏逻辑胡牌算法与状态机这是麻将游戏的灵魂所在。胡牌判定算法网上有很多这里我采用一种比较直观的“递归剔除将牌顺刻组合”的方法。胡牌算法思路以标准麻将14张牌为例检查牌数是否为 3n 2 (n0,1,2,3,4)。从牌列表中尝试选取所有可能的“将”对子。移除这对“将”后对剩下的12张牌进行判断看是否能全部组成“顺子”或“刻子”三张相同。判断剩余牌组时可以排序后从小到大遍历。对于当前最小的牌它要么属于一个刻子三张相同要么属于一个顺子需要它和它的1, 2都存在。递归或循环检查。如果找到一种分组方式使得所有牌被分完则胡牌。// MahjongLogic.ts - 简化的胡牌判定核心函数 export function checkWin(tiles: number[]): boolean { // 1. 排序 tiles.sort((a, b) a - b); // 2. 递归检查 return _checkWinRecursive(tiles); } function _checkWinRecursive(tiles: number[], hasPair: boolean false): boolean { if (tiles.length 0) { return hasPair; // 牌分完且已有将牌胡牌 } // 尝试取刻子 if (tiles[0] tiles[1] tiles[0] tiles[2]) { if (_checkWinRecursive(tiles.slice(3), hasPair)) return true; } // 尝试取将牌且尚未有将牌时 if (!hasPair tiles[0] tiles[1]) { if (_checkWinRecursive(tiles.slice(2), true)) return true; } // 尝试取顺子序数牌且不是字牌 const first tiles[0]; if (first 400) { // 假设400以上是字牌不能组成顺子 const idx1 tiles.indexOf(first 1); const idx2 tiles.indexOf(first 2); if (idx1 ! -1 idx2 ! -1) { const newTiles [...tiles]; newTiles.splice(idx2, 1); newTiles.splice(idx1, 1); newTiles.shift(); // 移除first if (_checkWinRecursive(newTiles, hasPair)) return true; } } return false; }注意事项这是一个基础版本实际中需要处理“七对子”、“十三幺”等特殊牌型它们不符合3n2的常规组合模式需要单独判断。此外算法效率在递归深度大时可能成为瓶颈对于实时性要求极高的场景如服务器端万人同时在线需要优化或用查表法。游戏状态机麻将游戏流程清晰非常适合用状态机来管理。GameController中维护一个当前状态状态改变驱动不同的行为。enum GameState { Idle, // 空闲 Dealing, // 发牌 PlayerTurn, // 玩家回合等待摸牌或操作 WaitingForAction, // 等待玩家选择吃碰杠胡 AITurn, // AI回合 GameOver, // 游戏结束 } // 在GameController的update或通过事件驱动状态转移 switch(this.currentState) { case GameState.Dealing: // 执行发牌动画发完后切换到PlayerTurn break; case GameState.PlayerTurn: // 等待玩家摸牌或对他人打出的牌做出反应 break; case GameState.WaitingForAction: // 显示“吃、碰、杠、胡”按钮等待玩家点击 break; }使用状态机可以让游戏逻辑条理非常清晰避免用一堆布尔标志位isDealing,canPong...带来的混乱。3.3 UI交互与动画反馈良好的UI交互能极大提升游戏体验。在麻将游戏中主要涉及手牌的选择、拖拽如果支持、操作按钮的弹出与反馈。手牌交互点击选牌为每张牌预制体添加按钮组件。点击时触发事件到GameController控制器判断当前状态是否允许出牌是否是自己的回合是否已摸牌等如果允许则调用PlayerData.discardTile(tile)然后更新UI。视觉反馈选中的牌可以有一个上浮的动画或外发光效果。这可以通过在MahjongTileView中控制节点的position.y或添加一个高亮Sprite来实现。public setSelected(isSelected: boolean) { if (isSelected) { tween(this.node) .to(0.1, { position: v3(this.node.position.x, 20, 0) }) // 上浮20像素 .start(); } else { tween(this.node) .to(0.1, { position: v3(this.node.position.x, 0, 0) }) .start(); } }操作按钮管理当其他玩家打出一张牌而你可能有吃、碰、杠、胡等选择时需要弹出一个操作按钮面板。这里的关键是按钮的智能显示与自动隐藏。智能显示GameController在收到“牌已打出”的事件后立即根据当前玩家的手牌计算所有合法操作。然后通知UIManager显示操作面板并只激活那些合法的按钮如可碰才亮“碰”按钮。自动隐藏需要设置一个倒计时例如5秒。如果玩家不操作倒计时结束后自动隐藏面板并默认执行“过”放弃操作。这可以用setTimeout或scheduleOnce实现。踩坑记录按钮面板的事件绑定一定要在面板隐藏或回收时妥善移除否则可能引起内存泄漏或重复触发。最好在面板节点的onDestroy生命周期里统一做事件清理。4. 完整实现流程与关键代码解析让我们串联起上述模块走一遍游戏从启动到进行一回合的核心流程。4.1 游戏初始化与洗牌发牌场景搭建创建一个GameScene包含背景、四个玩家区域手牌区、碰杠区、打出牌区、中央牌墙区、操作按钮面板、信息提示文本等UI节点。数据初始化在GameController的start()方法中初始化MahjongData。// GameController.ts start() { // 1. 初始化牌墙生成136张牌的逻辑值数组 this.mahjongData.initWall(); // 2. 初始化四位玩家数据 this.players.forEach(p p.reset()); // 3. 洗牌对牌墙数组进行随机排序Fisher-Yates洗牌算法 this.shuffleWall(); // 4. 进入发牌状态 this.changeState(GameState.Dealing); }发牌动画发牌不是瞬间完成的应该有动画效果。我们可以用tween协程来实现。async dealCards() { const dealOrder [0,1,2,3, 0,1,2,3, ...]; // 发牌顺序东南西北轮流 for (let i 0; i 52; i) { // 每人先发13张共52张 const playerIndex dealOrder[i]; const tileValue this.mahjongData.drawFromWall(); const targetPos this.getPlayerHandPos(playerIndex); // 使用对象池获取一张牌节点 const tileNode this.tileManager.getTile(tileValue, this.node); // 设置起始位置牌墙 tileNode.setPosition(wallPosition); // 执行补间动画飞到玩家手牌区 tween(tileNode) .to(0.3, { position: targetPos }) .start(); // 更新玩家数据 this.players[playerIndex].addTile(tileValue); // 等待一小段时间形成连续发牌的效果 await this.sleep(50); // 一个简单的延时函数 } // 最后再发一轮庄家多一张第53-56张 // 发牌完成后切换状态到玩家回合 this.changeState(GameState.PlayerTurn); }4.2 玩家回合与AI决策循环玩家回合流程状态机进入PlayerTurn。如果轮到真人玩家UI上提示“请摸牌”。玩家点击牌墙或摸牌按钮后控制器从牌墙取一张牌加入玩家手牌并刷新手牌UI。玩家从新手牌中选择一张打出。GameController会验证这张牌是否在玩家手牌中然后执行player.discardTile()。打出的牌需要放置到“河”里中央打出牌区并通知其他三家玩家或AI“有一张牌被打出了”。AI决策实现当轮到AI玩家或需要AI对打出的牌做出反应时调用AIPlayer.makeDecision()。AI的决策树可以这样设计makeDecision(currentState, discardedTile) { // 1. 先检查是否能胡这张打出的牌如果能胡通常优先胡 if (this.canWin(discardedTile)) { return { action: WIN, tile: discardedTile }; } // 2. 检查是否能杠暗杠、明杠、补杠 if (this.canKong(discardedTile)) { return { action: KONG, tile: discardedTile }; } // 3. 检查是否能碰 if (this.canPong(discardedTile)) { // 简单AI如果碰了之后能听牌就碰 if (this.willBeReadyAfterPong(discardedTile)) { return { action: PONG, tile: discardedTile }; } } // 4. 检查是否能吃仅限上家 if (this.canChow(discardedTile)) { // 策略判断... } // 5. 如果什么都不能做或者策略选择不做就摸牌 if (currentState selfTurn) { const drawnTile this.drawTile(); // 摸牌后需要决定打哪张出去 const tileToDiscard this.chooseTileToDiscard(); return { action: DISCARD, tile: tileToDiscard }; } else { return { action: PASS }; } }chooseTileToDiscard()是AI策略的核心。一个简单的规则是“打孤张”即无法与任何其他牌形成顺子或对子的牌或者“打生张”河里还没出现过的牌点炮概率相对小。更复杂的AI会引入概率计算和牌效分析。4.3 胜负判定与结算展示当有玩家执行“胡”动作时游戏进入结算阶段。锁定游戏状态立即将游戏状态切换为GameOver或ShowingResult阻止其他任何操作。计算番数与分数调用MahjongLogic.calculateFan(winningHand, winningTile, winType)。这里需要根据地方规则实现一个番种计算器。例如判断是否有“清一色”、“碰碰胡”、“杠上开花”等。这是一个规则密集型的模块建议将番种定义和分数配置在外部JSON中。展示结算界面弹出结算面板显示胡牌者、番型、总分以及各家的输赢分数变化。可以使用Label组件和动画数字滚动、飘字效果来增强表现力。数据重置与回合循环结算展示完毕后询问玩家是否开始新一局。如果是则重置MahjongData和PlayerData重新洗牌发牌庄家可能根据规则轮转。5. 常见问题、调试技巧与性能优化在开发过程中你一定会遇到各种奇怪的问题。下面是我踩过的一些坑和解决方法。5.1 Cocos Creator 编辑器与开发环境常见问题编辑器启动报错 “Cannot read property ‘uuid’ of null” 这个问题通常与资源引用丢失或场景文件损坏有关。解决方法1检查控制台报错的具体位置找到是哪个脚本或组件的属性在编辑器序列化时引用了不存在的资源uuid为null。尝试在属性检查器中重新关联丢失的资源。解决方法2如果问题难以定位可以尝试清理编辑器临时数据。关闭Cocos Creator删除项目目录下的library、temp文件夹然后重新打开项目。编辑器会重新导入和编译资源这个过程可能较慢但能解决很多诡异的引用问题。解决方法3检查你的TypeScript脚本是否有语法错误或循环引用有时这也会导致编辑器解析失败。代码控制动画Animation或Spine不流畅或卡顿确保使用正确的API对于Animation组件使用play()方法并监听finished事件。避免在update里每帧去设置动画进度。检查动画资源如果是帧动画确保所有SpriteFrame已正确加载并放入图集。大量零散小图会造成渲染性能瓶颈。使用性能分析工具Cocos Creator内置的Profiler是神器。在运行时打开开发者 - 性能分析器查看Script、Renderer、Animation等模块的耗时。如果动画更新耗时很高可能是骨骼太复杂或更新频率过高。打包后资源加载失败特别是小游戏平台路径问题在代码中加载资源时不要使用硬编码的绝对路径。使用resources.load()或assetManager.loadBundle()等API它们会处理不同平台的路径差异。资源未包含在构建中在构建发布面板中确保你所用到的资源如图集、预制体、音效所在的目录被勾选在“参与构建的资源”范围内。对于resources目录下的资源会自动包含但其他目录的需要手动配置。小游戏平台限制如美团小游戏有包体大小限制。需要使用资源分包功能。将首包不必要的资源如后续关卡的图片、音效放到远程服务器或配置为子包。5.2 麻将游戏逻辑调试技巧麻将逻辑复杂Debug不能只靠console.log。单元测试为胡牌算法、番种计算等纯逻辑函数编写单元测试。你可以使用Jest或Mocha等框架或者在项目中简单创建一个测试场景用预设的牌型数组调用函数断言输出结果。// 在一个测试脚本中 test(七对子胡牌判定, () { const tiles [101,101, 102,102, 103,103, 201,201, 202,202, 301,301, 401,401]; expect(MahjongLogic.checkWin(tiles)).toBe(true); });状态可视化在游戏场景中创建一个调试面板可以默认隐藏通过快捷键打开实时显示当前游戏的核心数据。例如当前游戏状态四位玩家的手牌逻辑值牌墙剩余张数当前回合玩家 这能让你在测试时一目了然地看清内部状态快速定位是逻辑错误还是UI显示错误。录制与回放实现一个简单的命令记录功能。将每一局中所有的关键动作洗牌种子、发牌序列、每个玩家的每一次摸牌、打牌、吃碰杠按顺序记录到一个数组或文件中。当出现疑似Bug的牌局时保存这个记录。然后可以实现一个“回放”功能按照记录自动执行所有动作从而100%复现问题这对于调试AI策略和网络同步问题极其有用。5.3 性能优化要点即使是一个2D麻将游戏在低端手机或小游戏平台上也需要关注性能。Draw Call优化这是2D游戏最常见的性能杀手。确保所有麻将牌面纹理都在同一个SpriteAtlas中。使用Creator的渲染调试工具查看Draw Call数量如果一张牌一个Draw Call那肯定有问题。合图后同材质的牌在一次绘制中完成。节点数量控制牌墙如果一开始就实例化136个牌节点并隐藏虽然方便但节点数过多。更好的做法是牌墙只用一个或几个节点表示如一堆牌的背面逻辑上用一个数组管理。只有被摸出的牌才真正创建交互节点。手牌区也要及时回收打出的牌节点到对象池。垃圾回收避免在update中频繁创建临时对象如new Vec3,new Array。对于需要重复使用的变量在类成员中声明。谨慎使用闭包和匿名函数它们可能产生不必要的内存分配。逻辑帧率与渲染帧率解耦麻将游戏不需要60FPS的逻辑更新。你可以通过setInterval或schedule将AI思考、动画状态更新等逻辑控制在较低频率如每秒10-20次而渲染依然保持流畅。这能减少不必要的计算特别是在AI思考较复杂时。开发这样一个项目最大的收获不是最终做出了一个游戏而是在这个过程中你系统地实践了Cocos Creator的UI系统、动画系统、资源管理、对象池、状态机设计、算法实现和性能优化。很多思路和代码结构可以复用到其他类型的游戏或应用中。当你看到自己写的AI能像模像样地打出一手牌或者成功判定出一个复杂的胡牌牌型时那种成就感是非常实在的。