企业官网建设流程全解析

说到用 Cocos Creator 做麻将游戏，不少开发者第一反应是“不就是洗牌、发牌、定缺、胡牌吗，有什么好讲的”。但真正上手做一款能上线的麻将小游戏，你会发现坑远比想象的多——从吃碰胡的交互手感，到 3D 桌面上的物理表现，再到 Android、iOS、微信小游戏等多端打包，每一步都能让人加班到凌晨。最近我拿到了一套号称“非逆向、多平台适配”的 Cocos Creator 麻将游戏源码，实测跑通之后，决定把它拆开讲讲，也算是给自己踩过的坑做个备忘。

这套源码不是网上那种只能看不能跑的演示工程，而是能打开 Cocos Creator 后直接构建发布的那种完整项目。玩法上支持四人麻将的吃碰杠胡，桌面带 3D 表现，骰子也用物理引擎驱动，操作动画、音效衔接、结算界面都齐全。如果你是刚入行的游戏客户端开发者，想搞明白一个完整棋牌项目该怎么组织代码；或者你已经在做棋牌项目，正为了某个交互效果卡了几天，这篇文章都能给你一些确实用得上的参考。我会尽量把源码里的设计思路、运行流程、真机适配经验都摊开讲，并且把我实测中踩到的坑一并列出来。

1. 项目全景：标题里的每个承诺，都是一项实际需求

1.1 先拆壳：一套“非逆向”源码意味着什么

网上搜“Cocos Creator 麻将源码”，能搜到一大堆，但里面至少有三分之一是拿解包工具扒出来的资源工程。这类工程最大的问题是：代码没有注释、变量名被混淆、场景结构乱成一团，你改一行逻辑可能要牵连十几个地方。而所谓“非逆向”，就是指源码本身就是开发者主动整理的工程，目录结构正常、脚本命名可读、资源引用关系清楚。这套源码在这方面做得比较典型，我打开 assets 目录后能直接分辨出场景、脚本、预制体、音效和贴图的归属，而不是面对一堆 hash 文件名发呆。

这个区别在实际开发里非常重要。逆向工程往往只能“参考着看”，而一套正常的源码可以“拿来就改”。比如我想把原本的四人麻将改成带“赖子”的玩法，只需要找到判定模块，修改对应的牌型处理逻辑即可。如果是反编译的项目，光是找到判定函数的入口都可能耗掉半天时间，更别说改了以后还不敢保证没有遗漏的关联调用。

1.2 多平台适配不是口号，是构建管线的真功夫

“多平台适配”在标题里很抢眼，但实际做到位并不容易。Cocos Creator 本身就支持一次开发多端发布，但它提供的是“能力”，不是“结果”。同一个项目发布到微信小游戏和发布到 Android 原生，需要处理的差异点非常多：包体积限制、资源加载方式、屏幕安全区、触摸事件延迟、物理引擎的性能开销……这套源码在这些地方做了对应的代码分支，我在后面第五部分会仔仔细细讲。

另外，麻将游戏对“可重复开局”的要求很高，一局结束以后要能快速回到大厅重新匹配或创建房间。源码里花了大量篇幅处理房间数据重置、牌局状态清理、节点池复用，这比单纯实现一局玩法要复杂得多。如果你拿这套源码做二次开发，这部分逻辑建议先看懂再动，因为很多“玩第二局时卡死”的 Bug 就出在清理不干净上。

1.3 这套项目适合谁、能改造成什么

以我实测的体感来看，这套源码的难度属于“中高一档”。对刚学 Cocos Creator 的人来说，它比官方示例复杂，但比商业项目精简，刚好处于“看得懂，又有挑战性”的位置。你可以照着它的状态机设计学习棋牌游戏的整体架构，也可以只提取其中的吃碰胡判定部分，移植到自己的项目里。

如果做二次开发，比较常见的改法大概有这么几类：

