游戏开发 on 方糖猫Blog

《princes》：用 Cocos Creator 写一款餐厅经营放置小游戏

Sat, 05 Sep 2020 21:00:00 +0800

《princes》：用 Cocos Creator 写一款餐厅经营放置小游戏

继《去赶海吧》之后，把更早做的一款餐厅经营小游戏也整理开源了，照例写篇文章介绍玩法和实现上的技术点。仓库名叫 princes（历史遗留命名，内容其实是餐厅），代码里还住着不少从其他项目移民过来的残留，这次一并"考古"出来。

开源地址：https://gitee.com/soulnew/princes
技术栈：Cocos Creator 2.3.4 + JavaScript
平台：微信小游戏（竖屏 720×1280）
规模：39 个脚本，约 4200 行代码，单主场景

游戏核心玩法一句话概括：开一家餐厅，顾客自动上门排队等位、走到餐桌点餐、用餐完留下金币，你点击收金币，再用金币解锁更多食物、餐桌和顾客皮肤——放置 + 点击收菜的经典经营循环。

一、玩法介绍

1.1 核心循环

玩家几乎不直接操作角色，核心是"看店 + 点击收钱 + 花钱解锁"：

graph LR
    A[顾客自动上门<br/>每15秒补1个] --> B{有空餐桌?}
    B -->|有| C[A*寻路走到餐桌]
    B -->|没有| D[门口排队等位]
    D -->|有空桌释放| C
    C --> E[头顶弹气泡点单]
    E --> F[用餐5秒<br/>点击气泡可加速]
    F --> G[桌边产出一堆金币]
    G --> H[玩家点击拾取]
    H --> I[解锁新食物/餐桌/顾客]
    I --> A

几个关键设计：

餐桌是稀缺资源：场上最多 10 个顾客（maxPlayer = 10），没桌子的顾客会在门口按队列序号排开站位，有空桌释放时队首补位、全队前移；
点单匹配：每个顾客皮肤有自己的"可点菜单"（foodList），随机点一道——这道菜已解锁就正常产金币，没解锁就显示"没有这道菜"的图标，等于告诉你"该去商店解锁了"；
巡游消费：顾客吃完饭不直接走，而是从酒柜、古董花瓶、海滩桌等 6 类装饰家具里洗牌出一份"参观清单"，逐件走过去参观，每件停留几秒再留下一笔金币——买装饰家具不只是好看，是真的能多赚钱；
邀请按钮：等不及可以点"邀请"立刻来一位顾客，这个入口同时服务每日任务和成就。

1.2 四屏地图与翻页

餐厅不是一张单屏地图，而是四个房间：海滩（left1）、大厅（mid）、剧院（right1）、花园（down1）。顾客在房间之间穿行时走"传送门"格子——比如大厅到海滩，先寻路到 (0,11) 这个门，切换父节点到海滩场景节点，再从海滩的入口格 (12,11) 继续寻路。

相机不是跟随式的，而是手动拖拽翻页：单轴锁定滑动，滑过屏宽 1/10 左右翻页、屏高 1/14 上下翻页。门口还有两个服务员（waiterPlayer），有顾客进门就弹出欢迎气泡 5 秒——不做实际传菜逻辑，纯氛围组。

1.3 成长线：解锁三件套

金币花在三个商店面板上：

商店	内容	解锁的意义
食物	54 道菜，价格 100~153 递增	顾客点单能匹配上，用餐才产金币
家具	大厅 6 组餐桌（每组 3 级升级）+ 各房间散桌 + 装饰家具	新餐桌 = 多一个接待座位；装饰家具 = 巡游产金币点
顾客	50 种皮肤	新皮肤进入上门顾客的随机池

顾客皮肤的名字很有梗：学士、水电工、警长、老板、小青龙、法师、熊猫、海贼、管道工、侦探、伯爵、外星人、厨神、牙医、流浪歌手、开膛手、屠夫、王少爷、腹肌男、特工K、机器人……基本是把能想到的梗都塞进去了。

1.4 成就与每日任务

15 条成就分 5 种类型：解锁指定物品、解锁 N 种某类物品、服务 N 个顾客、累计金币（500/5000/10000/30000）、邀请 N 次，奖励统一 5000 金币；
每日任务从 7 条里随机洗牌取 6 条（服务顾客 2 次、累计 800 金币、邀请 2 次、招待指定顾客 2 次等），按本地日期键 年_月_日 翻日重置，还会随机指定"今天要招待某位顾客"。

两个系统都有红点提醒，领取后自动检查链上下一档成就。

二、技术亮点

项目不大（4000 行出头），但有几个点是自己撸出来的轮子，值得展开。

2.1 手写 A* + “传送门"式跨屏寻路

寻路没有用任何库，AStar.js（217 行）是手写的标准实现：

地图是 position.json 里一个 21×13 的一维数组（273 个元素，0 可走，其他障碍），screenManager 按屏幕尺寸算出格子边长，做格坐标到像素坐标的换算；
AStarStep 封装 g/h/position/last，f 是 g+h 的 getter；启发函数用曼哈顿距离，八方向扩展，斜走 14、直走 10（经典的 √2×10 近似）；
拿到格子路径后，把每一格转成 cc.moveTo(1, 像素坐标) 拼成 cc.sequence 播放——每格固定走 1 秒，移动节奏完全由动画序列驱动，不需要 update 里手动插值。

跨屏是这套寻路最有意思的部分——四个房间不是一张大地图，而是各自独立的节点树，靠 6 对"门坐标"缝合：

graph LR
    A[当前房间] -->|寻路到门格 mid_left1| B[门 0,11]
    B -->|切换父节点| C[目标房间]
    C -->|从入口格 left1_mid 继续寻路| D[最终目标]

大地图拆成小地图 + 门对，每个房间的寻路空间始终只有 21×13，复杂度和内存都可控，是小工程里很实用的拆法。

2.2 自研虚拟列表 ListView

Cocos 2.x 官方没有现成的虚拟列表，商店、成就、每日任务的长列表就手写了一个（ListView.js，380 行，项目内最大文件）：

NodePool 复用：划出视野的 item 回池，进入视野的从池里取或 instantiate；
增量填充：_filledIds 记录当前树上已填充的索引，update() 每帧用 content 的滚动偏移算起始 item 索引，变了才触发 updateView，只回收越界的、只补缺失的；
Adapter 模式：ListAdapter 持有数据和 item 脚本名，updateView 里 item.getComponent(componentName).setData(data)——Android ListView 的味道很浓，View 和数据彻底分离；
支持多列网格（oneLineItemNumber）、上拉/下拉回调、监听 refreshScollView 事件做局部刷新。

家具面板没用这个 ListView，而是手写了一个更简的裁剪：视野内 opacity=255、视野外 opacity=0。同一项目里两种方案并存，算是"够用就好"和"造个轮子"的对照组。

2.3 餐桌分配：一个微缩排队系统

realTimeData.js 里藏着一个小小的服务台排队模型：

activeFurnitureData 是"空闲桌池”，顾客来了随机抽一张（splice 取出），用完 push 回去；
没桌时顾客进 waitTableQuenue，按 index/maxPlayer 比例在门口插值站位——队伍有多长，人就排多密；
空桌释放时遍历等待队列，队首补位、全队回调前移。

没有定时器轮询，全靠事件驱动，几十行代码把"等位"这个经营游戏的核心张力做出来了。

2.4 运行时程序化动画：两帧图集走天下

所有角色（50 个顾客皮肤 + 2 个服务员）的走路动画都是运行时代码创建的。AnimationBase.js 只有 23 行：

let clip = cc.AnimationClip.createWithSpriteFrames(frames, 1);
clip.wrapMode = cc.WrapMode.Loop;

美术只需要给每个皮肤画两帧（icon/icon2），代码动态建 clip 循环播放，“两帧鬼畜踏步"反而有一种魔性的喜感。50 套皮肤 = 100 帧图 + 一段 23 行的代码，动画资源维护成本为零。这个思路和《去赶海吧》的皮肤动画一脉相承。

2.5 金币堆：对象池 + 聚合拾取

金币是这个游戏最高频的创建/销毁对象，处理上花了最多心思（git 历史里"金币堆积优化"“金币拾取动画效果修改"好几个 commit 都在打磨这块）：

金币走 cc.NodePool（上限 50），生成时随机旋转、1 秒散落动画到桌边随机位置；
同一格子的金币记入 nearGroup 按堆聚合，面额累加进 valueMap——十份饭钱堆成一坨，而不是十个独立节点；
池满时 getGoldByMoveNearby 从邻居堆"借"一个实体过来复用；
点击一堆 → 整堆回收，合成一个 “+总额” 数字标签飞向屏幕左上角的 HUD，飞行时长按距离等比计算，落地才到账。

性能和手感都照顾到了：节点数有上限，拾取有"整堆收进腰包"的爽感。

2.6 事件驱动与成就三态流转

全局只有一个 50 行的事件中心（eventuality.js，出自 Crockford《JavaScript 语言精粹》里的 eventuality 函数），只有 fire/on/removeListener 三个方法，所有跨模块通信——loadover、addGold、unLock、serverPlayer、invite、arriveAtGate、showDialog——都走它。

成就/每日任务系统（两个 Manager 合计 660 行）建立在这个事件中心上，数据按三态流转：

graph LR
    A[unachieveMap<br/>未达成 按类型分桶] -->|事件计数达标| B[waitPayMap<br/>达成待领取]
    B -->|点击领取| C[已领取<br/>写入存档]
    C -->|自动检查| D[链上下一档成就]

事件一来，只检查对应桶里的成就，不用全表扫描；领取后自动把下一档（服务 10 人 → 服务 50 人 → ……）挪进未达成桶继续监听。

三、整体架构一览

graph TD
    subgraph 场景层
        L[loading.fire<br/>微信分包加载] --> G[game.fire<br/>主场景 103节点]
    end
    subgraph 入口与全局
        G --> GAME[game.js<br/>顾客生成/对象池]
        GL[global.js<br/>playerData/event/realTimeData]
        GAME --> GL
    end
    subgraph 玩法层
        GAME --> P[player.js<br/>顾客AI: 排队/寻路/点单/巡游]
        GAME --> W[waiterPlayer.js<br/>迎宾氛围组]
        GAME --> FM[FurnitureManager<br/>家具摆放/餐桌注册]
        GAME --> GM[GoldManager<br/>金币堆/拾取]
        P --> AS[AStar.js<br/>21×13格子寻路]
        P --> SM[screenManager<br/>格子坐标系/跨屏门]
    end
    subgraph 系统层
        AM[AchievementManager<br/>15条成就]
        DM[DailyTaskManager<br/>每日任务随机6条]
        LV[ListView<br/>自研虚拟列表]
        GUI[guide.js<br/>HUD与五个面板]
    end
    subgraph 数据层
        PD[player-data.js<br/>6份json配置+localStorage存档]
        RT[realTimeData.js<br/>餐桌队列/对象池/运行时状态]
    end
    GL --> AM
    GL --> DM
    GL --> PD
    GL --> RT
    GUI --> LV

数据分三层：defines.js 常量表（配置路径 / 存档键 / 事件名）、player-data.js 持久层（6 份 json 配置 + localStorage 存档，配置是 Excel 手填导出的）、realTimeData.js 运行时状态（对象池、餐桌队列、zIndex 发号器）。首次进游戏送 400 金币，默认解锁每类第一个条目。

四、找茬彩蛋

和《去赶海吧》一样，代码里的瑕疵原样保留，欢迎找茬：

A 代价函数传错参*（AStar.js:87）：算邻居格移动代价时，_costToMove(borderPosition, finish) 把终点当成上一个节点传了进去，导致大量格子被按斜走 14 计费、g 值普遍虚高。好在曼哈顿 h 也偏小，错误互相稀释，路还是能找对，只是已经不是标准 A* 了。
全项目调了一个不存在的方法：事件中心只实现了 removeListener，但十几处 onDestroy 里都在调 global.event.off(...)——调用即 TypeError，只是主场景从不销毁所以没炸过。就算有 off，传进去的也是新建箭头函数，永远匹配不上原监听器。
死代码雷区（utils/pathSearch.js）：另一套从未被实例化的 A*，里面有 this.year = '2002' 调试残留、原型方法引用闭包变量（调用即 ReferenceError）、严格模式下裸赋值，是从网上教程抄来没跑通的草稿。paopao.js 和 food.js 则是从泡泡龙/三消项目移民来的——food.js 的 onLoad 会调一个不存在的方法，挂上节点必崩，所以它谁也没挂。
拼写宇宙：createPalyer、walktoTabel、distence、memuPanel 全文通行；最惨的是 awarddiamand（成就表）和 awarddiamond（家具表）两种拼法并存，AchievementItem.getAward 只认前者，家具表里的钻石奖励永远读不到。
每日任务污染成就存档（DailyTaskManager.js:220）：每日服务计数误写进了成就用的总计数键；payAward 的 switch 里还有两个永远进不去的 undefined case。

另外 defines.js 里挂着 9 个根本不存在的配置路径（engineerNameConfig……“工程师"暴露了这是从另一个项目复制来的），food.json 里 54 道菜的名字是"食物1"到"食物54”——明显的占位数值没来得及填。

五、写在最后

