跳到正文

客户端:Cocos 工程、页面与资源加载

联机放置游戏第 08 节 / 共 11 节 ·2026-11-16·~6 min

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 只声明表现层用到的那一小块 cc API(两百多行,签名从 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 行:

类型行数是什么
sheet5438 方向图集:一张图 + .rig.json 写格子、帧率、脚底
icon191图标
object115场景物件、家园卡片
anim26逐帧动作 + rig(陪伴小窗和战斗卡用)
symbol17符号
backdrop16背景
fx10特效
scene1一个烘焙目录: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 准备数据时要隔开发。