# 百人赛页面与分包

更新日期：2026-09-16。

## 目录

| 目录 | 打包方式 | 内容 |
| --- | --- | --- |
| assets/cloud_rise_home | 本地主包资源，compressionType=default | 活动弹窗、共用控制脚本、弹窗使用的图片 |
| assets/cloud_rise_matching | 统一微信分包内的独立 Bundle | 匹配页面、匹配头像及提示 |
| assets/cloud_rise_stage1 | 同上 | 5 关路线、名单、胜利和失败/超时结算 |
| assets/cloud_rise_stage2 | 同上 | 7 关路线、名单、胜利和失败/超时结算 |
| assets/cloud_rise_stage3 | 同上 | 9 关路线、名单、胜利和失败/超时结算 |
| assets/cloud_rise_art | 非分包原始资源目录 | 保留的原始美术；运行时不主动加载此目录 |

每个页面的预制体均在对应目录的 prefab/CloudRise.prefab。home 是随主包发布的普通 Asset Bundle，不在微信 subpackages 清单中。微信发布时只有一个 cloud_rise 分包，内部有 matching 和三个 stage 共四个 Bundle。

项目扩展 packages/cloud-rise-package 在 build-finished 阶段，把 Creator 输出的四个分包目录移至 subpackages/cloud_rise/ 下，更新 game.json 和 settings.js，并注入统一下载器。四个目录的 meta 仍保留 subpackage，这是构建中间格式，不是最终微信分包结构；字节跳动及浏览器沿用原加载方式。home、公共字体归属及 Bundle UUID 不变。首次添加扩展后需要重启 Creator 再完整构建，控制台应出现“已合并为一个微信分包，保留四个 Bundle”。不要只复制或手改旧 game.json。

Creator 2.4 图形界面构建的 platform 为 mini-game，扩展优先用 actualPlatform 判断 wechatgame。模板 game.json 保留四个中间目录，只有合并成功后的产物清单才改为一个 cloud_rise；防止扩展未执行时引用不存在的统一目录。

## 加载和衔接

- 登录状态确认后，对可报名玩家、个人挑战仍有效或有待结算奖励/结果的玩家，后台准备 home 和统一活动分包，不阻塞首页。报名窗口已结束但个人挑战未结束时仍可下载。
- 统一分包只下载一次；可开始匹配时优先完整加载 matching 预制体及依赖，暂不初始化三个 stage。打开总览后提前实例化隐藏匹配页，点击开始复用。预准备失败不报名，点击开始可重试；尚未准备好时按钮显示“正在准备…”。
- 手动点击开始/开始下一阶段，同时准备匹配页与目标 stage；匹配页就绪后立即显示，不等待 stage。准备期间显示本人头像及 1/100，右上角关闭按钮用于取消并返回活动总览，不提交报名。下载可以继续并缓存，供再次开始复用。
- 目标 stage 就绪后进入报名确认，暂时隐藏取消按钮；确认成功后播放对手入场动画并达到 100/100，再进入进度页。资源失败可重试且不消耗报名机会；取消、关闭后的旧请求不能触发报名或覆盖新请求的页面状态。
- 查看已参与的进度、逐关结算或恢复未看完的结算，仅加载当前 stage。
- stage1/2 胜利结算仍需动画结束后手动点击，返回主包活动弹窗，再手动开始下一阶段。stage3 胜利及失败结算仍按现有流程关闭。
- 切换 stage 会销毁旧 stage 的页面节点，停止其云朵/头像展示；已经加载的 Bundle/Prefab 缓存用于再次打开。
- stage 不引用匹配页头像模板或其他 stage 资源，各自保存需要的模板和美术。百人赛共同依赖的弹窗图片由 home 优先持有；公共字体由启动场景包持有。

## 编辑器维护

home 根节点挂载 CloudRisePanel。独立页面根节点挂载 CloudRisePage，使用 nodeKeys/nodes、componentKeys/components、frameKeys/frames 成对保存引用；冒号后数字表示控制器数组下标，例如 tracks:1 是第二阶段路线。移动节点不会影响引用，删除被绑定节点时需要同步调整绑定。

stage 页包含 Progress、Participants、Templates、AvatarTemplates、Victory。头像模板和名单行模板默认隐藏，不能当作无用节点删除。每个 stage 只保留一组 StageSteps，普通云朵分别为 4、6、8 个；通关目标仍为 5、7、9。最后一关落在 Progress/PrizeCloud（宝箱奖励云），不额外生成 Step。普通云及连接小云点从右下出发向上排列，终点前的一朵普通云位于右上。头像的跳跃目标、静止站位与浮动跟随统一通过 cloudForScore 选择落点；最后一关失败时，其他晋级玩家跳向奖励云，自己仍从原云淘汰。

原先被替代的 Result 结算面板、总览隐藏 Panel/Description/Rules、进度隐藏 Pool 和未使用的 Solo 文案已移除。超时提示由 stage 内的 ExpiredMessage 展示，失败继续使用 FailureMessage。

所有金额的 Digits 保留固定五个 Sprite 节点，组件 digits 是 0～9 的十张字形资源表。总览、匹配和进度统一引用 common/font.plist 的 scoin 字体，Source Art 开启、Glyph Material 为空；9 对应资源名 scoin_09。胜利奖励保持原有胜利数字素材。金额仍由接口动态更新，最大五位。

公共字体只保留 common/font 原资源，不复制图集。LoadScene 的 Load.commonFont 引用完整图集，使其归属内置 start-scene（优先级 9），并随启动场景加载；home 优先级为 6，匹配和 stage 为 3。common 是普通目录，单独修改它的 priority 不生效；不要删除启动场景的 commonFont 绑定，或把业务包优先级提高到启动场景之上。内置 main 在本项目配置为微信分包，因此不能把 main 与微信主包混为一谈。

宝箱星光共用 home/images/xinguang.png 与 xingxing.png。匹配、进度及胜利结算的 Chest 下挂 ChestSparkles，包含外围 Stars 和两个金币高光 CoinGlintTop/CoinGlintFront；随宝箱父节点移动、缩放和显隐。首页宝箱在 PanelTop 合成图内，因此 ChestSparkles 挂在 PanelTop 下，按原图星形位置对齐。直接在预制体调整位置即可，无需运行时创建节点。

## 验证

专项测试：tools/test-cloud-rise-bundles.cjs、test-cloud-rise-prefab.cjs、test-cloud-rise-availability.cjs、test-cloud-rise-animations.cjs、test-cloud-rise.cjs。覆盖分包清单、引用完整性、独立 stage 资源、按需加载、失败重试、关闭中断、原有匹配/胜负动画及奖励流程。

本次使用实际 Cocos 2.4.15 引擎和源码预制体做隔离预览，验证主包弹窗、匹配、三个 stage、胜利返回总览和失败页面。未重新构建微信发布包或进行真机验证。完整类型检查被现有 Utils.ts:1913 的语法错误阻断；本次变更文件的 TypeScript 转译通过。

目录和分包清单变化后需要重新构建微信包，不能继续使用旧构建产物。当前统一分包不是旧的单预制体 cloud_rise Bundle；其内部仍保留四套独立的 Bundle 配置。