从 git 历史能还原出开发顺序：跨屏寻路 → 桌子排队 → 成就系统 → 每日任务 → 钻石 → 金币特效与堆积优化 → 层级修正——先把核心玩法立住，再一层层包外围系统，最后打磨手感。

这是一个典型的个人开发者"麻雀型"项目：4000 行代码里同时住着写得相当讲究的虚拟列表、排队模型、跨屏寻路，和成堆的复制粘贴残留、拼写错误与失效代码。亮点和找茬各占一半，反而更适合做"真实项目代码考古"的样本——毕竟真实项目从来不是教科书。

源码在 https://gitee.com/soulnew/princes，欢迎 Star，也欢迎提 Issue 交流。

教你打麻将

Wed, 24 Jun 2020 14:00:00 +0800

教你打麻将

文章面向从未接触过联网游戏开发的读者，所以前半部分会把"联网棋牌游戏到底是怎么跑起来的"讲清楚，中间穿插真实代码层面的例子；后半部分专门开一章讲四川麻将的新手实战策略——毕竟做麻将游戏的人，自己先得会打麻将。

服务端：Java + Spring Boot + Netty（netty-socketio）+ Hazelcast + MySQL
客户端：Cocos Creator / JavaScript

一、先搞明白：联网棋牌游戏到底是怎么回事

1.1 单机游戏和联网游戏的本质区别

单机游戏里，所有逻辑都在你自己的设备上运行，规则由你的设备说了算。联网游戏不行——四个人打麻将，谁摸了什么牌、谁点了炮，必须有一个"裁判"说了算，否则每个人的手机都各算各的，立刻就乱套了。

这个"裁判"就是服务器。联网棋牌游戏的基本模型是：

graph TB
    subgraph 玩家设备
        C1[玩家A的手机<br/>Cocos Creator 客户端]
        C2[玩家B的手机]
        C3[玩家C的手机]
        C4[玩家D的手机]
    end
    S[游戏服务器<br/>贝密：Spring Boot + Netty]
    DB[(MySQL<br/>账号/战绩/房卡)]
    CACHE[(内存缓存 Hazelcast<br/>房间/牌局实时状态)]

    C1 <-->|WebSocket 长连接| S
    C2 <--> S
    C3 <--> S
    C4 <--> S
    S --> CACHE
    S -.异步落盘.-> DB

几个关键点：

牌在服务器手里。洗牌、发牌都在服务器上做，客户端只负责"显示"和"发指令"。你在手机上点"打出三万"，本质是给服务器发了一条消息：doplaycards: "12"，服务器校验"现在确实轮到你、你手里确实有三万"之后，才广播给全桌人。
每个人看到的信息不同。服务器把同一局牌的状态，按"你能看到什么"过滤后分别发给四个人——你只能看到自己的手牌和别人打出来的牌。这叫信息不对称，也是棋牌游戏和射击游戏最大的不同：状态同步必须分人定制。
防作弊的第一道防线就是"服务器权威"。客户端想赖牌（打出一张自己没有的牌），服务器直接拒绝。

1.2 为什么用 WebSocket 而不是 HTTP

没接触过联网游戏的人容易问：发消息不就是调接口吗，用 HTTP 不行吗？

不行，因为 HTTP 是"问一句答一句"，服务器没法主动找你。而棋牌游戏里大量事件是服务器主动推的：轮到你出牌了、有人碰了你的牌、房间人齐了……这些都需要服务器随时推消息给客户端。WebSocket 是一条建立后一直保持的双向通道，双方随时可以说话，延迟低、开销小。贝密用的 netty-socketio 就是在 Netty 上实现了 Socket.IO 协议（跑在 WebSocket 上），客户端 Cocos Creator 里直接用 socket.io 的 JS 库连。

1.3 房卡模式：一张"虚拟门票"

贝密 0.8.0 主打房卡模式，这也是 2016-2018 年棋牌游戏爆发的典型商业模式：

你在商城购买"房卡"（虚拟道具，存在 MySQL 里）；
你想和朋友打牌，就"开房"——消耗房卡，服务器生成一个 6 位数字房号（贝密里由 GameEngine.creatGameRoom 生成）；
朋友在大厅输入房号进房（客户端发 searchroom 事件），人齐开局；
打完约定的局数，服务器出结算单，房间销毁。

和陌生人随机撮合的"大厅模式"相比，房卡模式本质上卖的是"熟人社交的场地"，技术上则多了一个"按房号精确找房"的入口。

二、贝密的整体架构拆解

2.1 架构总览

graph LR
    subgraph 客户端
        A[Cocos Creator<br/>dizhu / majiang 模块]
    end
    subgraph 服务端 com.beimi
        B[GameEventHandler<br/>Socket 事件入口]
        C[GameEngine<br/>游戏总调度]
        D[自研状态机<br/>BeiMiStateMachine]
        E[Board 牌局内存模型<br/>MaJiangBoard / DuZhuBoard]
        F[Action/Task<br/>出牌·结算·计时任务]
    end
    subgraph 存储层
        G[(Hazelcast<br/>房间/牌局/玩家/撮合队列)]
        H[(cache2k<br/>过期回调当计时器)]
        I[Disruptor RingBuffer<br/>异步事件]
        J[(MySQL JPA)]
        K[(Elasticsearch)]
    end

    A <-->|WebSocket /game namespace| B
    B --> C --> D --> E
    D --> F
    E --> G
    F --> H
    C --> I
    I --> J
    I --> K

各层职责一句话概括：

GameEventHandler：所有 @OnEvent 端点都在这里，负责把客户端消息翻译成人话（比如把 "12,13" 解析成字节数组），然后交给 GameEngine；
GameEngine：总调度，加房、开局、出牌、杠碰胡、离房、解散房间都从这儿过；
自研状态机：驱动"房间"这个对象的生命周期（后面细讲）；
Board 内存模型：一局牌的完整状态（四家的手牌、桌面牌、轮到谁、倍率），只活在 Hazelcast 内存缓存里；
存储分层：实时状态全在 Hazelcast，MySQL 只存账号/战绩/房卡流水，而且是通过 Disruptor 异步写入——牌局进行中的一秒钟都不等数据库。

2.2 一次出牌的完整旅程（以麻将为例）

这是最核心的一条链路，用实际代码里的事件名走一遍：

sequenceDiagram
    participant P1 as 玩家A客户端
    participant H as GameEventHandler
    participant E as GameEngine
    participant B as MaJiangBoard
    participant T as 计时器(cache2k)
    participant P2 as 其他玩家客户端

    P1->>H: emit("doplaycards", "12")
    H->>E: takeCardsRequest(token, card)
    E->>B: 出牌校验 + 从手牌移除
    E->>T: remove(roomid) 取消A的出牌倒计时
    E-->>P2: 广播 "command": takecards
    E->>E: checkMJCard 遍历其他家<br/>查 杠/碰/吃/胡
    alt 有人能杠碰胡
        E->>T: 挂5秒等待任务(DEAL事件)
        P2->>H: emit("selectaction", "peng")
        H->>E: actionEventRequest 执行碰
    else 无人响应
        E->>B: dealRequest 下家抓牌
        E-->>P2: 广播 "command": dealcard
        E->>T: 挂8秒出牌任务<br/>(超时自动打)
    end

举例说明：假设你打出一张"五筒"，服务器干的事依次是——

校验：轮到你、你有五筒、这张牌合法；
把你 8 秒的出牌倒计时从计时器缓存里删掉（你不主动出，超时会由 CreateMJPlayCardsTask 强制替你出）；
广播给全桌：“A 打了五筒”；
挨个问另外三家：你能碰吗？能杠吗？能胡吗？（定缺了筒子的那家直接跳过——这就是四川麻将的规则在代码里的体现，GameUtils.processMJCard 里定缺花色不参与判断）；
如果 B 能碰，给 B 弹"碰/过"按钮，牌局挂起 5 秒等他决定；B 点了"碰"，就执行碰、轮到 B 出牌；
如果三家都"过"，下家自动摸一张牌，服务器先替他检查一次"摸上来的牌能不能暗杠/自摸"，然后通知他出牌，重新挂上 8 秒倒计时。

整个过程中，客户端只做两件事：把服务器的消息渲染成动画，把玩家的点击发给服务器。

2.3 房间的状态机流转

房间是有生命的：创建、等人、人齐、开局、结算、销毁。贝密没有用 Spring StateMachine，而是自研了一个极简状态机（core/statemachine 包），每种游戏一个 Bean：

stateDiagram-v2
    [*] --> NONE
    NONE --> CRERATED: ENTER 创建房间
    CRERATED --> WAITTING: JOIN 玩家陆续进房
    WAITTING --> READY: ENOUGH 人齐
    WAITTING --> WAITTING: AUTO 超时补AI机器人
    READY --> BEGIN: RAISEHANDS 全员准备
    BEGIN --> LASTHANDS: 发牌完成
    LASTHANDS --> PLAY: 庄家打出首张
    PLAY --> PLAY: DEAL/PLAYCARDS<br/>摸牌出牌循环
    PLAY --> END: ALLCARDS 有人胡牌/牌摸完
    END --> [*]: 结算发战报

状态机里每个"事件"对应一串 Action（比如麻将的链路是 EnterAction → JoinAction → EnoughAction → SelectAction(定缺) → MJRaiseHandsAction → DealMJCardAction → PlayMJCardsAction → AllCardsAction），业务代码只需要一句 game.change(room, event, intervalSeconds)，状态机负责找到对应 Action 执行，并由 Action 顺手创建下一个延时任务，形成闭环。

三、断线重连：联网游戏逃不掉的工程问题

新手最容易低估的就是这块。手机上打牌，来个电话、进个电梯，连接说断就断。贝密的处理方式是"托管 + 快照恢复"：

flowchart TD
    A[玩家网络断开] --> B{服务器收到<br/>OnDisconnect}
    B -->|玩家正在对局中| C[标记 OFFLINE<br/>进入托管状态]
    C --> D[计时器超时后<br/>auto=true 自动出牌]
    D --> E{玩家重连?}
    E -->|emit recovery| F[GameEngine 查缓存<br/>发现该房间有进行中的 Board]
    F --> G[下发 RecoveryData 全量快照:<br/>自己的手牌/桌面牌/轮到谁/剩余倒计时25s]
    G --> H[客户端按快照重建牌桌画面]
    E -->|一直没回来| I[AI托管打到本局结束]

举例：你出牌出了半局断网了，服务器不会暂停牌局等你（其他三个人不答应），而是把你标记为 OFFLINE，由超时任务替你"摸什么打什么"。30 秒后你连回来了，客户端发 recovery，服务器把当前牌局的完整快照发给你，你的手机根据快照把桌面重新画出来，无缝接上。注意重连期间你是被托管的——所以掉线久了回来，往往牌已经很难看了，这是规则的一部分。

四、四川麻将新手致胜策略：一个结构化的决策框架

做了这么久的麻将游戏，经常被问"新手怎么提高胜率"。零散的口诀（“记牌"“防点炮”）新手记不住也用不上，所以这一章我把四川麻将的策略整理成一个结构化框架：先确立唯一的目标函数，再按"战略层 → 信息层 → 战术层 → 概率层"四个层级组织所有决策，最后给出血战到底的特有推论和新手错误清单。逻辑主线只有一句话：

麻将的每一步都是在信息不完备下做期望收益最大化的决策。四个层级分别回答：往哪走（战略）、知道什么（信息）、这巡打哪张（战术）、什么时候切换路线（概率）。

4.0 规则即策略：先立规则，再推结论

定缺：开局后每人必须选一门花色（万/筒/条）作为"缺门”，胡牌时手里不能有这门牌，摸到缺门的牌必须打掉。牌墙只有 108 张（三门花色，无风牌）。
血战到底：一家胡牌不结束牌局，剩下的人继续打，直到牌摸完或只剩一家没胡。点炮只有点炮者付分，最后没胡的人还要给已听牌的人"查叫"赔分。

从这两条规则可以直接推出三条战略推论，整章都是它们的展开：

信息压缩：定缺把每家的"有效牌域"从三门砍到两门，而且是公开信息。读牌成本比别的麻将低一个量级——新手也能读。
时间价值：牌局不因一人胡牌而结束，每张牌的价值随牌墙减少而衰减。“还剩几巡"是所有决策的隐含变量。
止损优先：点炮只由点炮者一人付分、没胡要赔查叫——落后的代价是确定的，追上的收益是概率性的。这决定了"不跟随到最后"在数学上往往是对的。

三条推论的推导关系：

flowchart LR
    R1[规则一: 定缺<br/>缺门公开] --> C1[推论一: 信息压缩<br/>读牌成本低]
    R2[规则二: 血战到底<br/>胡牌不终局] --> C2[推论二: 时间价值<br/>剩几巡是隐含变量]
    R2 --> C3[推论三: 止损优先<br/>点炮独赔+查叫保底]
    C1 --> S[决定 4.2 信息层怎么读]
    C2 --> S2[决定 4.4 何时切换路线]
    C3 --> S3[决定 4.5 防守与保底策略]

4.1 战略层：起手评估与路线选择

拿到起手牌、定缺之前，先给牌打分。不需要精确，三个数就够：

