MatchMaster/docs/cloudRise-prefab.md

# 百人赛页面与分包

更新日期：2026-09-18。

## 目录

| 目录 | 打包方式 | 内容 |
| --- | --- | --- |
| 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 | 统一微信分包内的公共图片 Bundle，优先级 5 | 匹配页及三个 stage 共用的图片 |

每个页面的预制体均在对应目录的 prefab/CloudRise.prefab。home 是随主包发布的普通 Asset Bundle，不在微信 subpackages 清单中。微信发布时只有一个 cloud_rise 分包，内部有 art 公共图片、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；防止扩展未执行时引用不存在的统一目录。

## 公共图片归属

cloud_rise_art 复用原目录与图片 UUID，集中保留原有共用图片，并新增十张 rank_0～rank_9 名次数字图片；匹配与 stage 只保留自身专用图片。continue.png 保留原引用，由优先级更高的 home 持有，不增加首页对活动分包的依赖。原目录中未使用的 12 项素材及 meta 归档至 source-art/cloud_rise（assets 之外，不参与构建）。其他玩法的同图副本及 common/font 不动。

CloudRiseService 按 home → art → 目标页面加载 Bundle；公共 Bundle 的并发请求合并，失败后可重试。加载 art 配置不会主动加载全部结算图片，仍由页面依赖按需加载。不要直接绕过 Service 加载页面预制体。

## 加载和衔接

匹配开始前不再调用 userLevel 上传主线进度。prepare_match（以及兼容的 start/start_stage）随请求携带 levelAmount = GM_INFO.level，表示前端已通过关卡数；后端以该值 + 1 确定阶段起点和对手匹配中心。请求入队后保留该次进度快照，重试不重新取值。需先发布支持 levelAmount 的 cloudRise/index 后端，再使用新客户端；普通主线存档逻辑不受影响。

- 登录状态确认后，对可报名玩家、个人挑战仍有效或有待结算奖励/结果的玩家，后台准备 home 和统一活动分包，不阻塞首页。报名窗口已结束但个人挑战未结束时仍可下载。
- 统一分包只下载一次；可开始匹配时优先完整加载 matching 预制体及依赖，暂不初始化三个 stage。打开总览后提前实例化隐藏匹配页，点击开始复用。预准备失败不报名，点击开始可重试；按钮固定使用“开始”美术，不再叠加 CaptionCover/Caption。
- 手动点击开始/开始下一阶段，同时准备匹配页与目标 stage；匹配页就绪后立即显示，不等待 stage。准备期间显示本人头像及 1/100，匹配期间不展示取消按钮和右上角关闭按钮。下载可以继续并缓存，供再次开始复用。
- 目标 stage 就绪后通过 prepare_match 准备对手，再播放头像入场；匹配页已移除手动取消入口；底层取消草稿机制保留。取消返回总览，以 cancel_match 清理草稿，保留本期报名机会、前一阶段进度和奖励。取消写入本地同步队列，断网或重启后继续发送；旧请求不能触发报名或覆盖新匹配。
- 达到 100/100 时调用 confirm_match 正式参加并显示“点击以继续”，点击后进入进度页。首次参加的个人挑战计时从确认时开始，后续阶段沿用原截止时间。需先发布支持这三个操作的 cloudRise/index 后端，再更新客户端；旧后端会拒绝准备请求，不会误扣资格。
- 查看已参与的进度、逐关结算或恢复未看完的结算，仅加载当前 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。胜利奖励保持原有胜利数字素材。金额仍由接口动态更新，最大五位。

ProgressValue、SurvivorsValue 使用 CloudRiseCounter 和七个可复用 Glyph，引用 home/images/stat_0～stat_9、stat_slash。三个 stage 按 stage1 的数字样式统一排版，并开启 Use Prefab Layout：接口数值更新时只替换字形和显隐，保留各 Glyph 的位置及 Sprite Size Mode，避免运行时覆盖编辑器调整。关闭该选项才使用 Glyph Height 自动居中排版。剩余人数的名单按钮已停用。

