简介这是一套基于Cocos Creator开发的达达麻将棋牌游戏完整项目资源面向具备一定JavaScript基础、想了解棋牌游戏前后端架构及上线流程的开发者。资源覆盖Cocos Creator场景与UI、JS游戏逻辑、Node.js后端服务、MySQL数据存储等环节并针对安全性、性能优化、兼容性测试等运营问题给出设计思路适合作为网络棋牌类项目的参考模板。包内文件总数约2000个总大小51.62MB以js脚本、json配置、png图片、prefab预制体、mp3音频为主另含大量md文档及meta、plist等引擎辅助文件可支撑从客户端表现到服务器交互的完整开发链路。目前已有3238人学习下载多数文件为可直接查阅的工程代码与资源文件便于按模块拆解麻将逻辑、匹配流程和数据表结构。1. Cocos Creator 达达麻将棋牌先别急着写胡牌把桌子立起来再说“cocos creator达达麻将棋牌游戏”这类项目外行看是洗牌、发牌、打牌三步实际动手才知道工作量的大头在状态流转、牌型判定和低端机适配三块。Cocos Creator 做棋牌的优势在编辑器就能排 UI、调动画再用 TypeScript 把规则写成确定性代码不依赖黑匣子框架调试时每一步都能看见。适合正在接棋牌外包、准备自研休闲游戏、或者想拿麻将当规则训练样本的团队。这篇笔记从项目框架讲到胡牌递归最后落在打包与动效照着搭一遍就能把一副牌真正跑起来。2. 先立框架再写牌达达麻将牌桌的最小目录与坐标约定2.1 目录与模块划分三层资源结构为什么够用麻将的代码量不大真正容易失控的是资源引用和全局变量。我习惯把 assets 分成三层scenes 只放场景文件scripts 按 core、ui、effect 三个子目录分开res 下面再拆 prefabs、textures、sounds、anims。首版不建议上分包棋牌项目几十 MB 的资源单包出首版后面真需要热更再按玩法拆。assets/ ├── scenes/ # 游戏场景 │ └── mahjong.scene ├── scripts/ │ ├── core/ # 数据模型、算法、网络协议 │ ├── ui/ # 场景组件、HUD、弹窗 │ └── effect/ # 发牌动效、拖尾、音效控制 ├── res/ │ ├── prefabs/ # 牌、按钮、操作条等预制体 │ ├── textures/ # 图集与单图 │ ├── sounds/ │ └── anims/ └── settings/为什么强调 scripts 和 res 同级拆因为在 Cocos Creator 里场景文件会直接引用资源的 UUID如果把 prefabs 和 scripts 混在同一个目录编辑器每次刷新资源库都会扫描一遍所有 uuid 映射项目一大就卡。分开之后scripts 目录基本不用动只有 res 变化才会触发资源数据库重建。core/ui/effect 这个拆分对应的是代码依赖方向core 不 import uiui 可以 import coreeffect 只在具体动画点被调用。这样胡牌算法、洗牌逻辑这些纯函数可以脱离场景单独跑单元测试。很多麻将项目翻车都是因为玩法逻辑里混了this.node、this.label一脱离场景就没法验证最后只能靠人肉打牌测。2.2 Canvas 适配与坐标约定先定安全区再摆牌棋牌项目最怕在不同分辨率手机上牌位错乱。我的做法是写一个GameConfig.ts把设计分辨率、安全区、四家牌位坐标全部收敛到一个文件任何业务代码不直接写死坐标。// GameConfig.ts import { view, ResolutionPolicy } from cc; export const DESIGN_SIZE { width: 1280, height: 720 }; export const SAFE_AREA { top: 80, bottom: 80, left: 120, right: 120 }; export const TABLE_POS { player0: { x: 0, y: -280 }, // 自家手牌区 player1: { x: -500, y: 0 }, // 下家 player2: { x: 0, y: 280 }, // 对家 player3: { x: 500, y: 0 }, // 上家 poolCenter: { x: 0, y: 0 } // 牌池 };这段代码做了三件事。第一DESIGN_SIZE定义了画布设计分辨率我习惯用 1280x720因为这个比例覆盖了绝大多数手机的宽高比区间。第二SAFE_AREA是给刘海屏和水滴屏留的边距避免牌靠边后被圆角裁掉。第三TABLE_POS是四家手牌和牌池的基准点后续只要这个表里的坐标对了UI 层的布局压力就小一大半。// main.ts 项目入口脚本里做适配 import { view } from cc; view.setDesignResolutionSize(1280, 720, ResolutionPolicy.FIXED_HEIGHT);适配策略我一般用FIXED_HEIGHT。麻将桌是横向布局为主但手牌区、操作条都在屏幕下半部分固定高度可以保证下方 UI 永不被裁左右两侧用背景图补足。SHOW_ALL会在宽屏手机上留黑边看起来很业余FIXED_WIDTH呢竖屏项目适用棋牌横屏用不上。注意这两个策略在实际手机上的表现差异最好拿几台真机跑一遍这是所有模拟器都模拟不出来的细节。2.3 预制体与牌池牌是租来的不是 new 出来的很多人写麻将第一版每局直接instantiate144 张牌节点结束再destroy。这在 PC 上没感觉一到低端 Android 机上开局瞬间创建上百个节点卡顿非常明显。正确做法是用 NodePool 做对象池牌对象复用。// TilePool.ts import { NodePool, instantiate, Prefab, Node } from cc; export class TilePool { private pool new NodePool(); constructor(private tilePrefab: Prefab) { // 预创建 20 张牌避免开局瞬间的实例化峰值 for (let i 0; i 20; i) { this.pool.put(instantiate(this.tilePrefab)); } } get(): Node { return this.pool.size() 0 ? this.pool.get() : instantiate(this.tilePrefab); } put(node: Node): void { this.pool.put(node); } }参数说明NodePool.size()返回当前池内节点数量池空了才走instantiate分支。put不是把节点销毁而是收回到池里节点上的组件、位置、缩放等状态由调用方负责重置。这里有个容易踩的坑put进去的节点如果还挂在活动场景里会出现“隐身但仍在渲染”的情况回收前必须把节点removeFromParent再清空坐标和透明度。对象池用在哪里我一般只给手牌、牌池、操作按钮这几个高频创建销毁的对象用。弹窗、特效这些低频的用instantiate就行过度设计反而增加回收失败的排查难度。开局时 144 张牌复用 20 张预创建的存量后面随用随取峰值稳稳压住。3. 麻将牌不是扑克牌数据模型与洗牌发牌的一种较优解3.1 数据模型从裸数组到带状态的牌对象第一版麻将代码最容易写成用number[]表示手牌比如[1, 2, 3, 5, 5, 6]。这种写法能跑但后面做碰杠、听牌提示、动画回放时你会发现数组里根本存不下“这张牌是哪张图”“这张牌在哪个位置”“这张牌能否被操作”这些信息。// MahjongTile.ts import { Node } from cc; export enum TileSuit { Wan, Tiao, Bing, Zi } // 万、条、筒、字 export class MahjongTile { readonly suit: TileSuit; readonly value: number; // 万/条/筒 为 1-9字牌为 1-7 tileId: number; // 实例唯一 ID用于区分同牌面的两张牌 node: Node | null null; // 渲染节点由对象池注入 constructor(suit: TileSuit, value: number) { this.suit suit; this.value value; } }suit和value是牌面的天文数字组合tileId是这张牌的身份证。为什么需要tileId因为牌池里有 4 张五万它们在玩家眼中的渲染图一样但在拆牌逻辑里必须能区分“你打出去的是哪一张”。不用tileId的话动画回放或撤销操作时会出现歧义这是血泪经验。node是渲染节点的引用放在数据对象里看似耦合实际是为了让牌数据与显示一一对应。我倒是不建议把node单独放在 Map 里维护因为麻将对局中牌的生成和回收非常频繁Map 的增删键值对开销虽然小但容易忘记清理导致内存泄漏埋在对象上反而直观。3.2 Fisher-Yates 洗牌不要用 sort 加随机数一个经典翻车写法是arr.sort(() Math.random() - 0.5)。从效果上看牌是乱了但分布不均匀而且不同浏览器/不同 JS 引擎对 sort 的实现细节不同结果不可控。棋牌游戏的公平性是底线洗牌算法必须可验证。// shuffle.ts export function shuffleT(arr: T[]): void { for (let i arr.length - 1; i 0; i--) { const j Math.floor(Math.random() * (i 1)); [arr[i], arr[j]] [arr[j], arr[i]]; } }这段 Fisher-Yates 是算法课本上的标准实现从数组尾部往前遍历每个位置和随机位置交换。Math.floor(Math.random() * (i 1))保证 j 的范围是 0 到 i 闭区间不会越界也不会产生偏置。时间复杂度 O(n)144 张牌瞬间完成。要较真的话Math.random()本身不是加密级随机源正式棋牌项目想要反外挂应该换成自定义的种子随机数或加密随机。但本地 Demo 和休闲对战用Math.random()够用了先把流程跑通再升级随机源不要第一步就背上密码学负担。3.3 发牌与手牌排序先建立牌墙再发牌常见做法是先生成 4 副牌万字、条字、筒字各 36 张字牌 28 张共 136 张加花牌则 144 张洗牌后发到四个玩家手里。// deal.ts import { MahjongTile, TileSuit } from ./MahjongTile; import { shuffle } from ./shuffle; export function createAllTiles(includeFlower: boolean false): MahjongTile[] { const tiles: MahjongTile[] []; let id 0; // 三种花色每种 9 个数字每个数字 4 张 for (let suit TileSuit.Wan; suit TileSuit.Bing; suit) { for (let v 1; v 9; v) { for (let k 0; k 4; k) { tiles.push(new MahjongTile(suit, v)); tiles[tiles.length - 1].tileId id; } } } // 字牌 东南西北中发白 各 4 张 for (let v 1; v 7; v) { for (let k 0; k 4; k) { tiles.push(new MahjongTile(TileSuit.Zi, v)); tiles[tiles.length - 1].tileId id; } } if (includeFlower) { // 花牌/季节牌按各自规则补全这里略 } shuffle(tiles); return tiles; }createAllTiles里我给每张牌盖了tileId章。suit枚举的顺序本身就是一条排序规则万 条 筒 字。这在后面的手牌排序里会直接用上不需要额外写比较逻辑。export function dealTiles(allTiles: MahjongTile[], hands: MahjongTile[][], countPerHand: number 13): void { let cursor allTiles.length - 1; for (let i 0; i countPerHand; i) { for (let p 0; p hands.length; p) { hands[p].push(allTiles[cursor--]); } } }发牌逻辑的细节在cursor从牌墙尾部往前取配合洗牌后的allTiles保证每个玩家拿到的是牌墙里“均匀分布”的牌。发完 13 张后庄家多摸一张这个动作在发牌后单独做不建议在dealTiles里加参数否则边界条件会越来越复杂。发完牌后手牌要做一次排序便于玩家辨认也便于后续的听牌与胡牌判定export function sortHand(hand: MahjongTile[]): void { hand.sort((a, b) { if (a.suit ! b.suit) return a.suit - b.suit; return a.value - b.value; }); }排序完的手牌阵列UI 层每隔固定间距摆放一张从左到友依次渲染。这里注意排序用的是suit和value跟tileId无关所以 UI 不会因为两张一样的五万而交换位置对玩家来说视觉上无差别。4. 吃碰杠胡的逻辑与状态机让规则确定地跑起来4.1 玩家状态流转从等待到操作的去中心化设计麻将的难点不在某一步动作而在多个动作的交叉选择。比如你家打出三筒你到底能碰还是能吃需要状态机来裁决。我建议给每个玩家维护一个PlayerState把“当前能做什么”和“当前在等什么”分离。// PlayerState.ts export enum PlayerState { WaitTurn, // 等待轮到自己可能响应别人打出的牌 AfterDraw, // 刚摸牌可打牌或选择胡 Discard, // 等待出牌 Win // 已胡牌不再操作 }状态转移的核心指导思想任何玩家出牌后先广播给其他三方三方各自进入WaitTurn并计算“我能吃/碰/杠/胡吗”然后把自己的候选操作上报。玩家自己摸牌后进入AfterDraw状态此时能做的只有打牌或胡牌不能碰杠自己的手牌杠除外杠是摸牌后独有动作。export function nextState(state: PlayerState, action: draw | play | peng | gang | hu): PlayerState { switch (state) { case PlayerState.WaitTurn: if (action peng || action gang) return PlayerState.Discard; if (action hu) return PlayerState.Win; return PlayerState.WaitTurn; case PlayerState.AfterDraw: if (action play) return PlayerState.WaitTurn; if (action gang) return PlayerState.AfterDraw; // 杠后补一张仍保持摸牌状态 if (action hu) return PlayerState.Win; return PlayerState.AfterDraw; default: return state; } }nextState虽然看着简单但它把“操作合法性”和“操作结果”分开了。合法性由各自的规则函数判断结果由这个状态机推进。很多麻将项目做到一半卡在“抢杠胡”“一炮多响”这类交叉规则上本质上是状态机没定义好导致一个玩家的状态变化影响了另一个玩家的候选列表。4.2 胡牌判定递归拆刻子与顺子的最小实现胡牌判定是所有麻将游戏的试金石。我见过不少项目玩法做完了胡牌逻辑还在用三层循环遍历所有组合时间复杂度高到手机上卡顿。标准做法是用递归拆解。先把牌面编码为 0-33 的索引号万条筒各占 0-8、9-17、18-26字牌 27-33。// hu.ts // hand 是索引数组如 [0, 0, 1, 1, 2, 3, 4] 表示两个一万、一个二万等等 export function canWin(hand: number[]): boolean { const counts new Array(34).fill(0); for (const v of hand) counts[v]; return tryCompose(counts, false); } function tryCompose(counts: number[], hasPair: boolean): boolean { const total counts.reduce((sum, c) sum c, 0); if (total 0) return hasPair ? true : false; // 找第一个还有剩余牌的位置 let idx counts.findIndex(c c 0); if (idx -1) return false; // 1. 尝试把当前牌当雀头需要手牌中没有雀头且当前牌 2 if (!hasPair counts[idx] 2) { counts[idx] - 2; if (tryCompose(counts, true)) return true; counts[idx] 2; } // 2. 尝试把当前牌当刻子需要 3 if (counts[idx] 3) { counts[idx] - 3; if (tryCompose(counts, hasPair)) return true; counts[idx] 3; } // 3. 尝试把当前牌当顺子起点需要它是万/条/筒且后两个数字存在 if (idx 26 idx % 9 6) { if (counts[idx 1] 0 counts[idx 2] 0) { counts[idx]--; counts[idx 1]--; counts[idx 2]--; if (tryCompose(counts, hasPair)) return true; counts[idx]; counts[idx 1]; counts[idx 2]; } } return false; }这段递归的思路是每一层都找手牌里索引最小的那张牌不放过的意思。对这张牌要么和同数字的两张组成刻子要么和后两个连续数字组成顺子要么留下作为雀头。因为索引最小的牌没有任何更小的牌可以跟它组顺子所以对它做这三种尝试是完备的。counts数组每次递归复制一份的话性能差我直接原地修改再回溯所以能看到counts[idx] 2这类还原操作这是回溯法的标配写法。注意idx % 9 6这个边界万条筒每种花色只有 1-9索引 7、8 对应数字 8、9它们不可能作为顺子的起点因为后面不够两个数字。字牌更不能拿去组顺子所以直接限制idx 26。这个条件漏掉的话会把东、南、北拆成顺子胡牌判定当场翻车。递归深度方面一副手牌最多 14 张每次递归至少减少 2 张最深不过 7 层PC 和手机上都毫无压力。真正要注意的是多个玩家同时计算听牌时比如点一下“听牌提示”要给 34 张牌各跑一次canWin这时候需要把结果缓存不要反复算。4.3 碰杠与命令流本地预判加服务器校验的棋牌标准层碰和杠本质是“截胡”别人打出的牌。玩家点击“碰”不能直接把牌从别人手里拿过来 UI 上摆一下就算完。标准流程是客户端上报碰请求服务器广播给所有客户端校验通过后正式改变牌归属。但本地也要做一次预判目的是响应速度不然每次按钮都要等到服务器回包才有界面变化体验非常糟糕。// ActionValidator.ts // 本地预判给定手牌和对手打出的牌返回可执行的操作列表 export function canPeng(hand: number[], playedTile: number): boolean { const count hand.filter(v v playedTile).length; return count 2; } export function canGang(hand: number[], playedTile: number): boolean { const count hand.filter(v v playedTile).length; return count 3; } export function canChi(hand: number[], playedTile: number): boolean { if (playedTile 26) return false; // 字牌不能吃 // 顺子起点可能是 playedTile-2、playedTile-1、playedTile const needPairs [ [playedTile - 2, playedTile - 1], [playedTile - 1, playedTile 1], [playedTile 1, playedTile 2] ]; // 检查花色内且 hand 里包含这些牌 // 这里省略边界判断实际实现要逐个判断 index 是否越界 }这段只是骨架真正的实现还要考虑 playedTile 是否在 0-26 的花色区间内以及顺子组合不能跨花色。写这块代码时最常犯的错是把一手牌当成“无放回”来数比如hand.filter(v v playedTile).length 2其实同花色的同一张牌最多 4 张过滤后 number 可能是 4但碰只要 2 张杠要 3 张判断逻辑本身不会错容易错的是你拿手牌数组里可能已经包含别人打出的这张牌比如“碰”操作后那张牌还在手牌里要在出操作前先对手牌做快照排除。本地预判的意义在于 UI 弹窗响应快但服务器校验绝不能省。防作弊是棋牌游戏的命根子客户端只做展示和上报裁决权永远在服务器。Cocos Creator 客户端这边只需要把协议字段设计好操作后把整副手牌传出去给服务器重新计算一遍校验通过后再广播安全性和体验兼得。5. 达达麻将的五个翻车现场坐标、资源、动画与打包避坑5.1 手牌区 Widget 组件导致的排版抖动现象开局手牌到齐后低端 Android 机上牌位每帧轻微位移像在呼吸。玩家报告“牌在抖”但模拟器上完全正常。原因我给手牌容器挂了一个 Widget 组件对齐到父节点底部。Widget 在每次 Canvas resize 或子节点变化时都会重新计算对齐值手牌数量变化频繁重算次数多低端机 CPU 吃紧就出现抖动。本质上这不是 Widget 的错是我在不该用 Widget 的地方用了它。解决手牌区不用 Widget 约束改成固定坐标加 Layout 组件手动排。在GameConfig里定好手牌起点坐标每次手牌变化调用一次updateHandLayout()把每张牌按x baseX index * tileWidth摆放。发散思维想一步如果后续要支持玩家拖动排序这个手动布局也可以直接改造成“拖动后重排”比 Widget 更可控。5.2 开局瞬间白牌现象第一副牌发牌动画结束有的牌是纯白色几秒后才出现牌面。或者干脆一整局都是白板。原因牌面纹理用的是一张大图集图集异步加载未完成牌的 SpriteFrame 还没有拿到节点已经创建出来并渲染了于是显示默认的白色底图。一行director.getScene()也救不了因为资源加载不在渲染管线里是独立线程。解决场景加载阶段强制预加载图集。在进入牌桌场景之前调assetManager.loadBundle(gameRes)然后bundle.loadDir(tile_sheet)把整目录图集拉进内存。预加载完成前不出现在牌桌画面里配合一个 1-2 秒的“玩家准备中”遮罩既掩盖加载速度又避免白牌露出。这个坑的隐蔽点在于模拟器上本地文件读取快几乎不会复现白牌只有打 APK 装到真机、走远程资源或首次解包时才暴露。5.3 MotionStreak 拖尾在 Android 上掉帧现象发牌动画带拖尾效果iPhone 上流畅Android 千元机上动画一卡一卡甚至整个牌桌 UI 响应变慢。原因MotionStreak 组件每帧会生成新的顶点数据持续时间内路径越长、分段时间越短生成的顶点越多。Android 低端机的 GPU fill rate 有限顶点数一涨就顶不住。看日志会发现 Drawn Batch 数量不变但 draw call 耗时翻了好几倍。解决把 MotionStreak 的time从 0.3 改成 0.15minSeg改成 10 像素以上拖尾纹理缩小到 64x64 以内。如果牌桌同时有多个发牌动作比如“四人同时发牌”只给自家手牌这组做拖尾其他三家做成普通牌移动动画。这个优化做下来Android 掉帧基本消失视觉影响很小因为棋牌玩家更在意牌面清晰拖尾本来就是个点缀。5.4 打包 APK 时 JS 层编译报错现象构建 Android 工程时报TypeError: Cannot read property xx of undefined或者干脆表示找不到模块。构建日志指向的代码行在编辑器预览里完全正常。原因Cocos Creator 编辑器预览模式用的是浏览器环境而打包 APK 走的是 JSB 或原生引擎绑定某些浏览器自带对象会有差异。最常见的是我在代码里用了window.localStorage预览正常打包后 JSB 环境没有完整的 window 对象实际上有但 API 集合不一样代码跑到一半炸了。解决从第一天就养成写“平台安全代码”的习惯。访问window、document、localStorage前先判断存在性或者统一封装成一个StorageUtil.ts在真机环境用sys.localStorage在浏览器环境退回window.localStorage。这个坑最气人的是构建时不会报错运行到那一行才炸而且炸的时间很随机没有日志根本定位不到。血泪经验买一个低端 Android 真机做日常验证打包前跑一遍核心玩法至少能救回一半这类问题。5.5 UI 触摸穿透点牌时触发背景按钮现象玩家点击手牌打出时屏幕下方的聊天按钮或菜单按钮也跟着响应。玩家操作一次触发了两个动作。原因Cocos Creator 的触摸事件默认会向上冒泡而且节点如果没有挂 UI 组件拦截触摸会直接穿透到下面的节点。牌的节点上挂了Button组件但它没有阻止事件继续传递导致牌和背景按钮同时收事件。解决在牌的根节点或操作按钮区域挂一个BlockInputEvents组件这个组件的作用就是把触摸事件拦截在该节点层级不让它冒泡。如果自定义触摸逻辑在回调里调用event.propagationStopped true也能达到同样效果。注意BlockInputEvents只拦截触摸不会影响节点自己的事件回调。这个坑虽然小但在棋牌游戏里很致命因为“打牌误触聊天”会让玩家直接放弃游戏。6. 用 MotionStreak 给发牌加一道拖尾一套参数照着抄发牌动效是棋牌游戏里最值得砸成本的部分因为它决定了游戏的第一手感。MotionStreak组件在 Cocos Creator 3.x 里可以用来做拖尾效果具体参数我建议按这套起步值来再根据真机表现调整。参数建议值作用time0.15-0.2拖尾持续时长越短越轻盈太长容易糊minSeg10-15最小分段距离低于此值不生成新顶点可有效减少顶点数strokeWidth80-120线条宽度宽度过大会遮挡牌面texture渐变拖尾纹理用带透明度的渐变图避免生硬截断// DealEffect.ts import { _decorator, Component, MotionStreak, Vec3, tween } from cc; ccclass(DealEffect) export class DealEffect extends Component { property(MotionStreak) streak: MotionStreak null; property duration 0.3; play(from: Vec3, to: Vec3): void { this.node.setPosition(from); this.streak.enabled true; tween(this.node) .to(this.duration, { position: to }) .call(() { this.streak.enabled false; this.node.setPosition(to); }) .start(); } }这段代码的逻辑play方法接收发牌起点和终点坐标先把牌放到起点开启MotionStreak然后tween让牌在duration时间内移动到终点。移动结束后关闭streak并复位位置。关键在于streak.enabled false必须在 tween 的回调里而不是在 tween 开始前否则拖尾根本不会生成。很多同学第一次用都会把enabled开关写反结果牌飞到了拖尾没有或者拖尾一直留在原地不消失。参数调整的经验是先把time调到 0.05 测试这时候能看到拖尾是否存在再慢慢加长直到视觉上“有轨迹但又不糊”。minSeg反过来越大越省性能但如果大到 30 以上拖尾会变成一段一段的虚线这时候还是要调小。纹理用一张 64x64 的渐变图即可不推荐用纯色纯色拖尾看起来像一条蛇很出戏。我个人的习惯是把这个DealEffect挂在一个节点上复用不每张牌都挂组件。发牌时把当前要发的牌挪到起始位调用play等下一张牌时再重复。这样整个发牌序列只用到 1 个MotionStreak实例性能压力几乎为零。手牌数量多的场景比如杠后补牌、碰后展示也可以复用这套逻辑只是把from坐标换成对应位置。做棋牌项目我越来越认同一句话规则可以在服务器层写得严丝合缝但玩家能感知到的“好玩”往往藏在这些毫秒级的动效和手感里。这么多年下来最大的教训就是不自己骗自己——模拟器顺了不算顺真机跑三十分钟不掉帧才算过了第一关。希望帮到你。本文还有配套的精品资源点击获取