向听数：还差几张牌能听牌。数一下你手里有几个成型搭子/刻子/对子，13 张牌需要 4 副 + 1 将，差几副就是几向听。新手只要会区分"两向听以内（好牌）“和"三向听以上（差牌）"。
对子数：4 对以上 → 七对/大对子路线候选；0~1 对 → 别惦记对子路线。
同花色集中度：9 张以上同花色 → 清一色路线候选。

定缺选择是第一个战略决策，原则按优先级排：

缺张数最少的那门——缺门每张都是必打的废牌，张数越少浪费的巡数越少；
张数相近时，缺结构最差的那门（孤张多、没搭子的）；
还在纠结时，缺端张多的那门（1、9 多），因为端张成搭能力弱。

举例：起手万子 2 张（三万、八万，无关联）、筒子 5 张（两个搭子）、条子 6 张（一个刻子一个边搭）。毫无疑问题缺万——但如果万子是 2 张而筒子是 3 张但全是散牌，就该缺筒子：定缺看的是"废牌数量”，不是"张数”。

定缺公布后立即做第二步战略判断：看三家的缺门，决定做大还是快跑。

三家中有两家缺你这门 → 你要做的花色没人抢，牌墙里全剩给你，做大的绿灯；
三家都不缺你这门 → 四个人抢一门牌，你的关键张会被飞速消耗，果断转快跑。

至此，三条路线已经清晰：

路线	触发条件	目标	核心动作
快跑	牌型一般、向听小、花色被抢	最速听牌、先胡锁定收益	牌效优先，不留废搭
做大	起手 9 张+同花色/4 对+，且无竞争	清一色/大对子/七对	忍受慢听牌，屯关键张
防守	有人已听牌且自己手牌差	不点炮、保查叫底线	只打熟张，听牌优先于胡牌

把起手到定路线的全过程画成一张图：

flowchart TD
    A[拿到13张起手牌] --> B[三个数打分:<br/>向听数 / 对子数 / 同花色集中度]
    B --> C{定缺: 缺哪门?}
    C -->|第一优先| C1[缺张数最少的门]
    C -->|张数相近| C2[缺结构最差的门<br/>孤张多没搭子]
    C -->|还纠结| C3[缺端张多的门<br/>1和9成搭弱]
    C1 & C2 & C3 --> D[公布定缺<br/>观察三家缺门]
    D --> E{有人抢我要做的花色?}
    E -->|两家以上缺我这门<br/>绿灯| F{起手支持做大?<br/>9张+同花色 或 4对+}
    F -->|是| G[做大路线<br/>清一色/大对子/七对]
    F -->|否| H[快跑路线<br/>最速听牌]
    E -->|三家都抢我这门| H
    E -->|牌型差 三向听以上| I[保守推进<br/>随时准备转防守]
    style G fill:#ffe6cc
    style H fill:#d4edda
    style I fill:#f8d7da

路线不是选定就不变——每一巡都可以用新信息重估，4.4 会给出切换的量化标准。

4.2 信息层：记牌与读牌

信息层回答"我知道什么"。它分两半：记牌是对已发生事实的压缩存储，读牌是从事实反推未知信息。

4.2.1 记牌：分层记忆法

让新手背下三家打过的每张牌不现实。按重要性只记三类：

第一层：记"张数"不记"顺序"。 每门花色每张牌只有 4 张。你不需要记住"上家第 3 巡打了七万"，只需在脑子里维护计数：“七万已见 3 张”。重点盯的是你自己将牌和搭子两端的关键牌——你手里 6、8 万等卡 7 万，“7 万见了几张"直接决定这个搭子的死活：见 3 张以上，搭子基本死了，趁早拆。

第二层：记"缺门"和"花色倾向”。 定缺后，对手打出的非缺门花色才是有效信息。下家缺条，从第 2 巡起一直打筒子、摸到万子全留——一句话记住"下家只留万"即可，不用记他打的每一张。

第三层：记"序盘的反常中张"。 序盘（前 4~5 巡）正常人先打孤张边张（1、9）。有人序盘就打 4、5、6 中张，说明这门要么极好（搭子齐了中张多余）要么整门不要，结合缺门大概率能分辨。

口诀：数自己的关键张，记别人的花色倾向，盯序盘的反常中张。

三层记忆的工作量递减、收益递增，像一座金字塔——新手从塔底练起：

flowchart BT
    L1[第三层: 序盘反常中张<br/>一两个反常信号即可<br/>精力占比 ~10%] --> L2[第二层: 缺门与花色倾向<br/>每家一句话: 他只留X<br/>精力占比 ~30%]
    L2 --> L3[第一层: 关键张计数<br/>自己搭子两端的牌各见几张<br/>精力占比 ~60%]
    L3 --> R[收益: 搭子死活判断<br/>直接决定拆不拆]
    L2 --> R2[收益: 知道谁在收哪门<br/>直接决定防什么]
    L1 --> R3[收益: 序盘读出牌型方向]

4.2.2 读牌：他要什么、不要什么、打什么危险

读牌的本质是用别人的"打出"反推他的"留下"——人留下什么牌，才会打出什么牌。按牌局阶段读不同的东西：

序盘读"结构"：缺门 + 反常中张 + 第一碰，拼出每家的大致牌型方向。

中盘读"进度"：看连续动作。上家碰了"二筒"后摸打筒子以外的牌，说明他筒子上还有货；碰完后打的那张牌的邻张往往是他不需要的（碰二筒后打五万，他大概率没有 3-4 万、4-6 万的搭子）；碰了二筒后打的还是筒子，几乎可断定他在做筒子清一色或已听牌。

尾盘读"节奏"：一个人连续摸牌就打（摸打），说明手牌已成型，打出的就是刚摸的；反过来想了很久才打出一张，说明这张是从手里"拆"出来的，他在这张牌附近有搭子变动，其邻张不再安全。

由此得到防点炮 checklist，中后盘（牌墙剩 1/3 以内）每打一张前过一遍：

这张牌见过几张？ 见 2~3 张的熟张相对安全；一张没见的生张风险最高。
有没有人明显在收这门？ 对家在做万子，你手里的生张五万就是高危，宁可拆搭子打熟张。
他是不是单钓/卡张？ 碰了三副、手牌只剩一两张的人，听的牌范围很窄，往往就在他碰的那几副的邻张上——那一片中张全是雷区。

完整例子：对家定缺条子，碰了"三筒"，摸打两巡后思考良久切出"八万"。推断：他在做筒子（碰三筒+留筒），八万是万子里的多余搭子；你手里五、六、七万从此相对安全（他不要万子），但任何生张筒子都是高危，尤其一、二、四筒（三筒邻张）。

读牌的推理链条固定是"观察 → 反推 → 行动"三段，常见信号对照如下：

flowchart LR
    subgraph 观察[他打出/做了什么]
        O1[缺门公布后<br/>一直打筒留万]
        O2[碰二筒后<br/>又打出筒子]
        O3[碰二筒后<br/>打出五万]
        O4[连续摸打]
        O5[长考后拆出八万]
    end
    subgraph 反推[他留下/在想什么]
        I1[在做万子清一色]
        I2[筒子听牌或做筒]
        I3[万子3-4/4-6搭子不存在<br/>→ 万字邻张变安全]
        I4[手牌已成型<br/>打的就是刚摸的]
        I5[八万附近有搭子变动<br/>→ 邻张不安全]
    end
    subgraph 行动[我该怎么办]
        A1[生张万子列为高危]
        A2[生张筒子绝不打]
        A3[手里4万6万可放心打]
        A4[按他已听牌对待<br/>进入防守]
        A5[七万九万扣住观察]
    end
    O1 --> I1 --> A1
    O2 --> I2 --> A2
    O3 --> I3 --> A3
    O4 --> I4 --> A4
    O5 --> I5 --> A5

4.3 战术层：牌效——这一巡到底打哪张

战术层是执行：在路线已定、信息已有的前提下，每张出牌都按同一套优先级评估。

出牌优先级（无安全压力时）：缺门牌（必打）→ 孤立端张（无邻张的 1、9）→ 孤立中张 → 多余搭子中进张最少的那张 → 拆搭子。核心原则是"每一巡都最大化有效进张总数"：假设搭子 A（4-5 万）有 8 张潜在进张、搭子 B（1-2 筒）只有 3 张潜在进张，要拆就先拆 B——哪怕 B 看起来更"连得顺"。注意"潜在进张"还要减去已见张数，见 3 张的两面搭子不如没见过的卡张。

碰/杠决策是新手最容易犯错的地方，默认答案是"不碰"，除非满足以下至少一条：

碰了立刻听牌，或碰的是你的将牌方向（对子路线）；
你在做清一色/大对子，碰能加速成型；
这张牌不碰就被下家吃碰走、你再也等不到。

因为碰有隐性成本：暴露信息（全桌知道你在收这门）、破坏门清弹性（碰完之后手牌变窄，改路线更难）、改变摸牌顺序（可能把本该你摸的关键张让给下家）。杠同理：明杠多摸一张且血战里"杠上花"有额外收益，但同样暴露信息，尾盘还可能给别人开"杠上炮"。起手做大时积极碰杠，快跑路线时能不碰就不碰。

听口选择遵循两个数字：

听口宽度：两面听（8 张潜在）> 卡张/边张（4 张）> 对倒/单钓（2~4 张）。能选宽不选窄；
剩余张数：减去已见的。听见过 2 张的两面（剩 4~6 张），通常不如听没见过的卡张（剩 4 张但还有别人扣牌的空间）。尾盘再加一条修正：听熟张——别人敢打的牌，你才能吃到点炮；听生张只能指望自摸。

把出牌优先级和碰杠决策各画成一张图，实战时按图索骥即可：

flowchart TD
    A[这巡要出牌] --> B{手里有缺门牌?}
    B -->|有| C[打缺门牌]
    B -->|没有| D{有孤立端张?<br/>无邻张的1/9}
    D -->|有| E[打孤立端张]
    D -->|没有| F{有孤立中张?}
    F -->|有| G[打孤立中张]
    F -->|没有| H{搭子进张数比较}
    H -->|拆进张最少的搭子| I[打出该搭子中<br/>价值更低的一张]
    C & E & G & I --> J[打完前最后过一遍<br/>4.2.2 防点炮checklist]

flowchart TD
    P[别人打出一张牌<br/>我可以碰/杠] --> Q{碰了立刻听牌<br/>或是对子路线?}
    Q -->|是| R[碰]
    Q -->|否| S{我在做大<br/>且碰能加速成型?}
    S -->|是| R
    S -->|否| T{不碰就永远<br/>等不到这张?}
    T -->|是| R
    T -->|否| U[不碰, 默认答案]
    U -.成本.-> V1[暴露信息: 全桌知道你收这门]
    U -.成本.-> V2[破坏门清弹性: 手牌变窄]
    U -.成本.-> V3[改变摸牌顺序: 可能放走关键张]
    style U fill:#d4edda
    style R fill:#fff3cd

4.4 概率层：期望值决策——做大、快跑、防守的切换点

这是整个框架的"调度器"，回答"什么时候换路线"。先把 4.3 的直觉量化成一个可心算的模型。

基本概率感觉：任一时刻，你某方向的"期望进展" ≈ 剩余进张数 × 剩余可摸次数。你手里 4-5 万等 3/6 万，若都少见，剩余进张约 6-8 张；牌墙剩 40 张、四家轮流摸，你大约还能摸 8-10 次，摸中概率相当可观。但如果 3/6 万已见 3 张，进张只剩 1~2 张，期望直接砍到四分之一以下——搭子的价值不看牌面，看剩余进张数。

切换到"做大"的条件（需同时满足）：

起手结构支持：9 张以上同花色，或 4 对以上；
进张供给充足：三家缺门不与你抢这门（4.1 的绿灯）；
时间充足：牌墙过半之前。做牌是"用听牌速度换番数"，起手离目标越近、剩余巡数越多，换得越划算；
血战规则加成：一家胡牌不结束牌局，早胡者只是先锁定小收益，晚胡的大牌仍能兑现——大牌的"被截胡损失"比推倒胡小得多，所以四川麻将天然鼓励做牌。

切换到"快跑/止损"的条件（满足任一即执行）：

进张枯竭：关键牌期望进张 < 2，每一巡等待都是负期望——马上换听、拆死搭子；
有人已听牌且你生张密集：此时你的期望收益为负（点炮赔分 + 被查叫），最优解不是"我也赶紧听"，而是只打熟张把点炮概率压到最低，保住查叫底线。这就是"不跟随到最后"——追不上就不再投入，及时止损；
牌墙见底（剩 15 张以内）还没听牌：做牌的时间价值归零，唯一目标是听牌防查叫——往剩余张数最多的熟张方向听，只听一张也比"做了一半的大牌"值钱。

一个简化的期望算账例子（假设平胡 1 番 = 2 分，清一色 4 番 = 16 分）：你听牌了，可以选听口 A——平胡两面听，剩余进张 6 张；或改听口 B——清一色单钓，剩余进张 2 张。若剩余可摸次数约 6 次、点炮胡与自摸混合，A 的期望收益约是正 6~8 分；B 做成的概率约一半不到，做成了 16 分、做不成还要承担被查叫赔 2 分——期望约 6 分，且方差巨大。结论：番数翻倍抵不过进张减半，除非时间足够早或你已经落后必须搏。 新手默认选宽听口，永远是长期正期望。

把"什么时候切换路线"画成一张象限图——横轴是你的剩余进张，纵轴是牌局剩余时间，每巡定位一次自己落在哪个象限：