• 换玩法规则：改成四川麻将、湖南麻将、红中赖子杠等不同流派，重点改规则判定模块。
• 改界面风格：把 3D 桌面换成 Q 版、国风、赛博朋克等视觉风格，重点是场景、预制体和 UI 素材的替换。
• 加联网对战：源码如果带的是本地对战，那就在现有 UI 流程上接入服务端协议，技能栈从客户端向网络层延伸。

我自己动手验证的是“换玩法和换界面”这条线，整体的可扩展性比预期好。后面讲的各处细节，基本都来自这个实测过程。

2. 技术选型背后：为什么是 Cocos Creator 搭配 3D 物理引擎

2.1 Cocos Creator 在棋牌品类里的位置

做棋牌游戏，特别是小游戏平台上的棋牌，Cocos Creator 几乎是绕不开的选择。原因很直接：它的编辑器工作流适合 UI 密集型的项目，场景、预制体、动画都能可视化编辑；它的脚本组件体系上手快，一个界面绑定一个控件脚本，结构清楚；它对微信、抖音小游戏有官方构建通道，打包以后不需要太多手工胶水代码。相比之下，Unity 做 3D 更强，但在小游戏包体和启动速度上要吃更多苦头；Laya 和 Egret 虽然也是 H5 系，但社区和资源生态目前都不如 Cocos 热闹。

麻将本质上是一个“强 UI + 弱实时性”的游戏，核心玩法是点击和判定，不是动作打击和物理模拟。用 Cocos Creator 来做，资源占用小，包体容易控制，发布到小游戏平台时首包能控制在 4MB 以内。源码里我看到 fnt 字体、压缩纹理和音频的选型都在往“小体积”方向靠，这也是棋牌项目能不能过平台审核的一个重要条件。

2.2 3D 物理引擎在这里不是炫技，是表现力

很多人听到“3D 物理引擎”会以为麻将牌是立着倒下的那种 3D 动作游戏，其实不然。麻将玩法的核心还是 2D 牌面逻辑，3D 物理引擎在这里主要管三件事：骰子投掷、牌墙碰撞动画、以及相机微动带来的立体感。

骰子投掷是最典型的物理应用。开局时两颗骰子在桌面中间旋转出手，最终停下的点数决定从哪里抓牌。源码里给骰子挂上了 RigidBody，在投掷瞬间给一个随机角度和力矩，让每次开局的骰子结果都不一样。比单纯的动画播要自然得多，玩家能明显感受到“这是一局真实的牌局”而不是播放同一个过场。桌面上，牌墙由一列 3D 麻将牌放置而成，玩家的摸牌、打牌动作会触发牌与牌之间的轻微碰撞，让手牌区域看起来像是有重量的实体。这套实现其实不复杂，但效果直接拉升了游戏的整体质感。

不过用物理引擎就要承受它的性能消耗。手游端上一堆刚体的碰撞检测如果处理不好，帧率会肉眼可见地掉。源码的做法是把不必要的碰撞矩阵关掉，只保留关键节点之间的碰撞（比如牌与桌面、牌与牌），我实测下来发热和耗电都在可接受范围，后面排查部分我会给出具体参数。

2.3 为什么“完整可运行”比“功能齐全”更值钱

拿到一套源码，第一步不该看功能列表，而是先看能不能跑起来。真正常见的挫败是：功能描述写得天花乱坠，下载下来一打开场景，一堆资源引用缺失、脚本报错、预制体破坏，光修复工程就要大半天。这套源码能“完整可运行”，说明作者在交付之前至少做了一个完整构建流程的验证，这对买源码或者找学习素材的人来说，是最基本的保障。

我把这个工程放到 Cocos Creator 3.x 版本里打开，首次加载时会提示升级资源元数据，确认后就能正常进入 main 场景。构建目的地我分别试了浏览器（Web Mobile）、微信小游戏和 Android，三条路线都能顺利产出可运行产物。这种干净利落的体验，省下的是真正开发时间，而不是修补环境的耐心。

3. 核心玩法实现：吃碰胡的流畅度是怎么撑起来的

3.1 麻将状态机：所有流畅体验的地基

