2D 游戏 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 交流。

《去赶海吧》：用 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 交流。

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 游戏开发中大部分问题都能迎刃而解。希望这份笔记能成为你项目中的速查手册。