flowchart TB
    UP[纵轴 ↑ 剩余时间多] --- TOP
    subgraph TOP[ ]
        direction LR
        LEFT2[进张少] ~~~ A[换听调整<br/>时间够但方向死了<br/>例: 卡七万已见三张]
        A ~~~ B[做大<br/>时间够且进张足<br/>例: 起手清一色九张]
        B ~~~ RIGHT2[进张多]
    end
    TOP --- BOT
    subgraph BOT[ ]
        direction LR
        LEFT[进张少] ~~~ C[防守保底<br/>先听牌防查叫<br/>例: 剩十二张没听牌]
        C ~~~ D[快跑<br/>进张还在抢时间<br/>例: 两面听六张剩半局]
        D ~~~ RIGHT[进张多]
    end
    BOT --- DOWN[纵轴 ↓ 剩余时间少]
    style A fill:#fff3cd
    style B fill:#ffe6cc
    style C fill:#f8d7da
    style D fill:#d4edda

两条边界记死：进张 < 2 立刻换方向（左半区行动），剩 15 张只保听牌（下半区行动）。右下象限是血战到底最常见的好局面——进张还在但时间不多，别犹豫，最快胡法锁收益。

4.5 血战到底的三条特有推论

规则特殊，策略就有别处用不上的推论：

先胡是"锁仓"，不是"胜利"。你第一个平胡跑了，只是锁定 2 分；剩下三人继续打，大牌仍在你走后兑现。所以领先时快跑锁收益，落后时反而要做大搏翻盘——这和推倒胡"先胡为王"的直觉相反。
查叫把尾盘变成了保底竞赛。没胡的人要给听牌者赔分，所以尾盘的及格线是"听牌"而不是"胡牌"。最后 15 张，一切决策让位于"听上"。
点炮一人付，防守成本低。别人自摸三家分摊、你点炮你独赔——你打熟张"放生"别人自摸，损失远小于你点炮。所以防守期打熟张不仅是避险，还是把损失转移给全桌分摊的理性选择。

三种结算方式的赔付流向对比，一看就懂为什么"防守打熟张"是理性选择：

flowchart LR
    subgraph 点炮[你点炮: 你独赔]
        Y1[你 -8分] --> H1[胡牌者 +8分]
        O1[另两家 0分]
    end
    subgraph 自摸[对手自摸: 三家分摊]
        Y2[你 -3分] --> H2[胡牌者 +9分]
        O2[另两家各 -3分] --> H2
    end
    subgraph 查叫[流局查叫: 没听赔听牌]
        Y3[你没听 -2分] --> H3[听牌者 +2分]
    end
    style Y1 fill:#f8d7da
    style Y2 fill:#fff3cd
    style Y3 fill:#d4edda

同样是对手胡牌，你点炮亏 8 分、放生他自摸只亏 3 分——防守期每打一张熟张，赚的就是这个差价。

4.6 新手常见错误清单

对照检查，改掉一条涨一截胜率：

只记自己牌，不看池子——搭子死活取决于关键张已见几张，不看池子等于闭眼打牌；
见碰就碰——暴露信息、锁死手牌结构，快跑路线尤其要忍住；
死抱死搭子——7 万已见 3 张还抱着 6、8 万不拆，每巡都在付租金；
做大不看缺门——三家都抢你这门还硬做清一色，供给断了；
尾盘还想着翻盘——剩 15 张没听牌，唯一 KPI 是听牌防查叫；
不跟随到最后反着用——该止损时硬追生张点炮，该搏的时候（落后、时间早）却提前保守。

4.7 一页纸决策框架

把整章压缩成一张每巡都走的决策图：

flowchart TD
    A[每一巡] --> B{信息更新:<br/>关键张已见数/<br/>三家缺门/谁听牌了}
    B --> C{阶段判断}
    C -->|序盘: 定缺+定路线| D{起手支持做大?<br/>9张+同花色/4对+<br/>且三家不抢这门}
    D -->|是| E[做大路线:<br/>积极碰杠, 屯关键张]
    D -->|否| F[快跑路线:<br/>牌效优先, 能不碰不碰]
    C -->|中盘| G{有人已听牌<br/>且我生张密集?}
    G -->|是| H[防守: 只打熟张<br/>放生自摸, 不点炮]
    G -->|否| I{我的关键进张<br/>剩余>=4?}
    I -->|是| J[继续推进<br/>选进张最多的打]
    I -->|否| K[拆死搭子<br/>换听熟张方向]
    C -->|尾盘: 剩15张内| L{已听牌?}
    L -->|否| M[唯一目标: 听牌防查叫<br/>听剩张最多的熟张]
    L -->|是| N[宽听口优先<br/>不为一番改窄]

四个层级的关系：战略层定方向，信息层供弹药，战术层管执行，概率层负责喊停。 新手先把战术层的"进张最大化"练成肌肉记忆，再逐步叠加记牌和读牌，最后学会用期望值喊停——这条学习路径本身也是按依赖关系排的。

五、贝密的技术亮点

最后回到工程，挑几个我认为值得讲的点。

5.1 用 byte 编码整副牌：一副麻将只要几十个字节

贝密把每张麻将牌编码成一个 byte：万/筒/条各占 0~107（每门 36 个编号 = 9 个面值 × 4 张），牌面值 = (card % 36) / 4，花色 = card / 36；风牌用负数。这样 108 张牌的牌墙就是一个 byte[108]，序列化后不到 80 字节。

举例：编号 12 这张牌，12 / 36 = 0（万子），(12 % 36) / 4 = 3（第 4 个面值）——就是"四万"。一个除法一个取模就解出了花色和面值，不用查表、不用对象，广播出牌消息时网络上跑的就是 "12,13" 这样的字符串。

5.2 胡牌判断：不用 3N+2 递归，用"分堆 + 贪心摘顺子"

经典麻将胡牌算法是 3N+2 递归枚举。贝密的 GameUtils.processMJCard 走了一条不同的路：

把 14 张手牌按 key = 面值 + 9 × 花色 放进字典计数，先查定缺——缺门花色还在手里，直接不能胡（四川规则前置拦截）；
按计数把牌分成三堆：others（单张）、pairs（对子）、kezi（刻子）；
对单张堆排序后贪心摘顺子：同花色且 key 连续的 k/k+1/k+2 三张直接移除；
终止条件：单张摘空且恰好剩 1 对将（或 7 对——七对牌型天然被"pairs 堆 = 14 张"覆盖）；
对子多于 1 对时，把多余对子拆开当顺子候选再摘；全无刻子时枚举刻子拆开试。

源码 main() 里作者还放了性能测试：500 万次胡牌判断直接计时。要说明的是，这是个简化实现——作者自己在注释里承认某些"三连对"式的特殊牌型没完整处理。对在线棋牌的实际负载来说，这种"足够快、覆盖主流牌型"的取舍是合理的。

5.3 斗地主牌型识别：频次直方图一把梭

ActionTaskUtils.identification(byte[]) 的做法很干净：先统计同点数张数的分布（几个单张、几个对子、几个三张、几个炸弹），再用 switch(种类数, 最大点数) 一把识别全部牌型——单张、对子、三带一/二、顺子、连对、飞机带翅、四带二、炸弹、王炸。比较两手牌大小的 allow() 则只有三条规则：王炸最大、炸弹管一切非炸弹、同牌型比最大点数。AI 托管出牌也复用这套识别，找"能压住上家的最小牌"。

5.4 自研极简状态机统一驱动两种游戏

斗地主和麻将的流程差异巨大（抢地主 vs 定缺、出牌规则完全不同），但贝密用一个抽象统一了：BeiMiStateMachine + 按事件名查 transition 表 + Action 链。新增一种游戏 = 写一组 Action + 一份状态配置，调度、计时、广播的基础设施全部复用。

5.5 把缓存过期回调当游戏计时器用

这是我觉得最"巧"的设计。棋牌游戏里到处是倒计时：出牌 8 秒、杠碰胡决策 5 秒、抢地主超时自动放弃、房间超时补机器人。贝密没用 Quartz、没开线程池，而是用一个 sharpExpiry 的 cache2k 缓存当计时器：key 是 roomid，value 是任务对象，到期自动触发过期监听器执行任务。玩家主动操作了？remove(roomid) 就把倒计时取消了；要重置？put 一个新任务进去。零额外线程，语义严丝合缝。

5.6 实时状态与持久化彻底解耦

牌局进行中的所有状态（房间、Board、玩家手牌、撮合队列）全在 Hazelcast 分布式内存里，MySQL 只在结算时被异步写入——通过 Disruptor 的 RingBuffer 把变更事件丢给消费者，JPA 和 Elasticsearch 双写（ES 用于运营后台的战绩检索）。注释里还有一条重要的工程纪律：“只有一个地方对 GameRoom 二次写入，避免分布式锁”——用设计约束换掉了锁的开销。另外，房卡模式建房时的局数等规则赋值用了 Drools 规则引擎，规则写在 .drl 文件里，运营改规则不用改代码。

六、总结与反思

回顾这个项目，对新手最有价值的三个认知是：

联网游戏 = 服务器权威 + 按人过滤的状态分发。理解了"客户端只是显示器和遥控器"，就看懂了所有联网游戏的骨架。
棋牌游戏的复杂度不在算法，在工程。胡牌判断几百行就写完了，真正难的是断线重连、超时托管、并发房间这些"无聊"的部分——它们决定了玩家半夜打牌掉线时骂不骂人。
做游戏的人必须会玩游戏。第四章的四川麻将策略——分层记牌、由"打出"反推"留下"、用剩余进张 × 剩余巡数做期望决策——不只是给玩家的攻略，也是当初我们校验 AI 托管和出牌提示是否合理的标尺。

当然也有粗糙之处，如实记录：README 宣称的德州扑克在 0.8.0 里只有枚举占位并未实现；胡牌算法是简化版；源码里散落的 System.out.println 和作者自注的 bug 注释（比如多人同时可碰时先碰者胜出的竞态问题）都还在。但作为一个学习联网游戏开发的开源样本，它把一个房卡棋牌系统该有的零件——长连接、房间状态机、计时器、托管、异步落盘——都真实地摆在了那里，这比完美更有价值。

《去赶海吧》：用 Cocos Creator 写一款「大鱼吃小鱼」io 微信小游戏

Wed, 26 Feb 2020 14:00:00 +0800

《去赶海吧》：用 Cocos Creator 写一款「大鱼吃小鱼」io 微信小游戏

最近把自己做的一款微信小游戏整理开源了，写篇文章介绍一下玩法和实现上的一些技术点，希望能给同样在做休闲小游戏的朋友一些参考。

开源地址：https://gitee.com/soulnew/fishPick
技术栈：Cocos Creator 2.3.4 + TypeScript
平台：微信小游戏

游戏叫《去赶海吧》，核心玩法一句话概括：摇杆控制赶海人在海里吃海鲜攒贝壳，分数即体型，大鱼吃小鱼，活到最后吃鸡。

一、玩法介绍

1.1 核心循环

玩家通过全屏虚拟摇杆控制角色游动，摄像机始终跟随主角。地图上持续刷新各种海洋生物，吃到就得分（贝壳），分数直接决定体型和战斗力：

两个玩家相遇，分高者吃掉分低者——这是 io 类游戏的经典规则；
被吃的玩家死亡后会爆出金币（一半的分数拆成最多 10 条金币鱼散布在周围），形成"击杀后抢遗产"的爽点；
分数变成负数会直接死亡，所以海里的"毒蛇"（-2 分）和"海胆"（-1 分）是要躲着走的。

graph LR
    A[摇杆控制游动] --> B[吃海鲜攒贝壳]
    B --> C{遇到其他玩家?}
    C -->|我分高| D[吃掉对方]
    C -->|我分低| E[触发逃跑 AI / 被吃]
    D --> F[对方爆金币]
    F --> B
    B --> G[实时排行榜 Top5]

1.2 鱼的种类与概率设计

海里的鱼不只是"分"，还混入了道具和陷阱，让取舍更有策略性：

类型	效果	概率（实现值）
加速道具	速度 ×1.5，持续 10 秒	5%
护盾道具	免疫被吃 / 免疫负分鱼，10 秒	5%
鱼、虾、蟹	+1 分	约 35%
水母、海星	+2 分	20%
乌龟	+3 分	10%
海豚	+4 分	5%
毒蛇	-2 分	10%
海胆	-1 分	10%

负分鱼 10 秒后会自动消失，道具的剩余时间通过节点透明度渐变来提示，玩家一眼就能看懂状态。

1.3 四种游戏模式

主菜单提供四个入口，共用同一套核心机制：

无尽模式：死了可以用激励视频复活，AI 每 5 秒重生补齐，刷分为主；
挑战模式：“吃鸡"玩法——剩余玩家数低于阈值后进入 10 秒倒计时，活到最后获胜；
贪吃蛇模式：吃到的鱼变成尾巴跟随身后，撞到别人的尾巴即死；
人挤人模式：群体 Steering Behaviors 的实验玩法，20 个跟随者 + 1 个领队挤作一团。

挑战模式和贪吃蛇模式开局前有一个伪联机匹配面板：“搜索附近玩家…“的省略号动画，12 个头像从 288 张头像图集中不重复随机抽取、按 0~6 秒随机延迟逐个亮起——营造真人匹配的感觉，实际对手全是 AI。这是小团队没有联机服务器时的一个低成本体验方案。