麻将游戏里的“流畅”不是感觉问题，而是状态机设计得好不好的问题。玩家点击“碰”到界面响应碰牌动画，这中间涉及的流程是：玩家操作是否处于允许碰的窗口期、触发的牌是否真实可用、动画播放完后后续逻辑是否衔接得上。一个环节没处理好，就会出现“点了没反应”或“碰完手牌错乱”的问题。

源码里的状态机核心分为七个状态：Idle（等待）、Draw（摸牌）、Operate（操作判定）、Discard（出牌）、WinCheck（胡牌检查）、Settle（结算）、GameOver（结束）。每一局开始时状态机初始化到 Idle，然后按照“摸牌 → 操作 → 出牌 → 下家摸牌”的循环推进。状态切换通过事件驱动，而不是靠主循环逐帧去 poll，这样就避免了某帧卡顿导致状态错乱的风险。

在设计自己的棋牌项目时，你大概率也会照着这种思路做，但要特别注意的是“操作窗口期”的细节。比如上家打出一张牌后，下家不仅要判断能不能吃碰，还要处理多个玩家同时符合操作条件的情况（比如你和对家都想碰同一张牌）。源码里用一个优先级表处理：胡 > 杠 > 碰 > 吃。谁的操作等级高，谁优先拿到这张牌的操作权，其他玩家只能等待超时或放弃。

3.2 吃碰胡的判定逻辑，用数据结构和算法说话

麻将的吃碰胡判定，本质是集合运算和组合枚举。源码里把麻将牌拆成了数字索引，万条筒用 1-9 的区间区分，字牌用特殊的编号段表示。吃牌判断是典型的顺子组合查找，碰牌和杠牌只需要统计同一种牌的重复张数，而胡牌判定则需要对整副手牌做拆分。

举一个吃牌的代码思路例子：

// 伪代码示意：checkChi 返回所有可吃的组合 checkChi(targetTile: number, handTiles: number[]): number[][] { const results: number[][] = []; const hand = handTiles.slice().sort((a, b) => a - b); for (let i = 0; i < hand.length - 1; i++) { if (hand[i] === targetTile - 1 && hand[i + 1] === targetTile - 2) { results.push([hand[i], hand[i + 1]]); } else if (hand[i] === targetTile - 1 && hand[i + 1] === targetTile + 1) { results.push([hand[i], hand[i + 1]]); } else if (hand[i] === targetTile + 1 && hand[i + 1] === targetTile + 2) { results.push([hand[i], hand[i + 1]]); } } return results; }

注意吃牌只能使用“上家”打出的牌，而且要保证当前这张牌没有被其他玩家更高级的操作抢走，这是状态优先级之外的规则约束。胡牌判定更复杂一点，需要枚举将牌（对子）和刻子、顺子的组合，源码里用递归回溯来实现，输出的是一个布尔结果，最坏情况下的性能开销大约在毫秒级，不用担心影响帧率。

3.3 手牌排序和选牌交互的细节体验

麻将的操作手感，很大程度上取决于手牌的展示方式。源码里手牌按照 万 > 条 > 筒 > 字牌 的顺序分组排列，组内按点数升序。玩家选中一张牌后，它会从牌列中弹起一小段距离，然后出牌动画把它推进桌面中央，同时手牌列表会立即补位重排。这个补位重排如果做成整列重排，看起来会有轻微的跳跃感；源码里用的是 Tween 过渡，每张牌平滑地滑到新位置，整体视觉效果顺滑很多。

我当时实测时发现一个细节：快速连续点击手牌，偶尔会出现“明明选中的是这张，出牌却是上一张”的问题。后来追踪代码发现是 UI 按钮的点击事件在下发到组件之前，手牌索引被异步重新排序导致。源码里给操作加了一个“当前出牌序列号”的校验，每次点击事件都会检查序列号是否匹配，不匹配就直接拦截。这个思路值得借鉴：任何涉及动态渲染列表的点击操作，都要考虑数据和 UI 不同步时的兜底逻辑。

3.4 动画衔接：从摸牌到出牌的时间线设计

