148 lines
19 KiB
Markdown
148 lines
19 KiB
Markdown
# 百人赛 Prefab 与登录预加载
|
||
|
||
更新日期：2026-09-12。产品规则继续使用 PRD V1.1，包括阶段间必须手动点击开始。
|
||
|
||
## 资源与代码位置
|
||
|
||
```text
|
||
assets/cloud_rise/ 独立活动分包
|
||
prefab/CloudRise.prefab 活动页面，布局维护的唯一来源
|
||
scripts/CloudRisePanel.ts 页面数据绑定、按钮响应、动态名单
|
||
scripts/CloudRiseRuntime.ts 活动状态、持久化队列、关卡结算与恢复
|
||
scripts/CloudRiseSurface.ts 可在编辑器预览的圆角底板组件
|
||
images/ 原始美术资源
|
||
```
|
||
|
||
主包只保留必须先运行的接入代码：`CloudRiseService.ts` 查询资格、加载分包和转发主线事件；`CloudRiseView.ts` 挂载首页/游戏入口、实例化页面、协调暂停和首页弹窗。主包没有静态导入分包业务类，也没有直接引用活动 Prefab 或图片。
|
||
|
||
## 在 Cocos Creator 2.4.15 中维护
|
||
|
||
双击 `assets/cloud_rise/prefab/CloudRise.prefab` 进入 Prefab 编辑模式。固定页面节点不再由脚本生成；在编辑器修改坐标、尺寸、颜色、字体、图片及按钮样式后保存即可。
|
||
|
||
根节点 `CloudRisePanel` 挂载同名控制组件。`Design` 的尺寸为 1080×2200，运行时按可视区域等比适配。只有半透明黑色遮罩填满屏幕：首页保留在弹窗后方。总览底板按设计稿使用 902×1366 的九宫格图片，其他页面使用独立的圆角弹窗底板。
|
||
|
||
总览、匹配、进度与胜利结算金额使用 `CloudRiseNumberToImage`，Inspector 中可调整默认金额、数字高度、宽度比例、间距和金币间距。每个 `Digits` 容器固定包含 `Digit0`～`Digit4` 五个 Sprite 节点，根据接口奖池或已保存奖励逐位替换 SpriteFrame，不足五位时隐藏剩余节点；金额变化不创建、销毁节点。配置金额限制在 0～99999，超出五位不会截断后显示错误金额。组件的 `digits` 数组仍绑定 0～9 共十张图片，它是字形资源表，不是节点数量。
|
||
|
||
奖池数字通过 `reward_mask` 材质在一个 Sprite 内绘制白边、红棕描边和黄色填充，不再用多层节点叠加。材质接收各字形的图集范围与显示尺寸，边缘采样不会串到相邻数字；`reward_digits` 图集应保持不旋转、不参与动态合图。胜利奖励继续使用带描边的原始数字素材。金额变化时自动居中排版，必要时缩小至节点宽度内。图片、图集和材质均在活动分包的 `images/`，不依赖主包字体图集。页面的 Overview Pool 字段绑定这个组件，不能绑定 Label。
|
||
|
||
总览金额优先采用当前阶段记录的 pool；等待进入下一阶段时采用下一阶段配置值。倒计时统一使用深蓝圆角底、白色时钟和 `HH:mm:ss`，不附加“报名剩余/挑战剩余”文字；报名窗口与个人配置时长截止时间的判断规则保持不变。
|
||
|
||
| Design 下节点 | 用途 |
|
||
| --- | --- |
|
||
| Overview | 三阶段总览、阶段奖池、开始/开始下一阶段按钮 |
|
||
| Matching | 匹配过程 |
|
||
| Progress | 当前阶段进度、人数、奖池和台阶 |
|
||
| Result | 共用的成功/失败/超时结算页面 |
|
||
| Participants | 带裁剪区域的 100 人名单 |
|
||
| Templates/ParticipantRow | 名单行模板，一行 4 人 |
|
||
| Close、Error、Retry | 共用关闭、错误提示与重试按钮 |
|
||
|
||
默认只激活 Overview。编辑其他页时，先关闭 Overview，再激活要维护的页面；保存前可恢复为 Overview，运行时控制器也会按状态切换。Templates 默认关闭，编辑名单模板时可临时激活；保存后关闭，以免把模板本体显示在页面上。
|
||
|
||
Progress 内三组台阶分别为 5、7、9 关，各组位置均已存入 Prefab。头像队伍站在当前关卡云上表示进度，代码不覆盖云朵坐标。名单通过复制 ParticipantRow 并由 Content 的 `cc.Layout` 排列，调整行高或间距可直接编辑模板和 Layout。
|
||
|
||
运行时，CloudRisePanel 以 Prefab 坐标为基准，让当前激活的 StageSteps 下各 Step 上下浮动，振幅为 8～12 个设计像素，各云朵周期错开。进度页和逐关淘汰展示期间均播放，隐藏阶段不运动；离开页面或切换阶段时恢复基准位置。停留在云上的头像同步浮动，起跳或掉落时解除跟随，落地后跟随目标云朵。
|
||
|
||
重要引用通过根组件 Inspector 字段保存：Pages 的顺序为总览、匹配、进度、结算、名单；Buttons 的顺序为关闭、开始阶段、查看名单、返回总览、返回进度、重试。进度页的起点云为装饰节点，不提供继续闯关入口。移动或重命名这些引用节点不影响绑定；删除节点后应重新绑定对应字段。
|
||
|
||
关闭按钮 `Design/Close` 使用 `images/close.png`，从 newbieGift 所用的 `assets/res/close.png` 原样复制，并在活动分包内分配独立 UUID。新美术到位后替换这个节点的 Sprite Frame 即可，保留 Button 组件及根组件 Buttons 的第一个引用。原有紫色底板和“关闭”文字已移除。
|
||
|
||
头像模板内部的 `Face/Photo`、`Face/Cat`、`Name`、`Status` 为绑定约定，不要直接改名；若修改，需同步 `CloudRisePanel.avatar()`。圆角底板通过 CloudRiseSurface 的 Radius、Border Width、Border Color 和节点颜色维护。
|
||
|
||
总览六种状态的说明文案可以修改根组件的 Overview Copy。阶段数、进度、奖励、人数和动作按钮文案由业务状态决定，运行时会更新相应 Label 内容，但保留 Prefab 的布局和字体样式。
|
||
|
||
## 登录后加载策略
|
||
|
||
登录接口成功、玩家资料和本地金币恢复完成后，`GameManager` 调用 `CloudRiseService.afterLogin()`。该方法不加入登录完成条件、不阻塞进入首页，也不创建匹配。
|
||
|
||
1. 先请求服务端 `cloudRise/cloudRise`（action 为 `status`），不能仅凭旧的本地活动存档决定下载。
|
||
2. 满足以下任一条件，后台加载 `cloud_rise` 并准备 `prefab/CloudRise` 及其引用资源：当前服务端允许报名，且报名窗口有效；或者玩家轮次处于 playing/waiting，且个人截止时间未到；或者存在已成功但 rewardSaved 尚未完成的阶段，需要补存奖励。
|
||
3. 报名已结束但个人挑战仍有效，继续预加载；未开放、未达到资格、已用完机会且无进行中挑战、已超时或资格查询失败，不自动下载分包。
|
||
4. 预加载只准备资源，不实例化页面、不自动开始阶段，不提前加载 100 个头像。
|
||
5. 多个入口共用同一次分包/Prefab 加载；成功后保留 Prefab 引用以供页面复用，失败后允许重新加载。进入页面时等待同一个加载任务，后台失败不会使登录失败。
|
||
6. 在本次会话参与中的失败、完成或超时，仍可以显示结算。登录时仅有已结束历史记录，不为了自动弹历史结果额外下载分包；玩家主动点历史活动入口时才按需加载。
|
||
|
||
百人赛请求的 uid 与本地存档键 `cloudRise:<onlyId>` 使用登录返回的 `users.onlyId`，客户端对应 `GM_INFO.userId`。Runtime 中的未完成尝试恢复、离线已记录胜利补传、手动开启阶段继续沿用；金币由 Runtime 在前端计算，上报保存成功后更新本地余额。
|
||
|
||
后台配置删除 `status/enabled`，报名只按 startsAt/endsAt 判断。个人期限取报名时 durationHours（小时，默认 24），已报名期限不受改配置影响。全部完成、失败、超时后隐藏入口，未播放结算仍独立处理。
|
||
|
||
## 本地检查
|
||
|
||
```sh
|
||
node --test tools/test-cloud-rise.cjs tools/test-cloud-rise-prefab.cjs tools/test-prop-guide.cjs tools/test-battle-pass.cjs
|
||
node tools/preview-cloud-rise.cjs
|
||
```
|
||
|
||
预览默认读取 `build/cloud-rise-prefab-verification/web-mobile`，必须先完成一次 web-mobile 构建。可用环境变量 `CLOUD_RISE_BUILD` 指定其他同版本构建目录。预览使用实际构建的 Prefab、脚本、引擎和资源包，只替换活动接口状态，不访问生产 API。重新构建后重启预览进程以刷新带哈希的引擎文件名。
|
||
|
||
构建目录：`build/cloud-rise-prefab-verification`。验证时需要检查 CloudRisePanel、CloudRiseRuntime、CloudRiseSurface 的模块定义只存在于 cloud_rise 的脚本包，且 Prefab 只存在于活动包；只看源目录不足以证明没有被主包引用。
|
||
|
||
本次改动不包含云函数部署或活动开放。小游戏真机的下载耗时、低内存情况和后台恢复仍需在发布前验收。
|
||
|
||
验证结果：前端相关 45 项、后端专项 23 项通过；类型检查与基线相比无新增诊断（原有 17 条保留）。web-mobile 和 wechatgame 构建均退出 0，构建产物确认业务/页面模块未进入主包。实际 Prefab 预览已验证报名、三阶段进度、手动开始下一阶段、成功/失败/超时和名单滚动，无新页面控制台错误。
|
||
|
||
2026-09-12 身份与关闭按钮调整验证：前端 45 项、后端 23 项通过；Web 构建成功，onlyId 请求与按状态读取活动均由真实前后端联调测试覆盖。
|
||
|
||
前端发奖方案更新：已移除 CloudRiseWallet 及跨活动累计奖励补差，结果页对未保存的成功奖励显示“奖励待到账”。历史构建记录保留供参考，当前验证见开发记录。
|
||
|
||
## 2026-09-14 匹配与逐关淘汰动画
|
||
|
||
- Matching 页新增可编辑的 AnimationGrid、AnimationDetail，Prompt 和 Count 分别绑定 Animation Title、Animation Count。固定布局仍在 Prefab 内；运行时复制 ParticipantRow 的头像模板，生成 10×10 的 100 人名单。
|
||
- 点击开始后先等待匹配；拿到服务端实际对手后，头像依次缩放弹出并更新人数，展示匹配成功后进入进度页。等待及动画期间禁止重复操作。
|
||
- 主线关卡不显示活动入口。仍保留 CloudRiseView 组件处理同步和通关展示，首页入口规则不变。
|
||
- 每次服务端确认连胜进度增加，将前后阶段快照写入本地 journal.eliminations。仅本关新淘汰的头像下落淡出，先前被淘汰的头像保持暗淡；无人淘汰和阶段最终胜利也会展示。
|
||
- Map 原有胜利结算前播放待展示的淘汰动画。网络同步和资源加载各最多等待 2.5 秒；未能展示的记录保留，后续首页弹窗队列补播，并先于阶段结算。普通未报名玩家不等待活动同步。
|
||
- 播完才移除记录；轮询及重试不重复生成，页面销毁不会误记为已播放。动画不改变奖励计算、胜负上报及手动开始下一阶段的规则。
|
||
|
||
检查：百人赛状态、页面、Prefab 与动画测试共 45 项通过，道具引导及通行证相关 27 项通过。客户端类型检查仍为原有 17 项诊断，本次相关文件无新增诊断。通过 Cocos 预览引擎加载当前源码和原始 Prefab、复用已有构建纹理，验证了匹配弹出及逐关淘汰画面；完整 web-mobile 构建停在资源库初始化后已停止，尚未验证本次完整发布产物。
|
||
|
||
## 2026-09-14 按中间态效果图调整匹配页
|
||
|
||
Matching 页已改为 `百人赛界面中间0909-.jpg` 对应的全屏星空场景，包含标题、月亮、桂花枝、宝箱云朵、动态奖池、提示框和底部头像云朵。背景等比铺满，其他元素保留设计稿比例。匹配页无倒计时或关闭按钮；首页总览仍是弹窗。
|
||
|
||
新增 `matching_prompt_background`、`matching_prompt`、`matching_frame_left`、`matching_frame_right` 原始素材及独立 UUID。匹配奖池复用 CloudRiseNumberToImage，报名阶段使用接口配置，匹配返回后使用实际 stage.pool。
|
||
|
||
匹配头像逐个累积，已出现的头像不再隐藏、替换或移动。使用与进度页一致的错排堆叠布局，自己在前排，最多展示 18 个对手代表头像；头像框复用 Prefab 的 BackLeft、BackRight、Front 模板。每个代表头像弹出后按其对应批次更新匹配人数，最终显示完整名单的 100/100，再切换到进度页。只有开始下一次阶段匹配时才清理上一组头像；页面销毁时停止所有头像动画。
|
||
|
||
Pages 第 2 项绑定新的 Matching。Matching Background/Prompt/Title/Count/Reward/Slots 分别绑定对应节点或组件。曾使用的独立 Elimination 网格页已由下述云梯跳跃演出取代，胜负展示均复用 Progress 页。
|
||
|
||
验证：48 项百人赛相关测试通过，覆盖 100 个独立头像、固定位置不重叠、旧头像保留、下一阶段清理与逐关淘汰。Cocos 源码与原始 Prefab 预览确认人数递增至 100/100、先出现的头像在后续弹出期间身份和位置不变、最终全部可见，无页面脚本异常。尚未验证完整发布构建。
|
||
|
||
## 2026-09-14 按游戏内效果图调整进度页
|
||
|
||
Progress 使用 `百人赛界面游戏内0909.jpg` 对应的全屏星空场景，关闭原有弹窗底板。顶部为本阶段的月桂树、捣药台或广寒宫，统计栏使用原始标题、分界线和紫边底框，倒计时保留玩家本轮固定的个人截止时间。
|
||
|
||
阶段 1/2/3 分别显示 5/7/9 朵关卡云，使用原始 `登云.png` 和 `小圆点.png` 组成从底部通往宝箱的路线。云朵保持完整显示，当前进度由头像队伍所在位置表示。起点云和宝箱云为装饰，不计入关卡数量。对应位置、大小、连接点都保存在 Prefab；9 关路线的云朵稍小以完整展示。
|
||
|
||
`Progress Pool` 改为绑定 CloudRiseNumberToImage，显示当前 `stage.pool`（默认 10000/15000/20000，支持后台配置的其他金额），不再使用黄色文字 Label。右上角保留关闭入口；底部起点云只展示头像队伍，不提供“继续闯关”文字或点击操作；点击统计栏的剩余人数可查看参赛名单。
|
||
|
||
验证：源码及原始 Prefab 预览逐一核对三个阶段的云朵数量、关卡统计、勾选标记和奖池，额外验证自定义金额 23456、参赛名单往返及继续闯关。页面无脚本异常；类型检查仍为此前 17 项诊断。完整发布构建尚未验证。
|
||
|
||
## 2026-09-14 云梯头像队伍与胜负演出
|
||
|
||
初始队伍在右下角起点云，玩家自己位于前排并使用较大的蓝色头像框。显示自己和最多 18 个对手头像，允许堆叠遮挡；人数统计始终使用完整服务端名单。正常查看进度时，存活队伍位于当前已通过的关卡云上，替代先前的绿色勾选。Progress Start 为起点头像坐标，Progress Roster 为统一头像绘制层。
|
||
|
||
头像队伍按 4/5/5/4 个对手错排，扩大横向间距和纵向露出面积。起点队伍使用 1.3 倍布局和头像尺寸，宽约 350 设计像素，自己位于前排中央；跳到关卡云时随落地动画收至对应云朵可承载的大小。匹配页复用同样的错排布局，进一步放大到宽约 400 设计像素，避免原先大量微小头像铺成网格。
|
||
|
||
每次确认关卡结果都在 Progress 页播放：成功时自己先跳到下一朵云、其他过关者随后跳、淘汰者最后掉落；失败时过关者先跳到下一朵云、自己掉落、其他淘汰者最后掉落。成功后更新个人通关数，失败时个人通关数保持不变；掉落过程更新人数，最终与服务端 survivors 一致。动画样本同时包含幸存与淘汰者，未抽样展示的对手仍计入统计。
|
||
|
||
胜利和失败均持久化前后快照到 journal.eliminations，失败键增加 `:lost` 后缀，避免与同一通关数的胜利演出冲突。只有服务器确认的状态变化生成记录，完成播放才确认移除。断网、关页或重启会保留未播放记录，联网后补播。复活机会出现时不判负；最终放弃、重开和失败确认等待本次演出后再继续原有流程，重复点击由统一入口拦截。
|
||
|
||
验证：实际 Cocos 源码与 Prefab 预览检查了初始 100 人队伍、成功和失败两种跳跃/掉落顺序、人数结算及前后云朵落点，无页面脚本异常。专项测试覆盖播放顺序、全员失败、最终胜利、失败断网恢复、去重及播放期间离开场景。完整发布构建尚未验证。
|
||
|
||
## 2026-09-14 获胜结算与下一阶段衔接
|
||
|
||
获胜结果使用 `Design/Victory` 遮罩层，背景保留本阶段的 Progress 页，旧 Result 面板用于超时。`VictoryTitle`、`VictoryChest`、`VictoryCoins`、`VictoryPeople` 依次弹出，每组 0.35 秒缩放渐显，间隔 0.5 秒；演出结束后显示关闭按钮。最后一关的云朵演出结束后直接进入此结算，关闭后再显示主线胜利弹窗。
|
||
|
||
美术新增 `victory_*` 独立资源：提供的获胜标题、说明和结算数字原图，金币堆及光效复用项目素材并复制到分包。金币数字组件启用 `sourceArt` 和关闭 `showCoin`，保留原始白字描边。自己单独展示，其他存活者最多显示 7 个代表头像；不足 7 个时居中，人数文案使用真实存活数减一，独赢时隐藏他人行并更换说明。
|
||
|
||
新结算奖励计算为 `ceil(ceil(pool / survivors) / 10) * 10`。201 发 210，3334 发 3340，整十金额不增加；已保存的历史回执不重新补发。仍由前端计算、上报和更新余额，服务端负责持久化。
|
||
|
||
stage1/2 成功后点击主线“下一关”，先同步奖励并调用下一阶段匹配，成功后才切换关卡，失败可重试。返回首页则队列弹出 overview，等待手动点击“开始下一阶段”；状态轮询和引导自动跳转不会开启新阶段。stage3 完成后正常继续主线。
|
||
|
||
验证：百人赛、道具引导及通行证相关累计 89 项测试通过，包含展示顺序、关闭前等待、奖励边界与重试、下一关点击去重、首页手动开始。当前源码和 Prefab 已通过实际 Cocos 引擎预览，49 人获胜及独赢页面无脚本异常。类型检查仍保留原有 17 条诊断，无新增；本次完整发布构建尚未验证。
|
||
|
||
失败演出衔接更新：淘汰动画结束后直接在当前 Progress 页显示 `FailureMessage`（原始素材 `shibaiwenzi.png`，分包内命名为 `progress_failure.png`），隐藏 `progressStatsContents` 和头像队伍，保留该阶段主题、云梯、奖池和个人截止倒计时。关闭后确认结果已展示，再继续原有重开/返回流程；首页不重复自动弹出。离线尚未确认的失败仍保留原有同步补播机制。相关页面、演出与 Prefab 共 44 项测试通过，源码 Cocos 预览无异常，类型检查无新增诊断。
|
||
|
||
2026-09-16：Overview/DescriptionImage 绑定原始说明文字.png（558×98）；未参加、挑战中和等待下一阶段均展示，Description 标签仅作为缺失图片时的回退。终态隐藏说明图和标签。Victory 统一使用分享奖励图片，独赢时 Others 显示 0，Solo 不展示。第三阶段奖励手动关闭后直接退出，不再进入总览。
|