1.4 AI 设计

AI 不是无头苍蝇，每个 AI 出生时会随机分到三种性格之一：

进攻型：主动出击追杀人；
吃鱼型：闷头吃海鲜发育；
闲逛型：随机游走为主。

配合两个细节参数避免行为抖动：被追时有 2 秒"逃跑冷却”（不会在追/逃之间反复横跳），追击最长持续 7 秒（避免死追不放）。AI 找鱼也不搜全图，而是在自己屏幕范围内找鱼最多的格子再过去吃——这个格子划分和碰撞检测用的是同一套空间网格，下面会讲。

二、技术亮点

整个项目是单场景架构（主场景约 400 个节点），28 个 TypeScript 脚本，代码量不大，但性能优化和 AI 上的几个点值得展开说说。

2.1 空间哈希网格：把碰撞检测从 O(n) 降为局部查询

地图上同时存在几百条鱼，如果每帧让每条鱼和所有玩家做碰撞检测，微信小游戏的低端机上肯定扛不住。做法是把地图划分为 20×20 的网格：

graph TD
    A[鱼出生/移动] --> B[按坐标计算所在格子<br/>key = x_y]
    B --> C[挂到对应桶 BlockManager]
    D[碰撞检测] --> E[只查玩家 AABB 覆盖的格子<br/>getCoveredBlock]
    E --> F[与桶内鱼做精确检测]
    C -.鱼移动跨格.-> G[updatePosofFish 迁移桶]

碰撞检测时只查询玩家包围盒覆盖的几个格子里的鱼，而不是全图扫描；
鱼移动跨格时从一个桶迁移到另一个桶；
这套网格还顺手解决了另外两个需求：视野裁剪（视野外格子里的鱼直接隐藏）和上面提到的 AI 找鱼最密集区域。

再配合降频采样——每 4 帧才做一次全量碰撞检测——CPU 占用就控制得很好了。

2.2 对象池：向 GC 抖动说不

鱼、金币、飘分数字这些高频创建销毁的节点全部走对象池：Map<string, Node[]> 按预制名分桶，全局上限 500。小游戏平台上 GC 卡顿是卡顿的主要来源之一，对象池是性价比最高的优化。

2.3 Steering Behaviors：教科书式的群体行为实现

“人挤人"模式的背后是把 Reynolds 那套经典的 Steering Behaviors 完整实现了一遍（Gamer.ts，约 400 行）：

graph TD
    subgraph Steering Behaviors
        A[Seek 追踪] --> H[AccumulateForce<br/>力累加 + 截断]
        B[Flee 逃跑] --> H
        C[Arrive 减速到达] --> H
        D[Wander 随机游走] --> H
        E[Alignment / Cohesion / Separation<br/>群体三规则] --> H
        F[Pursuit 带预测提前量的追击] --> H
        H --> I[EnforceNonPenetrationConstraint<br/>防穿透约束]
        I --> J[最终速度/朝向]
    end

其中 Wander 用的是"jitter + 圆半径 + 投影距离"的经典做法，Pursuit 会根据目标速度算提前量。所有行为输出的力先累加、再按 max_force 截断，最后加一个防穿透的分离约束——这套结构在后面的项目里基本可以原样搬走。

2.4 屏外敌人指示器：io 游戏的标配 UX

强敌在屏幕外时，玩家需要感知威胁方向。实现方式是给每个屏外 AI 分配一个钉在屏幕边缘的箭头 + 分数标签：

用 atan2 计算敌人相对主角的方向角；
按屏幕对角线角度判断箭头该落在上下左右哪条边上；
求射线与屏幕边界的交点作为箭头位置；
8 种随机颜色区分不同敌人。

代码不长，但体验提升非常明显——被高分玩家接近时能提前看到箭头逼近，紧张感就出来了。

2.5 运行时程序化动画

美术资源只有每张皮肤 2 帧的游动图，动画是运行时用 cc.AnimationClip.createWithSpriteFrames 动态创建的 2 帧循环。换皮肤只需要换图集里的起始帧索引（100/102/104…），不用为每套皮肤手工做 Animation 资源。6 套皮肤 = 12 帧图 + 一段代码，维护成本几乎为零。

2.6 事件总线与模块解耦

全局只有一个 50 行的事件总线（on/off/fire）加一个聚合单例，音乐、广告、面板切换、碰撞结果全部走事件通信。单场景多面板的结构下，这种轻量解耦比引入框架更实用。

2.7 微信小游戏生态全套集成

分包加载：字体、头像、音频、图集拆成 4 个分包，loading 场景按包显示进度；
广告变现：Banner + 激励视频复活；
社交：wx.showShareMenu 分享、好友排行榜（开放数据域 + wx.postMessage 通信）、wx.login 登录；
轻量后端：服务器只负责登录、存分数、拉排行三个接口，玩法完全单机，部署成本极低。

三、整体架构一览

graph TD
    subgraph 场景层
        L[loading.fire<br/>分包加载 + 剧情动画] --> F[FirstPannel.fire<br/>单场景多面板]
    end
    subgraph 玩法层
        F --> GM[gameManager<br/>刷鱼/模式管理/降频碰撞]
        GM --> P[Player / BasePlayer<br/>得分/体型/道具/死亡爆币]
        GM --> Fish[Fish<br/>概率产出]
        GM --> Snake[贪吃蛇尾巴 lerp 跟随]
    end
    subgraph 数据与系统层
        GM --> BM[BlockManager<br/>20×20 空间网格]
        GM --> CM[CollideManager]
        GM --> PM[PoolManager<br/>对象池上限500]
        GM --> SM[ScoreManager<br/>实时排行]
        GM --> EV[CustomEventListener<br/>事件总线]
    end
    subgraph 平台层
        EV --> WX[分包/广告/分享/好友排行/登录]
        EV --> SRV[轻量后端<br/>login / saveScore / getRank]
    end

四、写在最后

这个项目验证了一个想法：没有联机服务器，用"伪匹配 + 性格化 AI"也能撑起 io 游戏的核心体验。代码里当然也留下了一些遗憾，比如数值全部硬编码没有配置表、BasePlayer.scoreChange() 里有一条永远执行不到的 else-if 分支（score>=10 先命中，后面的大体型缩放被挡住了）——这些都在代码里原样保留着，权当给读者的"找茬彩蛋”。

源码在 https://gitee.com/soulnew/fishPick，欢迎 Star，也欢迎提 Issue 交流。

《游戏开发物理学》学习笔记：从运动学到刚体碰撞的新手实战指南

Thu, 16 Jan 2020 11:00:00 +0800

《游戏开发物理学》学习笔记：从运动学到刚体碰撞的新手实战指南

参考书籍：《Physics for Game Developers》（David M. Bourg，O’Reilly，中译名《游戏开发物理学》）目标读者：想自己做物理效果（而不是只会调引擎参数）的游戏开发者、图形学/仿真方向的新手。阅读建议：这篇文章帮你建立主干知识框架：先数学，再运动学 → 动力学 → 载具模拟 → 实时积分 → 碰撞 → 粒子，最后给出避坑清单和主流引擎对照。公式只保留实战中真正会用的。

一、这本书到底讲什么？

很多新手做游戏的物理效果，路径是这样的：

用 Unity/UE 拖一个 Rigidbody，调调质量、摩擦力，能跑就行；
遇到「球穿过墙了」「车开起来像肥皂盒」「碰撞后能量爆炸越弹越高」就抓瞎；
回头发现：不是引擎不行，是自己不懂底层的物理模型。

Bourg 这本书的价值就在于：它把物理引擎内部在干什么，用程序员能实现的粒度讲了一遍。它不追求物理学的严谨完备，而是追求「在 60 FPS 的游戏循环里，用可承受的计算量，得到看起来正确、玩起来稳定的结果」。

全书知识地图：

mindmap
  root((游戏开发物理学))
    数学基础
      向量与运算
      矩阵与坐标变换
      四元数
    运动学 Kinematics
      位移 速度 加速度
      抛体运动
    动力学 Dynamics
      牛顿定律
      力与力矩
      流体阻力
    载具模拟
      飞机
      舰船
      气垫船
      汽车
    实时模拟
      数值积分
      游戏循环
      时间步长
    碰撞
      碰撞检测
      碰撞反应 冲量
    粒子系统

一句话总纲：游戏物理 = 用力计算加速度，用数值积分把加速度变成速度和位置，用碰撞检测发现问题，用冲量修正速度。整本书就是在把这句话的每个环节讲细。

二、核心数学基础速成

物理引擎 90% 的代码是向量、矩阵和四元数运算。这一关不过，后面全看不懂。

2.1 向量：物理量的通用语言

位置、速度、力、动量，全部是向量。必须熟练的运算：

加减：力的合成（$F = F_1 + F_2$）、相对速度；
点积（结果是一个数）：

$$ \mathbf{a} \cdot \mathbf{b} = |\mathbf{a}||\mathbf{b}|\cos\theta $$

实战用途：求投影（比如速度沿碰撞法线方向的分量）、判断两个方向夹角是锐角还是钝角（点积大于 0 还是小于 0）。碰撞反应里「物体是否在相互靠近」就是靠点积判断的。

叉积（结果是一个垂直向量，仅 3D；2D 中退化为一个标量）：

$$ |\mathbf{a} \times \mathbf{b}| = |\mathbf{a}||\mathbf{b}|\sin\theta $$

实战用途：力矩 $\tau = \mathbf{r} \times \mathbf{F}$（力作用点偏离质心会产生转动）、2D 碰撞冲量里的旋转项。

归一化：$\hat{\mathbf{v}} = \mathbf{v} / |\mathbf{v}|$，只要方向不要大小（碰撞法线必须归一化，忘记这步是经典 bug）。

避坑：2D 里叉积 $\mathbf{r} \times \mathbf{F}$ 是标量 $r_x F_y - r_y F_x$，正负号代表顺时针/逆时针，和引擎的坐标系朝向约定有关，写之前先定好「逆时针为正」并全程统一。

2.2 矩阵与坐标变换

旋转、缩放、坐标系切换都靠矩阵。新手只需要先建立两个直觉：

矩阵乘法 = 变换的复合，顺序不可交换（先旋转再平移 ≠ 先平移再旋转）；
每个刚体都活在两个坐标系里：局部坐标系（物体自己的，转动惯量、几何形状在这里算最方便）和世界坐标系（所有物体一起碰撞、渲染的地方）。物理计算每天的工作就是在这两个系之间来回变换。

2.3 四元数：3D 姿态的正确打开方式

3D 中表示朝向有三种方式：

方式	优点	缺点
欧拉角（roll/pitch/yaw）	直观，3 个数	万向锁（gimbal lock），插值不平滑
旋转矩阵	直接用于向量变换	9 个数冗余，数值误差积累会「变形」
四元数	4 个数紧凑，插值平滑，无万向锁	不直观，乘法规则要背

游戏物理的标准做法：内部存储和积分用四元数，给玩家看的时候转欧拉角。四元数必须经常归一化，否则数值漂移会让物体悄悄缩放变形。

2.4 微积分：只需要两个直觉

导数 = 变化率。速度是位置的导数，加速度是速度的导数。
积分 = 累积。已知加速度，累加得到速度；累加速度得到位置。

游戏里你永远不会真的去解符号积分——而是用数值积分一步步逼近（见第六章）。理解「导数是斜率、积分是累加」就够了。

2.5 单位制与坐标系：开工前先立规矩

避坑（这是新手第一大坑）：开工前必须白纸黑字定下来——

长度单位是米还是像素？重力加速度是 9.81 m/s² 还是 981 px/s²？混用必出灵异现象。

2D 屏幕坐标 y 轴向下，而物理教科书 y 轴向上。直接照抄公式会把「下落」写成「飞天」。

角度用弧度，所有三角函数接口都是弧度，传角度进去结果毫无明显错误提示。

三、运动学（Kinematics）：只描述运动，不问原因

运动学关心「物体怎么动」，不关心「为什么动」（那是动力学的事）。

3.1 三个基本量

$$ \text{速度 } \mathbf{v} = \frac{d\mathbf{x}}{dt}, \qquad \text{加速度 } \mathbf{a} = \frac{d\mathbf{v}}{dt} $$

匀加速运动（加速度恒定）下的三个实用公式：

$$ v = v_0 + at $$

$$ x = x_0 + v_0 t + \frac{1}{2} a t^2 $$

$$ v^2 = v_0^2 + 2a(x - x_0) $$

3.2 抛体运动：游戏里最值钱的运动学

抛体（炮弹、篮球、跳跃的角色）的核心思想一句话：水平方向和竖直方向互相独立，分开算。

水平：无加速度，匀速 $x = v_0 \cos\theta \cdot t$
竖直：受重力，$y = v_0 \sin\theta \cdot t - \frac{1}{2} g t^2$

由这两个式子可以推出（落回同一高度时）：

$$ \text{射程 } R = \frac{v_0^2 \sin 2\theta}{g}, \qquad \text{最高点 } H = \frac{v_0^2 \sin^2\theta}{2g} $$

两个直接能用在游戏里的结论：