流畅体验的最后一块拼图是动画时间线。源码里把摸牌、出牌、吃碰杠、亮牌等动画时长都集中在一个常量配置文件里，比如摸牌是 0.3 秒，出牌是 0.25 秒，碰牌之后的展示停留是 0.8 秒。这样统一管理的好处是，调整节奏时不需要在几十个组件里逐个修改，改一处配置全局生效。

一个常见的坑是动画事件和逻辑判定串行执行。比如碰牌动画还没播完，下一次摸牌逻辑已经触发了，导致手牌数量暂时错乱。源码里使用回调链和 Promise 链把动画结束和逻辑继续绑定在一起，每次动画完成后再通知状态机节点继续推进。如果你在自己的项目里也遇到类似问题，优先检查是不是把动画播放和逻辑驱动放在同一帧里处理了。

4. 源码结构与关键模块：从目录到核心脚本

4.1 一个能长期维护的目录长什么样

拿到源码后，我先看了 directory 结构，这是判断一个工程健康度的最快方式。这套源码的 assets 下大致分这么几个目录：

• scenes：存放场景文件，main、hall、game、settle 等场景按职责分开放。
• scripts：按模块再分子目录，logic、ui、data、utils、audio 各司其职。
• prefabs：所有可复用的预制体集中管理，比如牌预制体、骰子预制体、操作按钮预制体。
• resources：动态加载的资源，比如音效、远程加载的图片和配置表。
• textures、audio、fonts：静态素材按类型归档。

这种组织方式的优点很直接：当你要改一个“按钮点击后播放音效”的需求，你能在 10 秒内定位到对应脚本、对应音效文件、对应预制体，而不是满世界找资源。我在二次开发时给“碰”按钮加了个特殊音效，按这个目录结构改完只花了不到半小时。

4.2 核心脚本的职责划分：一个脚本只管一件事

源码里的核心脚本不算多，但每个都职责清楚：

• GameManager.ts：整个游戏流程的入口，持有状态机实例和当前牌局数据，负责启动、暂停、恢复、重置。
• PlayerController.ts：管理玩家对象，包括手牌、公开牌、玩家资金、操作权限等。
• TableTiles.ts：管理桌面牌墙和已打出的牌，负责牌的出场和清理。
• MahjongRules.ts：所有规则判断的纯函数集合，输入牌型数据，输出判定结果，不依赖场景节点。
• UITouchHandler.ts：UI 交互的统一入口，处理点击、拖拽、按钮回调。
• CameraController.ts：控制主相机，负责桌面视角的移动和缩放。

我最欣赏的一点是把 MahjongRules 做成纯函数集合，不挂在任何节点上。这意味着你可以完全脱离场景去单元测试规则逻辑，用 Node 直接跑这段代码就能验证胡牌判定对不对。我在改规则时把规则脚本单独复制到本地写了个测试脚本，跑了三百多个麻将牌型用例，确认无误后才再导回工程，大大减少了试错成本。

4.3 数据绑定与事件分发：组件之间怎么打招呼

组件通信是工程里最容易写乱的部分。源码采用的是全局事件总线加局部监听的方式，GameManager 发布全局事件（比如“出牌了”“胡牌了”），UI 层和动画层各取所需地监听对应事件。这样 UI 不直接持有游戏逻辑的引用，逻辑也不关心当前界面上有几个按钮，耦合度低，后期换主题皮肤或者调整 UI 结构都相对轻松。

事件总线是通过一个单例 EventBus 实现的，底层用的是 cc.EventTarget。我在自己的项目里也复用这个方案，但要注意事件监听的注销：节点销毁时如果不移除监听，容易引发内存泄漏或者回调到已销毁节点。源码中在 onDestroy 里统一做了 off 操作，这个问题在长周期的牌局场景中尤其重要，因为一局游戏要持续十几分钟，节点增删很频繁。

5. 多平台适配实战：从编辑器到真机的完整流程

5.1 构建发布的基础配置，几个必须勾选的选项

用 Cocos Creator 做多平台发布，构建面板里有一堆选项，但真正决定命运的是这几个：