匹配中部的 StreakHint 与进度宝箱 RewardHint 共用 streak_hint.png（用户提供的 weni.png）。点击宝箱切换提示气泡，不会误触继续。ClickToContinue 位于 home 的 Design 下，供匹配、各 stage 进度及胜负结算共用；使用 cloud_rise_art/images/continue.png（用户提供的“点击.png”）Sprite，不再使用 Label，显示时机与点击继续逻辑保持不变。continue_outline 材质沿文字透明轮廓绘制黑色、50% 不透明度、2px 描边（图片像素单位）；原文字保持 224×43，CUSTOM 节点扩大到 228×47 预留四周空间。该图片关闭动态合图和自动裁剪，确保材质 UV 与原图一致；不修改 PNG。

胜利标题与宝箱同时出现，之后依次显示金币、头像和共享奖励说明。本人单独展示，其他获胜者按实际存活名单全部生成头像，人数多时换行缩放。淘汰掉落距离减半，落点生成淡紫色云烟并扩散消失；结算后保留晋级头像与云朵浮动。进度头像密度根据云宽和屏幕边界调整，本人始终在最前。

公共字体只保留 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-counters.cjs、test-cloud-rise-package.cjs、test-cloud-rise.cjs。覆盖分包清单、引用完整性、独立 stage 资源、按需加载、失败重试、关闭中断、点击继续、图片人数、完整获胜名单及胜负动画和奖励流程。

2026-09-17 公共图片整理：133 项专项测试通过，Creator 2.4.15 微信完整构建成功。百人赛分包文件合计由 12,557,878 字节降至 4,447,077 字节，减少 64.59%（构建目录文件大小，非微信压缩包大小）。构建产物中 30 张公共图片均存在且无重复 native 文件；home 无 art 依赖、体积不变，其他玩法分包体积不变。四个页面预制体仅替换图片 UUID，节点结构与布局未改动。此次未进行真机流程验证。

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

## 2026-09-18 界面补充

- 三个阶段的 Victory/People/Shared/Others 使用名次数字图片；匹配 Count 使用与进度页相同的人数数字与斜杠图片。CloudRiseCounter 同时支持十张整数数字和十一张分数数字，不再用 Label 绘制这两个值。
- RewardHint 改为圆角矩形，文字图片四周各 20px 内边距，无三角尾部。晋级头像保持分批起跳和速度差异，使用一条平滑二次曲线，控制点不超过起终点较高处 42px，落地恢复原角度。
- 首页总览左上角和三个阶段进度页左上角增加 ActivityHelp。说明内容来自“月光宝盒玩法说明0918”，共用 home 中的 ActivityGuide 和三张说明图片；关闭说明只返回原活动页面，不触发点击继续。匹配和胜负结算期间不显示说明按钮。
- 首页淘汰结算优先级为 0，奖励结果优先级为 1，均先于其他首页活动队列。放弃结果仍在同步时也先占住队列，完成同步后播放淘汰动画，手动继续后再放行其他弹窗；转场结束检查保留。
- Pending 仍作为 save_reward 未成功时的异常兜底。正常收到奖励保存成功回执后立即显示实际金币数；不能仅凭胜利状态就显示奖励已到账。

本次 139 项百人赛专项检查通过，Creator 2.4.15 微信完整构建成功。新增数字、说明入口、说明页和气泡已做独立 Cocos 渲染检查；预览头像使用占位图，尚未进行微信真机完整流程测试。

2026-09-18 后续调整：阶段云端头像在各云原有尺寸基础上统一缩小 10%，堆叠间距单独按云宽调整，大云更松、小云更紧，玩家层级仍在最前。首页 ActivityHelp 移到弹窗内左上角（设计坐标 -345、495）。ActivityGuide 删除 GuideClose，完整的新点击手势关闭说明并拦截事件，不会同时关闭活动或触发继续。