45 度抛射射程最远（不计空气阻力时）；
已知初速度和目标距离，可以反解出抛射角——这就是「抛物线命中目标」的数学基础。

典型问题：炮弹打移动目标的提前量。 设目标当前位置 $\mathbf{p}$、速度 $\mathbf{v}_t$，炮弹速度 $s$，求解命中时间 $t$：

$$ |\mathbf{p} + \mathbf{v}_t t| = s t $$

两边平方得到一个关于 $t$ 的一元二次方程，取最小正根，瞄准点就取 $\mathbf{p} + \mathbf{v}_t t$。AI 炮塔、技能预判全是这个套路。

避坑：二次方程可能无解（目标跑得太快炮弹追不上），代码里必须处理判别式小于 0 的情况，否则 AI 会对着永远打不中的目标开火。

四、作用力与动力学（Dynamics）：运动的原因

4.1 牛顿三定律的程序员版本

惯性定律：不受力的物体保持匀速直线运动——所以你不用写代码让它「继续动」，它不减速只是因为没人让它减速；
核心公式 $\mathbf{F} = m\mathbf{a}$：所有物理引擎的心脏。先把作用在物体上的所有力加起来（合力），除以质量得到加速度，然后交给积分器；
作用力与反作用力：碰撞反应、火箭推力的理论基础。

旋转版本的对应关系（这对应表值得背下来）：

直线运动	旋转运动
质量 $m$	转动惯量 $I$
力 $\mathbf{F}$	力矩 $\tau = \mathbf{r} \times \mathbf{F}$
加速度 $\mathbf{a} = \mathbf{F}/m$	角加速度 $\alpha = \tau / I$
速度 $\mathbf{v}$	角速度 $\omega$

转动惯量的直觉：质量分布离转轴越远越难转（花样滑冰收手加速）。2D 里 $I$ 就是一个标量（如均匀圆盘 $I = \frac{1}{2}mr^2$，细杆绕中心 $I = \frac{1}{12}mL^2$）；3D 里是一个 3×3 张量矩阵，通常直接在局部坐标系下预计算并求逆，避免每帧重复。

4.2 游戏里最常见的几种力

重力：$F = mg$，恒定向下，人人有份；
弹簧力：胡克定律 $F = -kx$（$k$ 是劲度系数），悬挂、软绳、镜头跟随弹性都靠它；
摩擦力：静摩擦（小于阈值时完全抵消切向力）与动摩擦 $F = \mu N$（$\mu$ 摩擦系数，$N$ 法向压力）；
流体阻力（空气/水）：低速近似线性 $F = -k_1 v$，高速用二次项：

$$ F_d = -\frac{1}{2} \rho v^2 C_d A , \hat{\mathbf{v}} $$

$\rho$ 是流体密度，$C_d$ 阻力系数，$A$ 是迎流面积。飞机、舰船、弹道下坠感全靠它。

避坑：二次阻力在速度很大时力也爆炸式增大，直接积分容易数值不稳定（物体来回震荡甚至飞出屏幕）。实战技巧是给阻力加速度设上限，或改用半隐式积分。

五、载具物理：本书的招牌四章

Bourg 用飞机、舰船、气垫船、汽车四个例子，展示同一套框架（合力 → 加速度 → 积分）如何套出完全不同的手感。掌握套路比记住每个参数重要。

5.1 飞机：四力平衡

flowchart LR
    T[推力 Thrust<br/>发动机] -->|向前| P((飞机))
    D[阻力 Drag<br/>空气摩擦与压差] -->|向后| P
    L[升力 Lift<br/>机翼上下压差] -->|向上| P
    W[重力 Weight<br/>mg] -->|向下| P

核心公式是升力和阻力，共享同一个「动压」结构：

$$ L = \frac{1}{2} \rho v^2 S C_L, \qquad D = \frac{1}{2} \rho v^2 S C_D $$

其中 $S$ 是机翼面积，$C_L$ 升力系数。关键知识点：

$C_L$ 随迎角（机翼与气流的夹角）增大而增大，但超过临界迎角后骤减——这就是失速，飞机升力瞬间消失往下掉。模拟飞行手感，失速是必须实现的；
滚转、俯仰、偏航三个通道各自独立输入力矩，组合出飞行姿态；
升力正比于 $v^2$：速度不够就拉不起来，这是「起飞需要跑道」的物理原因。

避坑：完整的空气动力学模型极复杂，游戏里几乎没人真做 CFD。标准做法是查表/分段线性：把 $C_L$ 和 $C_D$ 做成关于迎角的查找表，手感调好就是胜利。

5.2 舰船：浮力与流体阻力的天下

浮力：阿基米德原理，浮力等于排开水的重量。简化模拟常用「浮力采样点」——在船底布若干采样点，每个点按入水深度产生向上的力，自然涌现出船的横摇和纵摇；
稳性：浮心与重心的相对位置决定船会不会翻。重心太高、浮心太低 = 头重脚轻，一晃就翻；
阻力：水的密度约为空气的 800 多倍，所以舰船阻力以粘性阻力为主，低速近似线性即可；
转弯：舵产生侧向水动力，船不是「拐过去」而是「漂着转过去」，模拟时要给船体侧向很大的阻力、纵向较小的阻力，才有「船感」。

5.3 气垫船：低摩擦的特殊手感

气垫船悬在气垫上，与地面的摩擦几乎为零，带来两个标志性的操控特性：

推力方向和运动方向可以长期不一致——船头朝东，船还在往西漂；
转向靠舵/侧推产生力矩，但转弯时船身会侧滑，直到横向水/气阻力把侧向速度消耗掉。

实现上就是在普通刚体模型里把接触摩擦调得极小，再加分方向差异很大的阻力系数（横向阻力大、纵向阻力小）。「阻力系数各向异性」是气垫船和所有水上载具手感的灵魂。

5.4 汽车：一切手感都在轮胎上

汽车的驱动力链路：发动机扭矩 → 变速箱/挡位 → 驱动轮 → 轮胎与地面的摩擦 → 牵引力。

最重要的概念是抓地力有限：轮胎能提供的摩擦力有上限（摩擦圆/摩擦椭圆），加速、刹车、转向消耗的抓地力共享同一个预算。转向打满还猛踩油门，抓地力透支——打滑、漂移就这么来的。

简化模型三件套：

驱动力 $F = \text{engineForce}$，随速度衰减（极速的来源：驱动力 = 阻力时不再加速）；
阻力 = 滚动阻力 + 空气阻力（二次项主导高速）；
转向时按当前速度把车头方向「往速度方向拉」，拉伸强度代表抓地力——强度低就是漂移手感。

避坑：很多新手给汽车直接用「速度 = 车头方向 × 油门」，车像轨道车一样瞬间转向，毫无惯性。正确做法是转向改的是车头朝向，速度方向靠轮胎力逐渐跟上，这个「跟不上」就是车感的来源。

六、实时模拟：数值积分与时间步长

前面所有公式给出的是「这一瞬间的加速度」。游戏是一帧一帧跑的，核心问题是：怎么从加速度一步步推出位置和姿态？

6.1 游戏物理主循环

flowchart TD
    A[读取输入] --> B[计算所有作用力与力矩<br/>重力/推力/阻力/弹簧...]
    B --> C[求合力 F 与合力矩 τ<br/>a = F/m, α = τ/I]
    C --> D[数值积分<br/>更新速度 v、角速度 ω]
    D --> E[再积分<br/>更新位置 x、姿态 q]
    E --> F[碰撞检测]
    F --> G{有碰撞?}
    G -->|是| H[碰撞反应<br/>施加冲量修正速度]
    G -->|否| I[渲染]
    H --> I
    I --> A

6.2 三种积分方法对比

方法	公式（以位置为例）	精度	速度	适用
显式欧拉	$x(t+h) = x(t) + v(t),h$	差，能量发散	最快	不推荐单独用
半隐式欧拉（Symplectic Euler）	先 $v(t+h) = v(t) + a,h$，再 $x(t+h) = x(t) + v(t+h),h$	一阶但能量稳定	快	游戏物理默认选择
RK4	四次采样加权平均	四阶，很准	4 倍开销	需要精确的离线仿真

半隐式欧拉只比显式欧拉改了一个顺序（用新速度更新位置），稳定性却有质的飞跃——这是书里最划算的「一行代码的智慧」。

6.3 时间步长：实时模拟的头号工程问题

固定时间步：物理每 1/60 秒（或 1/120 秒）推进一步，渲染帧率高时插值、低时多补几步。优点：结果可复现（回放、联机同步必须用它）；
可变时间步：直接用上一帧的耗时当 $h$。优点简单；缺点致命——帧率波动直接改变物理行为，同一台机器跑两遍结果都不一样。

避坑（ spiral of death，死亡螺旋）：帧率突然下降 → 单帧物理步数暴增 → 物理计算更慢 → 帧率进一步下降。解法：给每帧物理步数设上限（如最多 5 步），宁可游戏慢动作也不让模拟爆炸。

避坑（隧道效应 tunneling）：步长太大 + 速度太快 → 子弹一帧飞过了整面墙，两帧采样点都在墙外，碰撞检测永远发现不了。解法：小步长、射线扫掠检测（swept collision / CCD），或对高速物体单独细分步长。

七、刚体旋转：从粒子到真正的「物体」

粒子只有位置；刚体多了姿态（orientation），一切都变复杂了。

3D 姿态更新的标准流程（四元数版）：

存姿态四元数 $q$ 和角速度向量 $\omega$；
每步积分：

$$ q(t+h) = q(t) + \frac{h}{2}, \tilde{\omega} , q(t) $$

其中 $\tilde{\omega} = (0, \omega_x, \omega_y, \omega_z)$ 是纯四元数形式的角速度（注意乘法顺序，别写反）； 3. 归一化 $q$（不做的后果：物体慢慢变大/缩小）； 4. 需要转动向量时，用 $q$ 把向量从局部系旋转到世界系。

力矩链路：外力作用点相对质心的偏移 $\mathbf{r}$ 产生力矩 $\tau = \mathbf{r} \times \mathbf{F}$，角加速度 $\alpha = I^{-1}\tau$（3D 中 $I^{-1}$ 要用当前姿态把局部系的逆惯量张量变换到世界系），积分得 $\omega$。这就是为什么打在边缘的一拳会让物体边飞边转。

避坑：3D 转动惯量张量一定要在局部坐标系预计算并求逆；每帧变换到世界系用 $I^{-1}_{world} = R I^{-1}_{local} R^T$。直接在世界系里积分惯量是错误的经典写法。

八、碰撞检测：先粗后精

8.1 两阶段流水线

flowchart LR
    subgraph 粗阶段 Broad Phase
        A1[遍历所有物体对] --> A2[包围球 / AABB 快速排除]
        A2 --> A3[空间划分<br/>网格 / 四叉树 / BVH]
    end
    subgraph 窄阶段 Narrow Phase
        B1[候选物体对] --> B2[精确求交<br/>SAT / 顶点-面 / 边-边]
        B2 --> B3[输出碰撞信息<br/>接触点 / 法线 / 穿透深度]
    end
    A3 --> B1

关键思想：$n$ 个物体两两检测是 $O(n^2)$，先用粗阶段把 99% 不可能相碰的对子排除掉，窄阶段只处理剩下的少数。

8.2 常用包围体

包围体	特点	典型场景
包围球	测试只需比较圆心距与半径和，最快	子弹、粒子、粗略筛选
AABB（轴对齐包围盒）	各轴区间重叠判断，简单快速	静态场景、粗阶段
OBB（有向包围盒）	贴合物体旋转，测试较贵	车辆、细长物体
凸多边形/凸包 + SAT	分离轴定理：存在一条轴使两形体的投影不重叠 ⟺ 不相交	2D 精确检测、3D 凸体

避坑：SAT 的轴候选是「两个形体所有面的法线」（3D 还要加边叉积），漏掉一组轴就会在特定角度漏检。另外 SAT 只适用于凸体，凹体要先拆成多个凸体。

8.3 碰撞检测必须输出的三样东西

窄阶段不是只回答「碰没碰」，而是要给出碰撞反应需要的输入：接触点（冲量作用在哪里）、法线（冲量沿哪个方向）、穿透深度（位置修正多少）。缺了任何一个，后面的碰撞反应都写不出来。

九、碰撞反应：冲量法

碰撞瞬间持续时间极短、力极大，直接模拟力不现实。游戏物理的标准做法是冲量法：把碰撞看成瞬间改变速度的一次「踢」。

9.1 核心推导思路

设两物体碰撞前的相对速度沿法线分量为 $v_r \cdot \mathbf{n}$，碰撞后变为 $-e$ 倍（$e$ 是恢复系数：$e=1$ 完全弹性，$e=0$ 完全非弹性）——这就是牛顿碰撞定律。把「冲量同时改变两物体的线速度和角速度」代入，解出法向冲量大小：

$$ j = \frac{-(1+e), \mathbf{v}_{rel} \cdot \mathbf{n}} {\dfrac{1}{m_1} + \dfrac{1}{m_2} + \dfrac{(\mathbf{r}_1 \times \mathbf{n})^2}{I_1} + \dfrac{(\mathbf{r}_2 \times \mathbf{n})^2}{I_2}} $$

