105 lines
17 KiB
Markdown
105 lines
17 KiB
Markdown
# 百人赛页面与分包
|
||
|
||
更新日期：2026-09-22。
|
||
|
||
## 目录
|
||
|
||
| 目录 | 打包方式 | 内容 |
|
||
| --- | --- | --- |
|
||
| 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 共用的图片 |
|
||
|
||
matching/stage1/stage2/stage3 与 art 均为独立 Bundle，父目录 assets/cloud_rise 是普通目录，不能勾选 Is Bundle。页面优先级为 3，art 为 5，home 为 6，公共字体继续由启动包持有。微信平台的五个子 Bundle 设置为 isRemoteBundle=true、compressionType=merge_all_json；home 保持主包内的本地 Bundle。其他平台设置不变。
|
||
|
||
项目扩展 packages/cloud-rise-package 在 build-finished 阶段，将五个独立 Bundle 与简版 version.json 输出到同一远程目录。客户端查询版本并对比本地记录，百人赛的配置、合并 JSON 和图片等请求统一携带 ?v=版本号，同版本复用 Cocos 缓存，换版后按需下载新资源。此方案不生成 ZIP、不使用 wx.loadSubpackage，也不在 game.json 中声明百人赛分包。脚本留在 Creator 生成的本地 src/scripts 中，远程 Bundle 仅更新资源。
|
||
|
||
扩展将发布产物输出到微信构建目录的同级目录 <构建目录名>-cloud-rise/remote/cloud_rise/，其中包含 version.json 和同级的 art、matching、stage1、stage2、stage3 目录；每个 Bundle 的固定入口为 config.json。同时在 project.config.json 中排除 remote 和旧百人赛 subpackages 目录。暂不使用 manifest.json。详见 [远程资源发布步骤](cloudRise-remote-package.md)。
|
||
|
||
## 公共图片归属
|
||
|
||
cloud_rise/art 保留 art 这一 Bundle 名称和图片 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 和远程版本信息，不阻塞首页。报名窗口已结束但个人挑战未结束时仍可加载资源。
|
||
- 可开始匹配时优先加载 art 和 matching 预制体及依赖，三个 stage 按需独立加载。打开总览后提前实例化隐藏匹配页，点击开始复用。预准备失败不报名，点击开始可重试；按钮固定使用“开始”美术，不再叠加 CaptionCover/Caption。
|
||
- 手动点击开始/开始下一阶段，同时准备匹配页与目标 stage；匹配页就绪后立即显示，不等待 stage。准备期间显示本人头像及 1/100，匹配期间不展示取消按钮和右上角关闭按钮。下载可以继续并缓存，供再次开始复用。
|
||
- 目标 stage 就绪后通过 prepare_match 准备对手，再播放头像入场；匹配页已移除手动取消入口；底层取消草稿机制保留。取消返回总览，以 cancel_match 清理草稿，保留本期报名机会、前一阶段进度和奖励。取消写入本地同步队列，断网或重启后继续发送；旧请求不能触发报名或覆盖新匹配。
|
||
- 达到 100/100 时调用 confirm_match 正式参加并显示“点击以继续”，点击后进入进度页。首次参加的个人挑战计时从确认时开始，后续阶段沿用原截止时间。需先发布支持这三个操作的 cloudRise/index 后端，再更新客户端；旧后端会拒绝准备请求，不会误扣资格。
|
||
- 查看已参与的进度、逐关结算或恢复未看完的结算，仅加载当前 stage。
|
||
- 首页查看进度保留右上角关闭按钮；逐关动画、胜利和失败结算隐藏关闭按钮，动画完成后显示底部“点击以继续”。stage1/2 胜利点击后切回活动弹窗，下一阶段由玩家点击“开始”；stage3 胜利、失败及普通逐关进度点击后继续调用方的流程。提前按住或动画中的点击不会跳过展示。
|
||
- 活动倒计时结束时，HomeScene 隐藏入口并关闭已打开的活动页面，不播放超时淘汰动画。在 GameScene 超时后返回首页，同样清除超时展示记录，不补播；已打开的游戏内 stage 保留原地超时动画。这里只确认超时展示，不清除普通胜负记录或待保存奖励。
|
||
- 切换 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，节点结构与布局未改动。此次未进行真机流程验证。
|
||
|
||
目录和分包清单变化后需要重新构建微信包，不能继续使用旧构建产物。当前为公共图片及四个页面分别发布独立远程 Bundle，不能继续使用旧的微信分包或 ZIP 加载器。
|
||
|
||
## 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，完整的新点击手势关闭说明并拦截事件，不会同时关闭活动或触发继续。
|
||
|
||
### 首次解锁与分段说明（2026-09-23）
|
||
|
||
首页入口以 `GM_INFO.level >= unlockLevel` 为显示门槛，已保存的活动状态也不会绕过门槛。进入 HomeScene / 首页回到前台时刷新活动列表，读取 `openingRules`，仅在已达门槛、没有已开启个人期、距上次活动结束严格超过 12 小时（首次参与免等待）且 enabled=true 时请求 `cloudRise/index action=open_period`。成功回执后缓存新个人期并显示入口；普通轮询、登录和过关上报均不自动开期。离开首页后不再发起尚未开始的开期请求，已发送请求的迟到响应按账号隔离，重复请求不重置倒计时。
|
||
|
||
说明页 `ActivityGuide` 中的 `GuidePart01`～`GuidePart07` 依次展示标题、参赛玩家、云朵路径、箭头、宝箱、分享奖励说明和失败提示。参照通票，每组间隔 0.3 秒，以 0.3 秒 `backOut` 从零放大。点击关闭或面板关闭时停止动画，再次打开从头播放。新拆图放在 `cloud_rise_home/images/guide_*.png`，首页及三个 stage 共用同一说明页。
|
||
|
||
提供的原图 `yun.png` 自带蓝色矩形底色，仍按原图保留。`01.png` 通过 `guide_competitors.plist` 分别引用玩家云朵及文字区域，不显示截断箭头；`GuidePart02Competitors/MirroredArrow` 复用完整的 `guide_arrow` 图片，按下方箭头的水平镜像排版，与该组说明一起弹出，无新增箭头贴图。
|
||
|
||
百人赛同步不再作为棋盘输入门禁：拖动、锤子和魔法道具均立即响应；参赛记录先保存在本地队列，网络失败由现有定时同步重试。无业务模块的冷启动只触发节流后的后台恢复，不在异步返回时补造本关开始记录。过关后同步失败也允许继续下一关。后端 open_period 不再复核玩家关卡或冷却，已开期后的报名状态也不依赖数据库关卡数。
|
||
|
||
宝箱提示改为 Progress 下的独立 HintText（rewardHint 绑定直接指向此节点），移除 RewardHint 气泡背景。三个阶段统一使用 stage1 编辑后的 328.4 × 39 尺寸；点击宝箱后从初始位置上移 60，随后再上移 20 并淡出，总时长 0.9 秒。重复点击从初始位置重播；切换页面、打开说明或关闭面板时停止并隐藏。
|
||
|
||
匹配页显示 1 秒后先滚动等待人数，最多到 95/100；资源和对手资料准备好后播放头像入场并递增到 99/100，confirm_match 成功才显示 100/100 并等待点击继续。准备/确认接口失败以 toast 提示“匹配失败请重试”。胜利宝箱的 ChestSparkles 子节点使用不同周期和相位的透明度闪烁（20%～100%），关闭或切换页面恢复原始透明度。三个 stage 的 ProgressStart 由 y=-950 调整为 -990，头像大小不变。普通游戏期间活动超时，关卡结束/下一关不再展示活动过期结算；已打开活动 stage 页面内的超时表现保持原有流程。
|
||
|
||
### 活动总览与退出结算（2026-09-24）
|
||
|
||
- 匹配页删除 StreakHint；人数和头像填充流程保持不变。
|
||
- 总览 PanelTop 更换为 20260924-152732.png，保留九宫格下方内容区域。宝箱使用独立 Chest 节点（452×323，PanelTop 局部坐标 0、321），按 jiem.png 排版；ChestSparkles 位于宝箱上方，复用胜利页的错峰透明度闪烁。
|
||
- chest.png 连同原 UUID 移入主包 cloud_rise_home，匹配与阶段页继续共用这张图片，避免首页依赖远程 art 或重复贴图。此次资源变化需要主包及五个远程 Bundle 一起重新构建，远程版本为 1.0.2。
|
||
- 总览打开沿用月卡的三段回弹时长与相对缩放；关闭先放大再缩小收起。当前阶段 Badge 动态绘制窄白金色光晕，阶段改变时切换高亮。
|
||
- 胜利页 VictoryCoins/Rays 每 12 秒匀速旋转一圈，只旋转射线，退出后恢复原始角度。
|
||
- 失败后确认返回首页（包括暂停页退出）先播放百人赛结算并等待点击继续，再执行方块转场及 HomeScene 加载。普通关卡期间活动自然过期仍不展示淘汰结算，网络异常沿用现有非阻塞重试。
|