61 lines
9.3 KiB
Markdown
61 lines
9.3 KiB
Markdown
# 百人赛页面与分包
|
||
|
||
更新日期：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。打开总览后提前实例化隐藏匹配页，点击开始复用。预准备失败不报名，点击开始可重试；按钮固定使用“开始”美术，不再叠加 CaptionCover/Caption。
|
||
- 手动点击开始/开始下一阶段，同时准备匹配页与目标 stage；匹配页就绪后立即显示，不等待 stage。准备期间显示本人头像及 1/100，页面底部显示“取消匹配”，不展示右上角关闭按钮。下载可以继续并缓存，供再次开始复用。
|
||
- 目标 stage 就绪后通过 prepare_match 准备对手，再播放头像入场；尚未达到 100/100 时均可取消，包括请求在途及动画期间。取消返回总览，以 cancel_match 清理草稿，保留本期报名机会、前一阶段进度和奖励。取消写入本地同步队列，断网或重启后继续发送；旧请求不能触发报名或覆盖新匹配。
|
||
- 达到 100/100 时隐藏取消按钮，调用 confirm_match 正式参加并显示“点击以继续”，点击后进入进度页。首次参加的个人挑战计时从确认时开始，后续阶段沿用原截止时间。需先发布支持这三个操作的 cloudRise/cloudRise 后端，再更新客户端；旧后端会拒绝准备请求，不会误扣资格。
|
||
- 查看已参与的进度、逐关结算或恢复未看完的结算，仅加载当前 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 资源、按需加载、失败重试、关闭中断、点击继续、图片人数、完整获胜名单及胜负动画和奖励流程。
|
||
|
||
本次使用实际 Cocos 2.4.15 引擎和源码预制体做隔离预览，验证主包弹窗、匹配、三个 stage、胜利返回总览和失败页面，并实际点击验证继续、宝箱提示和关闭交互。头像数据使用预览占位，真实玩家头像请求仍沿用原逻辑。未重新构建微信发布包或进行真机验证。完整类型检查被现有 server/laf-cloud/functions/drawHead.ts:35 的语法错误阻断；本次变更文件的 TypeScript 转译通过。
|
||
|
||
目录和分包清单变化后需要重新构建微信包，不能继续使用旧构建产物。当前统一分包不是旧的单预制体 cloud_rise Bundle；其内部仍保留四套独立的 Bundle 配置。
|