（这是 2D 版本，$\mathbf{r}_1$、$\mathbf{r}_2$ 是接触点相对两质心的偏移；3D 版本把平方项换成矩阵形式 $\mathbf{n} \cdot [(\mathbf{r} \times \mathbf{n}) I^{-1} \times \mathbf{r}]$。）

然后：

线速度：$\mathbf{v}_1 \mathrel{-}= \frac{j}{m_1}\mathbf{n}$，$\mathbf{v}_2 \mathrel{+}= \frac{j}{m_2}\mathbf{n}$
角速度：$\omega_1 \mathrel{-}= \frac{(\mathbf{r}_1 \times j\mathbf{n})}{I_1}$，$\omega_2 \mathrel{+}= \frac{(\mathbf{r}_2 \times j\mathbf{n})}{I_2}$

打偏的一撞让物体旋转起来，就是这两个 $\mathbf{r} \times$ 项在起作用。

9.2 摩擦冲量

法向冲量解决「弹开」，摩擦冲量解决「蹭」。算出切向相对速度后施加切向冲量 $j_t$，并钳制在库仑摩擦锥内：

$$ |j_t| \le \mu , j $$

不做这个钳制，摩擦会反过来给物体加速——又一个「能量爆炸」来源。

9.3 实战避坑清单（碰撞反应篇）

穿透与抖动：数值误差让物体每帧陷进去一点又弹出来。解法：允许一个微小穿透量（slop），只对超出部分做位置修正（Baumgarte 稳定化），修正量再打个 0.2 左右的折扣；
能量爆炸：单次冲量解多接触点会互相打架，恢复系数别用满 1，摩擦记得钳制，必要时加阻尼；
迭代求解：多个接触点/约束时，对速度约束循环迭代 4-10 次（顺序冲量法），直到收敛——Box2D 就是这么做的；
静止接触：物体叠放静止时，冲量趋近于零但不等于零，抖动主要来自这里。slop + 位置修正 + 休眠（速度长期低于阈值就把物体标记为睡眠，跳过模拟）三件套缺一不可；
衝量只改速度：碰完物体还插在里面是正常的，位置交给下一帧的位置修正或积分自然分离，别试图一帧内又改速度又硬掰位置（除非做的是专门的位置投影）。

十、粒子系统：刚体的「降维打击」

粒子 = 没有旋转、没有形状（通常渲染成点或公告板）、数量极大的迷你刚体。

模拟上只做：合力（重力、风、阻力）→ 半隐式欧拉积分 → 简单碰撞（对地面反弹或直接死亡）；
表现上靠生成器（发射速率、初速度锥角、寿命随机分布）和衰减（颜色、大小、透明度随寿命变化）；
典型用途：火花、烟雾、爆炸、尾迹、简单的流体/喷泉近似。

避坑：粒子系统的瓶颈几乎从不在物理，而在渲染和内存。对象池复用粒子、避免每帧 new/delete，CPU 模拟 + GPU 渲染分工明确，是入门就该养成的习惯。

十一、2D 刚体模拟器：把全书串起来的最小实战

书中后半部分的 2D 刚体模拟示例，是最适合新手的毕业项目。最小可用版本只需要这些模块：

flowchart TD
    subgraph 数据结构
        D1[RigidBody2D<br/>位置/角度/线速度/角速度<br/>质量/转动惯量]
        D2[Contact<br/>接触点/法线/穿透深度]
    end
    subgraph 每帧流程
        S1[施加重力等外力] --> S2[半隐式欧拉积分]
        S2 --> S3[粗阶段: AABB 排除]
        S3 --> S4[窄阶段: SAT 求接触]
        S4 --> S5[冲量求解 迭代若干次]
        S5 --> S6[位置修正 slop + Baumgarte]
        S6 --> S7[休眠检测]
    end
    D1 --> S1
    S4 --> D2
    D2 --> S5

动手顺序建议：

先做单刚体自由落体 + 地面反弹（恢复系数可调），验证积分正确；
加旋转：给一个方块偏心施加力，看是否边飞边转；
加碰撞：圆 vs 圆（最简单）→ 凸多边形 SAT；
加摩擦冲量和迭代求解；
加位置修正和休眠，一堆方块能稳稳叠起来——恭喜，你写出了一个迷你 Box2D。

十二、典型问题 FAQ

Q1：物体速度越来越快最后飞出世界（数值发散）？ 检查三件事：是否用了显式欧拉（换半隐式）；步长是否过大（弹簧系统等刚度大的力要求更小的步）；阻力/弹簧是否缺上限或阻尼。

Q2：子弹穿墙？ 隧道效应。高速物体用扫掠检测（上一帧位置到这一帧位置打一条射线/扫掠体），或对其使用更小的子步长（CCD）。

Q3：箱子叠在一起不停抖动、慢慢沉进地里？ 缺 slop 容差和位置修正折扣；恢复系数设成了接近 1（静止接触应该用 0 或极小）；缺少休眠机制。

Q4：联机/回放时物理结果不一致？ 使用了可变时间步或浮点运算顺序不一致。固定时间步 + 固定迭代次数 + 固定遍历顺序是确定性模拟的前提；跨平台完全一致还要锁定浮点模式或用定点数（如《王者荣耀》等帧同步游戏的做法）。

Q5：斜坡上的箱子自己往下滑 / 不会滑？ 检查摩擦实现：切向冲量有没有做库仑钳制 $\mu j$；法线是否归一化；静摩擦与动摩擦有没有分开处理。

Q6：四元数积分后物体悄悄变形/缩放？ 忘记每步归一化四元数。这是四元数模拟里出现率最高的 bug。

Q7：2D 里物体往天上「掉」？ 屏幕 y 轴向下而公式按 y 轴向上写的，重力符号反了。

十三、避坑总清单（速查表）

坑	症状	解法
单位混用（米/像素）	一切数值都「差不多但不对」	开工前定死单位制，重力常数跟着改
y 轴朝向	运动方向全部镜像	定好坐标约定，重力符号随之确定
显式欧拉	能量越来越多，逐渐爆炸	半隐式欧拉起步
可变时间步	帧率一掉物理就变，不可复现	固定时间步 + 步数上限
隧道效应	高速物体穿墙	扫掠检测 / CCD / 子步长
法线没归一化	碰撞反应大小诡异	所有法线使用前 normalize
四元数不归一化	物体缓慢缩放变形	每步积分后归一化
摩擦不钳制	摩擦反而加速物体	库仑摩擦锥约束
穿透硬修正	抖动、弹跳不止	slop + Baumgarte 折扣修正
无休眠	性能浪费 + 静止抖动	速度阈值休眠
死亡螺旋	卡顿后彻底卡死	每帧物理步数设上限

十四、主流游戏框架与物理引擎

上面的原理，主流引擎都已内置实现；学原理的意义在于调得动、查得准、必要时能绕过。

引擎/框架	物理方案	备注
Unity	PhysX（3D）、Box2D（2D）	Rigidbody / Rigidbody2D，FixedUpdate 即固定时间步
Unreal Engine	Chaos（新版）、PhysX（旧版）	Chaos 支持破坏、布料等大型模拟
Godot	自研 Godot Physics，可换 Jolt	开源，2D/3D 分离
Box2D	2D 物理库（C++）	本书思想的工业化实现，愤怒的小鸟、无数 2D 游戏在用
Bullet	3D 物理库	开源老牌，影视与游戏双用
Jolt	3D 物理库	《地平线》系列使用，近年性能口碑极好
PhysX	3D 物理库（NVIDIA）	Unity/UE 底层，支持 GPU 加速
Cocos Creator	内置 2D（Box2D/builtin）、3D 可选 PhysX/cannon.js	国内小游戏主流
LayaAir	集成 Bullet（编译为 wasm）	国内 3D H5 主流
Rapier	Rust 编写，可编译 wasm	Web/独立游戏新势力，确定性模拟支持好
MuJoCo / PyBullet	科研仿真	机器人、强化学习训练场景

选型直觉：2D 游戏默认 Box2D 系；3D 商用项目跟着引擎走（Unity 用 PhysX、UE 用 Chaos）；网页端想要确定性（帧同步）看 Rapier；做机器人/RL 仿真看 MuJoCo。

十五、学习路径建议

第一周：把向量运算（点积、叉积、归一化）练到不用查，手写一个 2D 抛体模拟（重力 + 半隐式欧拉 + 地面反弹）；
第二周：给抛体加空气阻力和风，做「炮弹打移动目标」的提前量解算；
第三周：实现 2D 刚体（加旋转和转动惯量），偏心受力看旋转；
第四周：SAT 碰撞检测 + 冲量法碰撞反应 + 摩擦，让方块能撞、能停、能叠；
之后：挑一个载具（汽车最容易出成就感）做手感调优；有 3D 需求再啃四元数和惯量张量；
贯穿始终：每实现一个特性，先想「这一步在哪个引擎里对应什么参数」，原理和工具互相印证。

结语

《游戏开发物理学》最大的价值不是那些公式，而是一个思维框架：任何炫酷的物理效果，拆到最后都是「合力 → 积分 → 碰撞 → 冲量」这条流水线的变体。飞机和汽车的差别只在于往「合力」里塞了什么力；刚体和粒子的差别只在于有没有旋转那一半。

先把这条流水线在小项目里跑通，再去用引擎——你会发现所有参数突然都认识了。

Cocos Creator 2.x 实战笔记：动画、事件、向量、资源与避坑指南

Sat, 28 Dec 2019 14:00:00 +0800

Cocos Creator 2.x 实战笔记：动画、事件、向量、资源与避坑指南

本文基于 Cocos Creator 2.x（cc.* API）整理，覆盖从动作动画、输入事件、位置向量、场景管理、音效、资源加载到摄像机跟随等高频知识点。虽然 3.x 已全面转向 TypeScript 与新的组件系统，但 2.x 的核心思想——节点树 + 组件 + 生命周期 + Action 系统——仍然是理解引擎设计的最佳入口。

一、高层次思想：Cocos Creator 在组织什么？

Cocos Creator 的核心理念可以概括为一句话：

“节点（Node）负责层级与变换，组件（Component）负责行为与表现。”

graph TD
    A[Scene 场景] --> B[Canvas]
    B --> C[Node 节点]
    C --> D[Transform 变换]
    C --> E[Sprite 渲染]
    C --> F[Script 脚本]
    C --> G[AudioSource 音效]
    C --> H[PhysicsCollider 物理]
    D --> I[position / rotation / scale]
    F --> J[onLoad / start / update]

1.1 节点树 = 变换层级

每个 cc.Node 都有父节点，子节点的变换会继承父节点。理解这一点才能避免“为什么我改了坐标没效果？”这类问题。

World Space（世界坐标系）
   │
   ├── Canvas (Design Resolution: 720x1280)
   │      ├── Player (position: 0, -400)
   │      │      ├── Head (position: 0, 80)    ← 子节点相对父节点
   │      │      └── Gun  (position: 60, 0)
   │      └── Enemy

1.2 组件生命周期

stateDiagram-v2
    [*] --> onLoad: 场景初始化
    onLoad --> onEnable: 节点激活
    onEnable --> start: 第一次 update 前
    start --> update: 每帧调用
    update --> lateUpdate: update 之后
    lateUpdate --> update: 下一帧
    update --> onDisable: 节点禁用
    onDisable --> onEnable: 重新激活
    onDisable --> onDestroy: 销毁节点

避坑指南 #1：onLoad 中适合获取节点引用和初始化数据；start 中适合访问其他组件（此时场景中所有节点的 onLoad 都已执行完毕）。不要把耗时的初始化放在 update 里。

二、动作系统（Action）：让节点“动起来”

Action 是 Cocos Creator 2.x 中非常优雅的动画封装。它基于组合模式：简单动作可以拼接成复杂序列。

2.1 跳跃动画：位移 + 缓动曲线

// 跳跃上升
var jumpUp = cc.moveBy(this.jumpDuration, cc.v2(0, this.jumpHeight))
    .easing(cc.easeCubicActionOut());

// 下落
var jumpDown = cc.moveBy(this.jumpDuration, cc.v2(0, -this.jumpHeight))
    .easing(cc.easeCubicActionIn());

// 不断重复
return cc.repeatForever(cc.sequence(jumpUp, jumpDown));

xychart-beta
    title "跳跃高度随时间变化"
    x-axis [0, 0.25, 0.5, 0.75, 1.0]
    y-axis "高度" 0 --> 100
    line [0, 80, 100, 80, 0]

避坑指南 #2：moveBy 是相对移动，moveTo 是绝对移动。跳跃一般用 moveBy，因为落地位置取决于起跳点。如果误用 moveTo，角色会跳到固定世界坐标。

2.2 缩放与回调：序列动作

cc.sequence(
    cc.scaleTo(dua, 0.8, 0.8),
    cc.scaleTo(dua, 1, 1),
    cc.callFunc(() => {
        paopaoNode.destroy();
    })
);

2.3 旋转

var rotationTo = cc.rotateTo(1, 0, 180);
this.paiNode.runAction(rotationTo);

2.4 左右晃动（以锚点为原点）

var seq = cc.sequence(
    cc.rotateTo(0.2, 15),
    cc.rotateTo(0.4, -15),
    cc.rotateTo(0.4, 15),
    cc.rotateTo(0.4, -15),
    cc.rotateTo(0.4, 15),
    cc.rotateTo(0.2, 0),
    cc.delayTime(2)
);
this.node.runAction(cc.repeatForever(seq));

