Cocos Creator 3.8.8 工程在 client/,表现层在 client/assets/scripts/visual/。网页版、Windows、Android、iOS 同一份工程;现在线上跑的是网页版。
1. 没装 Creator 也能检查
开发机上多半没装 Creator,打包在专门的 Windows 打包机上做。所以工程里 Creator 平时会生成的东西,都由脚本生成、能校验:
client/tools/gen-meta.mjs:- 补
.meta文件。缺的 uuid 由「固定前缀 + 相对路径」的 sha1 算出来,任何机器上生成的都一样;已有的 meta 一个不动。图片按 SpriteFrame 导入、不裁透明边。 - 生成最小的主场景:Canvas + 相机 + 一个挂着
IdleBoot的节点。 - 生成四个平台的构建配置(文件名带 md5、bundle 的 import JSON 合成一个)。
--check查:缺 meta、孤儿 meta、uuid 重复或非法、场景引用对不上、构建配置过期。
- 补
- 类型检查:
client/tools/cc-stub.d.ts只声明表现层用到的那一小块ccAPI(两百多行,签名从 3.8 的cc.d.ts简化而来),拿它当桩,tsc严格模式查整个表现层。 - 共享代码
assets/scripts/shared/是从packages/拷过来的生成物,不手改。
2. 界面布局
┌─────────────────────────────────────────────────────┐
│ 顶栏 32px │
├────┬──────────────────────────────┬─────────────────┤
│dock│ │ 右侧状态栏 │
│56px│ 内容区(大地图 / 各页面) │ 概览 · 背包 · 角色│
│ │ │ │
│ │ ├─────────────────┤
│ │ │ 快捷面板 │
└────┴──────────────────────────────┴─────────────────┘
- 设计分辨率永远等于窗口的 CSS 像素尺寸:不缩放整张画布,系统缩放下字也清楚。完整界面最小 640×400。
- dock:每个技能一个按钮(战斗进战斗页,炼金进炼金页,其余进技能页),然后是 地图 · 家园 · 工坊 · 市场 · 时装 · 日志 · 控制台 · 设置。页面第一次打开时才建,之后一直留着。
- 右侧状态栏(宽度是窗口的 26%,夹在 260–360 之间):「概览」每个村民一块(在做什么、进度、黄色的「等材料」、× 撤回),加上小队血量;「背包」;「角色」每个战斗者的属性和六个装备格。下半截是快捷面板。
- 技能页:这个技能的动作列表,每个动作可以加人减人。
- 战斗页:卡牌式对阵,见 战斗 。
- 其他:物品详情弹窗、更新公告(只收上个版本以来的新条目)、欢迎回来小结、设置页(字体包和图片包的状态与重试、安装包下载、「关于」里的客户端和服务器版本与构建时间、第三方致谢)。
visual 只调 GameStore,不直接调接口;GameStore 在 client-logic 里,负责登录、同步、预测和推送(见 系统架构
)。
3. 摸鱼小窗与画中画
窗口小于 640×400,或者点「小窗」,进入小窗模式:
- 整页变成大地图,快捷面板变成下面一个可以收起的抽屉;
- 左上角一条「看谁」:镜头在主角和任意一个村民、战斗者之间切换;
- 在小窗模式里点去别的页面,打开的是快捷面板里对应的那一屏,不退出小窗。
快捷面板首页是四块:战斗 / 村民 / 背包 / 日志,每块点进去有下一层。它还能弹出浏览器的画中画窗口(Document Picture-in-Picture,340×300):用普通 DOM 画同一套四块面板,自己的 rAF 每秒刷新 6 次,游戏标签页在后台时也照样更新。挂在屏幕角落上班摸鱼正好。
原来右下角那个陪伴小窗(当前动作的小动画)2026-11-09 隐藏了,代码还在。
4. 资源键与资源类型
代码与配表只写资源键。config/tables/assets.csv 一行一个资源:
key,bundle,path,kind,w,h,res,format,tint,desc
w×h 是逻辑尺寸,res 是实际发多少百分比,format 是 png、png256(调色板 PNG)或 jpgNN。现在 919 行:
| 类型 | 行数 | 是什么 |
|---|---|---|
| sheet | 543 | 8 方向图集:一张图 + .rig.json 写格子、帧率、脚底 |
| icon | 191 | 图标 |
| object | 115 | 场景物件、家园卡片 |
| anim | 26 | 逐帧动作 + rig(陪伴小窗和战斗卡用) |
| symbol | 17 | 符号 |
| backdrop | 16 | 背景 |
| fx | 10 | 特效 |
| scene | 1 | 一个烘焙目录:scene.json + 地面块 + 贴片(就是整张大地图) |
bundle 按「是什么东西」分:fonts ui item character object backdrop fx map,另留一个 cosmetics。
AssetLoader 按键找 bundle 和路径,bundle 第一次用到时才加载;先查 getInfoWithPath,图还没做就返回空、什么都不画,不在控制台报错。有一个历史坑:Creator 构建有时照样裁透明边(有一版裁了、下一版没裁,根因没查清),所以加载时 untrim() 把 rect 还原成整张原尺寸,冒烟测试查「图是整张画布」。
5. 加载不卡主线程
2026-11-13 那一批改动的目标是「进地图、换时装不掉帧」:
- 图片包:打包后钩子把每个 bundle 的图片拼成几个
.bin包('IHPK'魔数 + 头长度 + JSON 文件表 + 原样拼接的图片,不压缩,每包目标 4 MB)。默认按 uuid 首位分成 1–16 包;另按用途分组:时装每个部件一个包,大地图按 2048 像素见方的区域分,每个建筑地点一个包。进了包的原图从产物里删掉,CDN 上的文件数大约减半。 - 客户端接管图片下载(
visual/assets/packs.ts):引擎要一张图时,找到它所在的包,整包下回来,用Blob.slice切出这张图交给引擎;引擎再用createImageBitmap解码,解码在后台线程。包下不来就报错让引擎重试,不退回原地址。 - 后台预读:进游戏后按 ui → item → character → fx → object → backdrop 的顺序在后台预读,时装图层(约 80 MB)和地图(约 60 MB)不预读,用到时再按需下。
- 时装在 Worker 里拼(
visual/assets/outfitCompose.ts):开 2–3 个 Worker(CPU 核数减一,最多 3 个),每个部件的彩色图集和深度图集逐像素合成,最后描一圈 1 像素的轮廓。一张动作图集(3840×2880、4 层)在 Worker 里约 2.5 秒;以前放在主线程上要两秒多,单帧最多卡 700 毫秒。层图用转移的方式交给 Worker,不复制。没有 Worker 或 OffscreenCanvas 的环境退回主线程、每层之间让一帧。 - 地图由近到远补:看得见的地面块和贴片才建节点、才请求图片,离镜头近的先请求,图片包也就按这个顺序下。
6. 加载画面与字体
- 加载画面在网页模板里,FF14 那种:预先模糊好的关键美术(清晨薄雾的桥畔小镇)、游戏图标、标题字、进度条。引擎脚本下载时进度按时间爬到 60%,之后由游戏报:正在连接服务器 → 正在同步存档 → 正在加载场景。没有东西在等了,或者最多 8 秒,就收起来。
- 字体 IdleHD Sans:Noto Sans SC(OFL)的子集,常规与半粗两种,共 2.3 MB,由
tools/art/font/build-font.mjs按游戏里出现的字 + 3755 个常用字裁出来。2026-11-10 从 MiSans 换过来:MiSans 的许可证不允许裁子集,整套 16 MB。字体要等document.fonts.load()真的确认了才算好——Cocos 的加载器超时 3 秒后不管成没成都报成功。
7. 本机验证网页版
开发机上没有 Creator,验证网页版的办法是:从打包机拿一份构建产物,放进一个 releases/<版本>/ 目录并写好 CURRENT,本机用 IDLE_DEV_AUTH=1 IDLE_WEB_ROOT=<目录> 起服务器,再用无头浏览器开发登录、截图、读 window.__idlehd.store。scripts/smoke-web.mjs 是全套冒烟。
几个坑:无头 Chrome 十几秒后会把页面标成 hidden,Cocos 随之暂停,要开焦点模拟;点界面要先在场景里按文字找到 cc.Label,把它的世界包围盒换算成屏幕坐标再发鼠标事件;登录后会先弹更新公告挡住点击;服务器按用户限流,批量 GM 准备数据时要隔开发。