• 主包压缩类型：小游戏平台选 Merlin 或默认的压缩方式，体积能省不少。
• 内联所有 Sprite 帧：如果项目里 Sprite Frame 资源较多，建议开启，减少小游戏平台的请求次数。
• 启动场景和引导场景配置：确认 main 场景被正确标记为“启动场景”。
• 物理引擎模块裁剪：用不到的碰撞检测需求可以裁剪掉，减少引擎包体。

我实测下来，如果不做这些配置，直接在构建面板里点“构建”，发布的包体会比优化后大 20% 左右，加载速度也会慢上一截。上架微信小游戏时，主包 4MB 限制是很现实的门槛，所以这步优化不是可选，而是必做。

5.2 微信小游戏平台的差异化处理

打包到微信小游戏时，需要注意世界的处理逻辑和浏览器端完全不同。源码里专门检测了cc.sys.platform === cc.sys.Platform.WECHAT_GAME来切换资源加载逻辑，微信端通过wx.createInnerAudioContext()播放声音，而浏览器端使用标准的 AudioSource 组件。这是因为微信小游戏没有浏览器的 DOM Audio 能力，直接播放会有兼容性问题。

另外，微信小游戏有首屏加载“冷启动”的概念，玩家从点击到进入游戏大厅之间，有 2 秒左右的资源加载时间。源码在大厅场景放了一个占位面的 Loading 动画，等场景资源和首局牌局数据都 ready 后再切到游戏场景，体验上就不会显得卡一下或白屏。这个处理我原封不动地保留在了自己项目中。

5.3 Android 打包与性能调优笔记

Android 原生打包相对简单，只要在构建面板里输出 Android 工程，用 Android Studio 打开，配置好签名就能出 APK。这里踩过几个坑，分享给兄弟们：

第一个是 GL 渲染模式。默认的 OpenGL ES 2.0 在老设备上兼容性更好，但如果游戏里用了较多 3D 材质，可能要考虑升级到 3.0。实测下来这套麻将的 3D 桌面用 2.0 也够用，帧率稳定在 60，而且兼容性好，建议保持默认。

第二个是屏幕适配。不同机型的屏幕宽高比差异很大，源码里的 Canvas 组件选择了适配高度、适配宽度的组合，配合相机把桌面位置固定在各机型都能接受的范围。如果你自己用固定分辨率坐标布了局，建议参照这套源码改成百分比和锚点混合布局，否则遇到异形屏（刘海、挖孔）会出现按钮被遮挡的情况。

第三个是内存占用。棋牌类游戏资源量不大，一般不会 OOM，但如果反复进出房间，资源没有及时释放还是会积压。源码针对牌桌场景做了节点池管理，退出房间时把可复用的牌节点回收进池子，而不是直接销毁，下一局再取出来用。这个技巧能让长时间游戏的玩家体验到更稳定的帧率，我强烈建议保留。

5.4 iOS 平台要额外留意的点

当前工程我没在 iOS 真机上跑完整流程，但基于代码里的 API 调用方式，可以给出几个常见的注意点。iOS 上音频播放格式建议用 m4a 或 aac，尽量避免某些 Android 原生支持的 ogg 格式。另外 iOS 不允许在启动阶段做大量底层资源加载，否则容易触发系统看门狗，因此启动场景尽量保持轻量，把核心资源拆到后续场景按需加载。这些在源码里虽然没有做完整的 iOS 专项配置，但留出的结构是支持后续扩展的。

6. 常见问题与排查技巧实录

6.1 物理表现不稳定的问题：刚体穿透、骰子乱飞

跑这套源码时，我最先遇到的物理问题就是骰子有时会飞到桌面外面去。排查下来，一个原因是刚体的碰撞体尺寸太小，两个骰子在高速旋转时互相穿过；另一个原因是物理引擎的迭代次数不够，碰撞解算不及时。源码里把刚体的碰撞检测模式设为 Continuous，并把物理引擎的 fixedTimeStep 从默认的 1/60 调整到 1/120，问题基本解决。