graph LR
    A[初始 0°] --> B[右偏 +15°]
    B --> C[左偏 -15°]
    C --> D[右偏 +15°]
    D --> E[左偏 -15°]
    E --> F[回正 0°]
    F --> G[停顿 2s]
    G --> A

避坑指南 #3：旋转方向遵循引擎约定，正数为顺时针，负数为逆时针。rotateTo 会尽量选择最短路径到达目标角度；如果需要连续多圈旋转，请用 rotateBy。

2.5 点击时按钮放大

// 在按钮的触摸开始/结束时分别放大与恢复
buttonNode.on(cc.Node.EventType.TOUCH_START, () => {
    buttonNode.runAction(cc.scaleTo(0.1, 1.1, 1.1));
});
buttonNode.on(cc.Node.EventType.TOUCH_END, () => {
    buttonNode.runAction(cc.scaleTo(0.1, 1.0, 1.0));
});

三、输入事件：键盘、触摸与鼠标

3.1 键盘事件

cc.systemEvent.on(cc.SystemEvent.EventType.KEY_DOWN, this.onKeyDown, this);

实现监听函数：

onKeyDown(event) {
    switch(event.keyCode) {
        case cc.macro.KEY.a:
            this.accLeft = true;
            break;
        case cc.macro.KEY.d:
            this.accRight = true;
            break;
    }
}

避坑指南 #4：第三个参数 this 不要漏！否则回调里的 this 会指向 cc.systemEvent，导致 this.accLeft 为 undefined。建议在 onDestroy 中移除监听，避免场景切换后事件泄漏。

3.2 触摸 / 鼠标事件

this.node.on('touchstart', this.touchStart, this);
this.node.on('touchend',   this.touchEnd,   this);

枚举与事件名对照：

枚举	字符串事件名	说明
`cc.Node.EventType.TOUCH_START`	`touchstart`	手指按下
`cc.Node.EventType.TOUCH_MOVE`	`touchmove`	手指移动
`cc.Node.EventType.TOUCH_END`	`touchend`	手指抬起（在节点内）
`cc.Node.EventType.TOUCH_CANCEL`	`touchcancel`	系统中断（如来电）
`cc.Node.EventType.MOUSE_DOWN`	`mousedown`	鼠标按下
`cc.Node.EventType.MOUSE_ENTER`	`mouseenter`	鼠标进入节点
`cc.Node.EventType.MOUSE_MOVE`	`mousemove`	鼠标移动
`cc.Node.EventType.MOUSE_LEAVE`	`mouseleave`	鼠标离开节点
`cc.Node.EventType.MOUSE_UP`	`mouseup`	鼠标抬起
`cc.Node.EventType.MOUSE_WHEEL`	`mousewheel`	滚轮滚动

四、位置向量 Vec2：2D 游戏的数学基础

4.1 生成与设置位置

var pos = cc.v2(randX, randY);
newStar.setPosition(pos);

4.2 距离、长度与运算

// 计算当前节点与玩家之间的距离
var dist = this.node.position.sub(playerPos).mag();

// 返回向量长度
var len = dir.mag();

// 自加（修改原向量）
v.addSelf(cc.v2(5, 5));

// 返回新向量（不修改原向量）
var vnew = v.add(cc.v2(5, 5));

// 缩放
var v = cc.v2(10, 10);
v.mul(5);   // 返回 Vec2 {x: 50, y: 50}
console.log(v); // 仍打印 Vec2 {x: 10, y: 10}

// 判断相等
var res = v.equals(cc.v2(10, 10)); // true

避坑指南 #5：addSelf、mulSelf、subSelf 等方法会修改原向量；不带 Self 的版本会返回新向量。在 update 中计算方向时，若不想意外修改 this.node.position，请使用非 Self 版本。

4.3 线性插值（Lerp）

var v  = cc.v2(10, 10);
var v1 = cc.v2(5, 5);
var v3 = cc.v2(0, 0); // 存储结果
v.lerp(v1, 0.5, v3);  // 在 v 与 v1 之间取 50%
console.log(v3);      // Vec2 {x: 7.5, y: 7.5}

4.4 坐标转换

方法	原点	用途
`convertToWorldSpaceAR(point)`	节点锚点	局部坐标 → 世界坐标
`convertToNodeSpaceAR(point)`	节点锚点	世界坐标 → 局部坐标
`convertToWorldSpace(point)`	节点左下角	不建议，除非 UI 特殊需求
`convertToNodeSpace(point)`	节点左下角	不建议

graph LR
    subgraph 世界坐标系
        direction TB
        A[World Origin] --> B[Player]
    end
    subgraph 局部坐标系
        direction TB
        C[Anchor Point] --> D[(100, 100)]
    end
    B -->|convertToWorldSpaceAR| D
    D -->|convertToNodeSpaceAR| B

避坑指南 #6：Cocos 编辑器默认以锚点（Anchor）为原点，因此优先使用带 AR 的方法。左下角为原点的方法主要用于兼容旧项目或特殊 UI 对齐。

五、场景与生命周期

5.1 重新加载场景

cc.director.loadScene('game');

避坑指南 #7：loadScene 会销毁当前场景所有节点。如果需要在切换前保存数据（如分数、关卡进度），请先写入本地存储，再调用加载。

5.2 暂停与恢复

// 暂停游戏逻辑，但渲染和 UI 响应仍在
cc.director.pause();

// 恢复
cc.director.resume();

常用于弹出结算面板或暂停菜单。

六、透明度、音效与组件

6.1 透明度渐变（实现缓慢消失）

update(dt) {
    this.node.opacity -= 100 * dt;
    if (this.node.opacity <= 0) {
        this.node.destroy();
    }
}

6.2 音效

properties: {
    scoreAudio: {
        default: null,
        type: cc.AudioClip
    }
}

// 播放音效（false 表示不循环）
cc.audioEngine.playEffect(this.scoreAudio, false);

避坑指南 #8：背景音乐请用 playMusic，音效用 playEffect。微信小游戏对同时播放的音频数量有限制，过量的 playEffect 可能导致后续音效被丢弃。

6.3 getComponent：获取组件

newStar.getComponent('Star').game = this;

避坑指南 #9：getComponent 是 Node 的方法，JS 中的方法和属性都挂在组件上。不要把脚本逻辑直接写在场景或节点上，而要写在组件脚本里。

七、屏幕、包围盒与资源加载

7.1 获取视图大小

var winSize = cc.director.getWinSize();

7.2 包围盒

var first_xMax = bgList[0].getBoundingBox().xMax;

getBoundingBox() 返回父节坐标系下的轴向对齐包围盒（AABB），包含 xMin、xMax、yMin、yMax、width、height 等属性。

7.3 加载图片

cc.loader.load(
    { url: "res/raw-assets/resource/texture/gold.png", type: 'png' },
    (err, texture) => {
        var fra   = this.spr2.getComponent(cc.Sprite);
        var sframe = new cc.SpriteFrame(
            texture,
            new cc.rect(20, 20, 100, 120)
        );
        fra.spriteFrame = sframe;
    }
);

cc.rect(20, 20, 100, 120) 表示从图片的 (20, 20) 开始，取宽 100、高 120 的矩形区域，即图片中 (20, 20) 到 (120, 140) 的内容。

避坑指南 #10：微信小游戏对图片尺寸有限制，长宽都不能超过 2048。超出此限制会导致加载失败或显示异常，导入资源前请先检查尺寸。

7.4 加载 Prefab

cc.loader.loadRes(`prefab/game08/${randIdx}`, cc.Prefab, (err, res) => {
    this.drawing = cc.instantiate(res);
    this.drawing.group = "drawing";
});

八、本地存储

// 写入
cc.sys.localStorage.setItem("finishLevel", this.curLevel);

// 读取（注意转换类型，localStorage 只存字符串）
var level = parseInt(cc.sys.localStorage.getItem("finishLevel") || 0);

避坑指南 #11：localStorage 只能存储字符串。存储对象时请先 JSON.stringify，读取后再 JSON.parse。微信小游戏有本地存储上限，重要数据建议结合云端存档。

九、摄像机跟随

9.1 主角简单跟随

// this.node 为 Camera 节点
update(dt) {
    var targetPos = this.player.position;
    this.node.position = targetPos;
}

9.2 主角自然跟随（平滑插值）

update(dt) {
    var targetPos = this.player.position;
    var currentPos = this.node.position;
    currentPos.lerp(targetPos, 0.1, currentPos);
    this.node.position = currentPos;
}

graph LR
    A[Camera 当前位置] -->|lerp 0.1| B[Player 当前位置]
    B --> C[下一帧继续插值]
    C --> D[最终重合]

十、调试、绘制与更新策略

10.1 cc.log

cc.log("只在发布时勾选调试模式才起效");

10.2 Graphics 画图

var g = this.node.getComponent(cc.Graphics);
g.moveTo(0, 0);
g.lineTo(100, 100);
g.stroke();

10.3 打包更新

发布时勾选 MD5 Cache，避免浏览器/微信缓存旧资源。
热更新需配合 cc.assetManager.loadBundle 或官方热更新方案。

cc.assetManager.loadBundle('level2', (err, bundle) => {
    bundle.loadDir('prefabs', (err, assets) => {
        // ...
    });
});

十一、物理关节：旋转关节 RevoluteJoint

// cc.RevoluteJoint 可约束两个刚体围绕一个点旋转
var joint = nodeA.addComponent(cc.RevoluteJoint);
joint.connectedBody = nodeB.getComponent(cc.RigidBody);
joint.anchor = cc.v2(0, 0);
joint.connectedAnchor = cc.v2(0, 50);

常用于门铰链、钟摆、车轮等效果。

十二、帧率与屏幕适配

12.1 锁定帧率

let fps = (cc.sys.os == cc.sys.OS_IOS) ? 40 : 40;
cc.game.setFrameRate(fps);

if (cc.sys.platform == cc.sys.WECHAT_GAME) {
    wx.setPreferredFramesPerSecond(fps);
}

12.2 分辨率适配

let frameSize = cc.view.getFrameSize();
let scrall = frameSize.width / frameSize.height;

cc.view.setResolutionPolicy(cc.ResolutionPolicy.EXACT_FIT);
cc.view.setOrientation(cc.macro.ORIENTATION_LANDSCAPE);

cc.Canvas.instance.fitWidth  = false;
cc.Canvas.instance.fitHeight = false;

let isFitWidth = scrall < 1.77;
cc.Canvas.instance.fitWidth  = isFitWidth;
cc.Canvas.instance.fitHeight = !isFitWidth;

12.3 常用设计分辨率

分辨率	比例	适用场景
720 × 1280	9:16	竖屏手游最常见
640 × 960	2:3	早期 iPhone 经典
1080 × 1920	9:16	高清竖屏
1280 × 720	16:9	横屏手游

graph TD
    A[设计分辨率 720x1280] --> B[实际屏幕分辨率]
    B --> C{选择适配策略}
    C -->|FIT_WIDTH| D[宽度铺满，高度可能裁剪/留黑]
    C -->|FIT_HEIGHT| E[高度铺满，宽度可能裁剪/留黑]
    C -->|EXACT_FIT| F[拉伸铺满，可能变形]
    C -->|SHOW_ALL| G[等比缩放，全部可见，可能留黑]
    C -->|NO_BORDER| H[等比缩放，铺满屏幕，可能裁剪]

十三、网络同步：Colyseus

对于多人实时游戏，Colyseus 是 Cocos Creator 常用的 Node.js 状态同步框架。

同步方式	核心思想	适用场景
状态同步	服务端权威，客户端插值预测	MMO、卡牌、休闲对战
帧同步	只同步输入，客户端各自演算	RTS、MOBA、格斗

避坑指南 #12：帧同步对浮点数一致性和随机种子要求极高。Cocos 2.x 默认使用 JavaScript 浮点运算，跨平台（iOS/Android/微信）可能出现不一致，需统一数学库与随机算法。

十四、避坑清单速查表

编号	避坑点
1	初始化放 `onLoad`，跨组件访问放 `start`
2	`moveBy` 相对移动，`moveTo` 绝对移动，别混用
3	旋转方向：正顺负逆；多圈旋转用 `rotateBy`
4	注册事件必须传 `this`，切场景时记得 `off`
5	向量运算区分 `Self` 与非 `Self` 版本
6	坐标转换优先用带 `AR` 的方法
7	`loadScene` 前保存必要数据
8	音乐用 `playMusic`，音效用 `playEffect`
9	逻辑写在组件脚本里，不要直接挂在节点上
10	微信小游戏图片尺寸不能超过 2048×2048
11	`localStorage` 只存字符串，对象需 JSON 序列化
12	帧同步注意浮点一致性与随机种子

十五、总结

Cocos Creator 2.x 的开发可以归纳为以下流程：

graph LR
    A[搭建场景节点树] --> B[挂载脚本组件]
    B --> C[处理输入事件]
    C --> D[在 update 中更新逻辑]
    D --> E[使用 Action 或逐帧修改属性实现动画]
    E --> F[加载资源 / 切换场景 / 保存数据]

掌握 节点-组件模型、生命周期、Action 组合、Vec2 运算、坐标转换、屏幕适配 这六大核心后，2D 游戏开发中大部分问题都能迎刃而解。希望这份笔记能成为你项目中的速查手册。