简介这份资源是面向棋牌游戏开发者与Cocos Creator学习者的达达麻将完整项目源码适合具备一定JavaScript基础、希望了解网络棋牌游戏前后端架构的初中级开发者可用于学习麻将规则实现、玩家匹配与数据同步等核心逻辑。压缩包共约2000个文件整体51.62MB以json配置、js脚本、meta资源描述、png图片、prefab预制体、anim动画、mp3音效为主另含Node.js服务端相关模块与MySQL建表脚本覆盖客户端表现层到服务端数据层的完整链路。目前已有3244人学习下载热度较高。项目基于Cocos Creator与JavaScript实现前端交互与游戏状态管理后端采用Node.js处理登录、匹配与数据同步MySQL存储玩家信息、积分与对局记录并涉及热更新、性能优化与安全防护等上线运营要点便于读者对照源码理解棋牌游戏从开发到部署的完整流程。1. 从零拆解 cocos creator 达达麻将棋牌游戏一套可复现的房卡制玩法骨架很多人第一次听到「cocos creator 达达麻将棋牌游戏」这个组合脑子里冒出来的是一堆散点Cocos Creator 是引擎麻将棋牌是品类达达是玩法风格。真正落到工程上它其实是一件事——用 Cocos Creator 搭一套房卡制、四人一桌、带托管和断线重连的麻将玩法骨架。我见过太多团队卡在同一个地方单机跑得挺欢一接房间和结算就崩玩家掉线回来牌局对不上最后只能推倒重来。这篇笔记不讲空泛的引擎介绍而是把「达达麻将」这类玩法从数据模型、房间状态机、发牌算法到结算校验按能照着复现的粒度拆开。适合已经会写 TypeScript、想入局棋牌但没跑通过完整一局的人也适合做过单机麻将、想补上联网和防作弊这块短板的熟手。读完你至少能判断这套骨架值不值得自己搭哪些坑必须提前埋点。2. 达达麻将的玩法骨架与数据模型怎么定先把「达达麻将」这个叫法说清楚。它不是一个官方标准玩法而是国内地方麻将里一类偏快节奏、房卡开桌、胡牌番型相对收敛的玩法代称。不同地区规则差异很大所以工程上第一件事不是写代码而是把规则收敛成一份可配置的数据模型。你如果一上来就按某个地区的完整番型硬编码后面每加一个玩法都要改核心逻辑这是最常见的翻车起点。2.1 先定牌型、座位和回合三张表麻将工程的核心不是渲染是数据。我一般会先落三张配置表牌型表、座位表、回合表。牌型表描述每种牌有多少张、有没有花牌、癞子怎么算座位表描述东南西北四个座位的固定顺序和庄家轮转回合表描述出牌、碰、杠、胡的优先级。这三张表定完后面的状态机才有依据。// tileConfig.ts 牌型配置以万、条、筒各 1-9每种 4 张为例 export interface TileConfig { suit: wan | tiao | tong; // 花色 rank: number; // 点数 1-9 count: number; // 每种牌的张数标准是 4 } export const TILE_CONFIG: TileConfig[] ([wan, tiao, tong] as const) .flatMap((suit) Array.from({ length: 9 }, (_, i) ({ suit, rank: i 1, count: 4, // 关键参数四人麻将每种 4 张共 108 张 })), ); // 座位固定顺序庄家轮转依赖这个顺序 export const SEAT_ORDER [east, south, west, north] as const; export type Seat (typeof SEAT_ORDER)[number];这段配置看起来简单但有两个参数必须提前想清楚。第一是count标准麻将是每种 4 张但有些地方玩法会去掉某几种牌或者加花牌这个值一变后面发牌和剩余牌堆的计算全要跟着变。第二是座位顺序SEAT_ORDER决定了庄家轮转和出牌方向如果你后面要做「血战到底」这种一炮多响的玩法座位顺序还会影响结算顺序。我见过有人把座位顺序写成对象 key 遍历结果顺序不稳定庄家轮转偶尔错位排查了半天。2.2 房间状态机从等待到结算的六个状态单机麻将和联网麻将最大的区别是房间状态必须显式管理。我一般会定义一个枚举把一局的生命周期切成六个状态等待、准备、发牌、出牌、结算、解散。每个状态只允许特定的操作比如「出牌」状态下才能碰杠胡「结算」状态下只能看结果或准备下一局。export enum RoomState { WAITING waiting, // 等待玩家加入 READY ready, // 四人到齐等待开始 DEALING dealing, // 发牌中禁止操作 PLAYING playing, // 出牌阶段允许碰杠胡 SETTLE settle, // 结算中展示番型和分数 DISMISS dismiss, // 房间解散 } // 状态迁移白名单只允许这些迁移防止非法状态跳转 export const STATE_TRANSITION: RecordRoomState, RoomState[] { [RoomState.WAITING]: [RoomState.READY, RoomState.DISMISS], [RoomState.READY]: [RoomState.DEALING, RoomState.DISMISS], [RoomState.DEALING]: [RoomState.PLAYING], [RoomState.PLAYING]: [RoomState.SETTLE], [RoomState.SETTLE]: [RoomState.READY, RoomState.DISMISS], [RoomState.DISMISS]: [], };这个白名单是我踩过坑之后加的。早期版本没有迁移校验客户端发一个「结算」请求服务端直接跳状态结果牌局还没打完就结算了分数算错。加上STATE_TRANSITION之后任何不在白名单里的迁移都会被拒绝日志里能直接看到是谁在什么状态下发了非法请求。参数上要注意DEALING状态必须禁止一切玩家操作因为发牌是服务端行为客户端此时只能等不能出牌也不能碰。2.3 发牌算法洗牌、发牌、剩余牌堆三件事发牌看起来是随机但棋牌游戏里「随机」是要可复现、可校验的。我一般用带种子的伪随机种子由服务端生成并记录这样一旦有争议可以复现整局。洗牌用 Fisher-Yates发牌按座位顺序每人 13 张庄家多一张剩下的进剩余牌堆。// 带种子的伪随机保证同一局可复现 function seededRandom(seed: number) { let s seed; return () { s (s * 9301 49297) % 233280; return s / 233280; }; } export function shuffleTiles(seed: number): string[] { const tiles: string[] []; TILE_CONFIG.forEach(({ suit, rank, count }) { for (let i 0; i count; i) tiles.push(${suit}_${rank}); }); const rand seededRandom(seed); // Fisher-Yates 洗牌从后往前交换 for (let i tiles.length - 1; i 0; i--) { const j Math.floor(rand() * (i 1)); [tiles[i], tiles[j]] [tiles[j], tiles[i]]; } return tiles; }seed这个参数是整个发牌可复现的关键服务端必须把它和牌局 ID 一起存下来。发牌时每人 13 张庄家 14 张剩余牌堆数量要实时同步给客户端因为玩家需要知道还剩多少张牌来判断局势。这里有个容易忽略的点剩余牌堆不能一次性全发给客户端否则等于把整副牌暴露了客户端只应该拿到自己手牌和剩余张数。3. 用 Cocos Creator 把一局麻将跑起来的最小实现数据模型定完接下来是让它在 Cocos Creator 里动起来。这一章的目标不是做完整 UI而是跑通「发牌 → 出牌 → 碰杠 → 胡牌」这条最小链路。我建议先用纯逻辑层跑通再接渲染否则你会被节点层级和动画干扰判断。3.1 逻辑层与渲染层分离的目录结构Cocos Creator 项目里我一般把逻辑层放在assets/scripts/core渲染层放在assets/scripts/view网络层放在assets/scripts/net。逻辑层不引用任何cc模块纯 TypeScript这样可以在 Node 环境里直接跑单元测试。渲染层只负责把逻辑层的数据映射成节点。assets/ scripts/ core/ # 纯逻辑不依赖 cc tileConfig.ts roomState.ts deal.ts huCheck.ts view/ # 渲染依赖 cc HandView.ts TableView.ts net/ # 网络 RoomClient.ts这个结构的好处是胡牌校验这种核心逻辑可以在命令行里跑测试不用启动引擎。我见过有人把胡牌算法写在组件里结果每次测都要开编辑器效率极低。core目录下的文件不要 importcc这是硬约束。3.2 手牌渲染用 Prefab 加对象池别直接 new Node手牌渲染最常见的性能坑是每次发牌都new Node一局下来节点反复创建销毁GC 压力大。正确做法是用 Prefab 加对象池。Cocos Creator 自带NodePool我一般会把手牌节点做成 Prefab初始化时预热 14 个发牌时从池里取出牌时回收。import { _decorator, Component, Node, Prefab, instantiate, NodePool } from cc; const { ccclass, property } _decorator; ccclass(HandView) export class HandView extends Component { property(Prefab) tilePrefab: Prefab null!; private pool new NodePool(); // 预热对象池避免运行时频繁创建 initPool(size: number) { for (let i 0; i size; i) { this.pool.put(instantiate(this.tilePrefab)); } } // 取一张牌节点池空则新建 getTileNode(): Node { return this.pool.size() 0 ? this.pool.get()! : instantiate(this.tilePrefab); } // 出牌后回收节点 recycle(node: Node) { this.pool.put(node); } }initPool的size参数建议设成 14因为一局手牌最多 14 张。getTileNode里池空时兜底新建避免发牌时池不够用报错。回收时机要卡在出牌动画结束后不能一出牌就回收否则动画会闪。这个细节我调了很久血泪经验是对象池的回收一定要等动画回调不要用定时器猜时间。3.3 出牌与碰杠胡的请求响应链路联网麻将的操作都是「客户端请求 → 服务端校验 → 广播结果」。客户端不能自己改状态只能发意图。我一般定义一套消息协议出牌、碰、杠、胡各一个消息类型服务端校验合法性后广播给四个玩家。// 客户端发送出牌意图 export interface PlayTileReq { roomId: string; seat: Seat; tile: string; // 要打出的牌如 wan_5 seq: number; // 客户端本地序号用于去重 } // 服务端广播的操作结果 export interface PlayTileResp { seat: Seat; action: play | peng | gang | hu | pass; tile?: string; nextSeat: Seat; // 下一个该操作的座位 remainCount: number; // 剩余牌堆数量 }seq这个字段是防重放的关键客户端每次请求带一个递增序号服务端记录已处理的序号重复的直接丢弃。nextSeat由服务端算好下发客户端不要自己算否则座位轮转逻辑两边不一致会出现「该我出牌但界面没反应」的玄学问题。remainCount每次操作后都要更新玩家靠它判断局势。3.4 胡牌校验把番型拆成可组合的规则胡牌校验是麻将逻辑里最绕的部分。我的做法是把胡牌拆成两个层次先判断「能不能胡」牌型是否满足基本胡牌结构再判断「胡了算几番」番型组合。基本胡牌结构用递归拆解番型用规则数组匹配。// 判断手牌是否满足基本胡牌结构n 个刻子 1 个对子 export function canHu(tiles: string[]): boolean { const counts new Mapstring, number(); tiles.forEach((t) counts.set(t, (counts.get(t) || 0) 1)); const keys [...counts.keys()].sort(); // 尝试每个可能的对子作为将牌 for (const key of keys) { if ((counts.get(key) || 0) 2) { counts.set(key, counts.get(key)! - 2); if (checkMelds(counts, keys)) { counts.set(key, counts.get(key)! 2); return true; } counts.set(key, counts.get(key)! 2); } } return false; } // 递归检查剩余牌能否全部组成刻子或顺子 function checkMelds(counts: Mapstring, number, keys: string[]): boolean { const first keys.find((k) (counts.get(k) || 0) 0); if (!first) return true; // 全部拆完胡牌成立 const [suit, rankStr] first.split(_); const rank parseInt(rankStr, 10); // 尝试刻子 if ((counts.get(first) || 0) 3) { counts.set(first, counts.get(first)! - 3); if (checkMelds(counts, keys)) { counts.set(first, counts.get(first)! 3); return true; } counts.set(first, counts.get(first)! 3); } // 尝试顺子注意不能跨花色 const second ${suit}_${rank 1}; const third ${suit}_${rank 2}; if (rank 7 (counts.get(second) || 0) 0 (counts.get(third) || 0) 0) { counts.set(first, counts.get(first)! - 1); counts.set(second, counts.get(second)! - 1); counts.set(third, counts.get(third)! - 1); if (checkMelds(counts, keys)) { counts.set(first, counts.get(first)! 1); counts.set(second, counts.get(second)! 1); counts.set(third, counts.get(third)! 1); return true; } counts.set(first, counts.get(first)! 1); counts.set(second, counts.get(second)! 1); counts.set(third, counts.get(third)! 1); } return false; }canHu先枚举将牌再调checkMelds递归拆解。checkMelds里rank 7是顺子的边界因为 8、9 后面没有牌了。这个算法对标准胡牌够用但如果你要做七对、十三幺这类特殊牌型需要在canHu之前单独判断。番型计算我一般单独写一个calcFan函数输入手牌和胡牌方式输出番数和canHu解耦方便按地区规则替换。4. 联网同步与断线重连的避坑清单棋牌游戏上线后玩家反馈最多的不是玩法是「掉线回来牌不对」「碰了没反应」「结算分数错了」。这一章把这类问题按现象、原因、解决拆开都是实际踩过的。4.1 现象玩家断线重连后手牌和桌面不一致原因通常是服务端只存了最终状态没存操作日志重连时下发的快照和客户端本地状态对不上。解决方法是服务端维护一份操作日志重连时先下发完整快照再补发断线期间的操作。快照要包含手牌、桌面已出的牌、当前状态、当前该谁操作。export interface RoomSnapshot { roomId: string; state: RoomState; seats: RecordSeat, { hand: string[]; melds: string[][]; score: number }; tableTiles: string[]; // 桌面已打出的牌 currentSeat: Seat; // 当前该操作的座位 remainCount: number; lastSeq: number; // 最后处理的操作序号 }lastSeq是关键客户端重连后带上本地的lastSeq服务端只补发比它大的操作避免重复执行。快照里的hand只下发该玩家自己的手牌其他玩家的手牌不下发这是防作弊底线。4.2 现象碰杠胡请求发出后没反应原因多半是服务端校验失败但没回错误码客户端一直等。解决方法是所有请求都必须有响应成功走广播失败走单播错误码。客户端收到错误码后要复位按钮状态不能让玩家卡在「已点击」状态。// 服务端处理出牌请求失败必须回错误 function handlePlay(req: PlayTileReq, room: Room): void { if (room.state ! RoomState.PLAYING) { return sendError(req.seat, INVALID_STATE); // 状态不对明确回错 } if (room.currentSeat ! req.seat) { return sendError(req.seat, NOT_YOUR_TURN); // 没轮到你 } if (!room.seats[req.seat].hand.includes(req.tile)) { return sendError(req.seat, TILE_NOT_IN_HAND); // 手里没这张牌 } // 校验通过执行出牌并广播 doPlay(req, room); }这三个错误码覆盖了大部分「没反应」的情况。客户端收到NOT_YOUR_TURN要把操作按钮置灰收到TILE_NOT_IN_HAND要刷新手牌收到INVALID_STATE要重新拉快照。我一般会在客户端做一个错误码到提示文案的映射表方便排查。4.3 现象结算分数和玩家预期不符原因通常是番型计算和分数结算用了两套逻辑或者结算顺序受座位影响没处理好。解决方法是把番型计算和分数结算合并成一个纯函数输入完整牌局数据输出每个座位的分数变化这个函数要能单独跑测试。export interface SettleResult { seat: Seat; fan: number; // 番数 delta: number; // 分数变化正为赢负为输 } // 纯函数结算不依赖任何运行时状态方便测试 export function settle( winner: Seat, loser: Seat | null, // 点炮者自摸为 null fan: number, baseScore: number, ): SettleResult[] { const results: SettleResult[] []; if (loser) { // 点炮点炮者扣分赢家得分 results.push({ seat: winner, fan, delta: baseScore * fan }); results.push({ seat: loser, fan, delta: -baseScore * fan }); } else { // 自摸三家各扣分赢家得三份 SEAT_ORDER.forEach((s) { if (s winner) { results.push({ seat: s, fan, delta: baseScore * fan * 3 }); } else { results.push({ seat: s, fan, delta: -baseScore * fan }); } }); } return results; }baseScore是底分fan是番数这两个参数要可配置不同房间可以设不同底分。这个函数是纯的输入确定输出就确定测试时直接断言结果即可。我见过有人把结算写在广播回调里依赖当前房间状态结果一改玩法就出错后悔药都没得吃。4.4 现象托管和超时处理导致牌局卡死原因通常是超时定时器和玩家操作竞争玩家在超时最后一刻出牌定时器也触发了两边都执行。解决方法是服务端用操作序号做幂等超时托管也走同一个操作入口带一个特殊标记序号重复就丢弃。// 超时托管走和正常出牌同一个入口标记为托管 function onTurnTimeout(room: Room, seat: Seat): void { const autoTile pickAutoTile(room.seats[seat].hand); // 托管选牌策略 handlePlay( { roomId: room.id, seat, tile: autoTile, seq: room.nextSeq() }, room, ); }pickAutoTile是托管选牌策略最简单的打最右边一张复杂点可以按孤张优先。关键是托管和正常操作走同一个handlePlay这样校验和广播逻辑只有一份不会出现两套逻辑不一致。nextSeq保证每次操作序号唯一重复的直接被幂等逻辑丢弃。5. 番型配置化与结算校验的进阶做法前面把骨架跑通了这一章讲怎么让这套骨架能撑住多种玩法。核心思路是番型配置化把「什么牌型算几番」从代码里抽出来变成数据运营改配置就能上新玩法不用改代码重新发版。5.1 用配置表描述番型而不是写死在代码里我一般用一张 JSON 表描述番型每条包含番型 ID、名称、番数、匹配条件。匹配条件用简单的表达式描述比如「手牌中有四个相同的刻子」对应melds.count 4。这样加新番型只需要加一行配置。{ fanTypes: [ { id: ping_hu, name: 平胡, fan: 1, condition: base }, { id: peng_peng_hu, name: 碰碰胡, fan: 2, condition: allTriplets }, { id: qing_yi_se, name: 清一色, fan: 4, condition: sameSuit }, { id: qi_dui, name: 七对, fan: 4, condition: sevenPairs } ] }condition字段对应代码里的判断函数我一般维护一个conditionMap把字符串映射到函数。这样配置表只描述「有哪些番型」具体判断逻辑在代码里两边解耦。加新番型时如果判断逻辑已有只加配置如果没有加一个判断函数再配一行。5.2 结算校验服务端算分客户端只展示防作弊的核心原则是所有涉及分数的计算只在服务端做客户端只负责展示。客户端可以本地预演算分给玩家看但最终分数以服务端广播为准。我一般会在结算消息里带上服务端算好的番型和分数客户端直接渲染不做二次计算。export interface SettleBroadcast { roomId: string; results: SettleResult[]; // 服务端算好的分数 fanDetails: { seat: Seat; fans: string[] }[]; // 每个座位的番型明细 timestamp: number; }fanDetails里列出每个座位胡了哪些番型玩家能看到「为什么是这些分」减少争议。timestamp用于对账如果玩家反馈分数不对可以按时间戳查服务端日志。客户端拿到这个广播后只做展示不做任何加减。5.3 回放与对账把每局操作日志存下来上线后一定会遇到玩家说「我这局明明胡了但没算分」。这时候操作日志就是后悔药。我一般会把每局的操作日志按房间 ID 和局序号存下来包含每次操作的座位、动作、牌、序号、时间戳。对账时按日志重放一遍就能还原真相。字段类型说明roomIdstring房间 IDroundnumber局序号seqnumber操作序号递增seatSeat操作座位actionstringplay/peng/gang/hu/passtilestring操作的牌tsnumber服务端时间戳这张表建议存到独立的日志库不要和业务库混在一起避免影响主流程性能。查询时按roomId round索引能快速拉出整局日志。我一般还会加一个重放脚本输入日志输出最终分数用来验证结算逻辑。5.4 一个具体技巧用种子加日志做争议复现最后分享一个我常用的技巧。每局开始时服务端生成一个种子发牌用这个种子操作日志记录所有操作。一旦有争议用种子重新发牌再按日志重放操作就能完整复现整局。这个组合比单纯存快照更可靠因为快照可能被后续操作覆盖而种子加日志是不可变的。// 复现一局种子发牌 日志重放 function replay(seed: number, logs: OperationLog[]): SettleResult[] { const tiles shuffleTiles(seed); // 用种子重新发牌 const room createRoomFromTiles(tiles); // 按发牌结果建房间 logs.sort((a, b) a.seq - b.seq); // 按序号排序 logs.forEach((log) applyOperation(room, log)); // 逐条重放 return room.settleResult; // 返回最终结算 }replay函数是纯的输入种子和日志输出结算结果可以在测试环境反复跑。这个技巧帮我定位过好几次「分数不对」的问题最后发现都是客户端本地预演算分和服务端不一致导致的服务端本身没问题。我的习惯是任何涉及分数的争议先跑replay用数据说话不靠猜。希望帮到你。本文还有配套的精品资源点击获取