桌上牌墙偶尔会出现“牌叠牌”的情况，那是碰撞体的 z 轴位置与牌墙排列逻辑不一致造成的。处理方式是统一所有牌节点的坐标基准，让牌的显示位置和物理碰撞体位置保持一致，避免一边是逻辑坐标，一边是物理坐标的错位。

6.2 卡顿和掉帧，先从资源加载和 DrawCall 查起

表现上“进入牌局后动画略卡”的问题，我用 profiler 抓了一下，发现瓶颈主要来自资源异步加载和 UI 的 DrawCall 数量。资源方面，源码里对牌面图集做了合并，一张图集包含多张牌面，减少纹理切换；UI 方面，如果按钮和背景图都不需要动态变化，就把这些节点标记为静态，交给引擎合批处理。

如果你在跑其他工程时遇到类似情况，我的排查顺序是：先看资源加载有没有阻塞主线程、再看 DrawCall 是不是异常高、最后看物理引擎的刚体数量是不是超出预期。大多数麻将类项目的卡顿逃不出这三个原因。

6.3 点击事件和动画冲突：为什么点了“碰”没反应

这个问题的本质是动画播放期间的输入拦截。源码的做法是给操作面板加了一个“可点击状态”标记，在动画播放期间把标记置为 false，动画结束再恢复。如果你拿到的工程没有这个标记，又恰好出现点击按钮无响应、但过一会儿又恢复的情况，大概率就是动画时间内的输入丢失导致的。

另外，如果操作面板和手牌区域的节点有重叠，需要检查每个节点的点击区域是否被遮挡。我把手牌区域节点的UITransform尺寸调大以后，曾经挡住过一次碰按钮，排查了很久才发现是节点层级顺序的问题。建议每次改完 UI，都用浏览器的调试工具点一遍关键按钮，确认触发区域没有异常。

6.4 多局游戏后资源泄漏的定位方法

连续玩五局以上，如果内存持续上涨，说明存在资源泄漏点。最常见的泄漏原因是场景切换时没有释放动态创建的节点和事件监听。源码里提供了一个“房间退出清理”的调用链：GameManager 在退出房间时依次发布 GameExit 事件，所有监听该事件的模块执行自身的清理逻辑（移除监听、回收节点池、清空运行时数据）。

如果你在自己的项目里排这类 Bug，可以在浏览器开发者工具里定期执行cc.director.getScene()分析节点树，看是否有残留的事件监听器挂在被卸载的节点上。也可以用Memory Stats面板观察堆内存曲线，对比不同操作前后的增量，逐步缩小可疑模块范围。

6.5 给拿这套源码开发的朋友的三条建议

第一，先不要急着改功能，花一天时间把状态机和事件流看明白。很多问题都是在改规则时破坏了状态流转顺序才冒出来的，你越了解底层的流转方式，后续定位 Bug 就越快。

第二，把规则判定脚本抽出来做单元测试。麻将规则分支多，尤其胡牌判定，靠手工点几局很难覆盖全。我建议把 MahjongRules 脚本导出到 Node 环境里，写个简单的命令行测试工具，把常见的听牌、胡牌组合全部枚举一遍，确认输出结果无误再改 UI。

第三，遇到物理表现问题，优先去看碰撞矩阵和迭代次数，而不是急着换物理引擎版本。Cocos Creator 自带的 Bullet 物理后端在棋牌类场景下完全够用，多数“物理效果不自然”的问题都出在参数配置，而不是选型错误。

我自己的体会是，做棋牌项目的核心不是引擎用得多高级，而是把状态、规则、动画这三个环节的耦合梳理干净。这套麻将源码在我看过的同类型项目里算是一个比较规范的教学样本，完整跑通一遍以后，你对 Cocos Creator 的掌控感会明显上一个台阶。如果后续想把它改造成联网对战版本，建议从服务端的牌局同步入手，客户端现有的状态机可以原样复用，这也是我当时顺手整理过的扩展思路。希望这篇拆解能帮你少走一些我走过的弯路，码代码愉快。