Repository Guidelines

项目结构与模块组织

本仓库是 Cocos Creator 3.8.8 小游戏项目。主入口在 assets/main.ts，主场景是 assets/main.scene。页面与弹窗组件集中在 assets/prefabs/，命名通常为 PageXxx.ts、PassModal.ts。公共逻辑位于 assets/scripts/：core/ 放页面基类与视图管理，utils/ 放 SDK、鉴权、存储、网络等工具，config/ 放接口配置，types/ 放类型定义。静态资源在 assets/resources/，编辑器配置在 settings/v2/packages/，设计说明在 docs/ 与根目录分析文档中。

构建、调试与开发命令

先运行 npm install，同步 minigame-api-typings 依赖。日常开发主要通过 Cocos Creator 编辑器完成：使用 3.8.8 打开仓库，点击 Play 预览，使用 Project > Build 或 Cmd+B 构建小游戏包。若编辑器已生成 temp/tsconfig.cocos.json，可执行 npx tsc --noEmit 做一次 TypeScript 静态检查。

代码风格与命名约定

项目使用 TypeScript，当前代码统一为 4 空格缩进。组件类、页面类、管理器类使用 PascalCase，实例属性与私有方法使用 camelCase / _camelCase，管理器统一使用 XxxManager 后缀。新增页面、预制体、脚本请保持同名，例如 PageLevel.prefab 对应 PageLevel.ts。优先把复用逻辑放入 assets/scripts/utils/ 或 assets/scripts/core/，不要把业务代码散落到场景脚本中。Cocos 资源的 .meta 文件必须一并提交。

测试与验证

仓库当前未配置 Jest、Vitest 一类自动化测试。提交前至少完成三项验证：1. 编辑器预览主流程可进入页面；2. 目标平台构建成功；3. 涉及微信能力时，在真机或开发者工具验证登录、分享、隐私授权等流程。若修改接口或体力/关卡逻辑，补充手动验证步骤到 PR 描述。

好友分享挑战链路

当前好友分享挑战是独立于普通闯关的一条链路，核心入口和数据流如下。

选题入口在首页 PageHome，点击 PK 按钮后进入 PageWriteLevels，不是从普通 PageLevel 内发起。assets/prefabs/PageHome.ts
PageWriteLevels 会通过 CompletedLevelsManager.fetch() 拉取当前用户“已通关关卡”列表，只允许从这些题里选题；当前规则要求必须选满 6 关才能预览或正式创建分享。assets/prefabs/PageWriteLevels.ts assets/prefabs/PageWriteLevels.ts
预览按钮只做本地预览：把 selectedIndices 和 shareTitle 传给 PagePreviewLevels，后者再从 CompletedLevelsManager 缓存中按索引读取答案、提示和封面图展示，不会请求后端。assets/prefabs/PageWriteLevels.ts assets/prefabs/PagePreviewLevels.ts
正式分享时，PageWriteLevels 会把选中索引转成 levelIds，调用 ShareManager.createShare(title, levelIds) 命中 POST /share 创建挑战，服务端返回 shareCode。assets/prefabs/PageWriteLevels.ts assets/scripts/utils/ShareManager.ts
创建成功后，页面会尝试补充一次发起者头像昵称信息，再调用 WxSDK.shareAppMessage 发起微信转发；真正落到分享卡片上的关键信息只有标题和 query=shareCode=xxx，没有把题目内容塞进 query。assets/prefabs/PageWriteLevels.ts assets/scripts/utils/ShareManager.ts
被分享用户从微信卡片进入小游戏时，启动页 PageLoading 通过 WxSDK.getShareCodeFromLaunch() 读取启动参数。如果拿到 shareCode 且登录成功，会先调用 ShareManager.joinShare(code) 命中加入分享接口，再跳过首页直接打开 PageLevel，并带上 params.shareMode = true。assets/PageLoading.ts assets/scripts/utils/WxSDK.ts
ShareManager.joinShare() 会把服务端返回的分享关卡列表转成运行时 RuntimeLevelConfig[]，缓存到内存里；这里不会再走普通闯关的 AuthManager.nextLevel / LevelDataManager / enterLevel 链路，首关图片会被预加载，后续关卡按需懒加载。assets/scripts/utils/ShareManager.ts assets/scripts/utils/ShareManager.ts
PageLevel 在 shareMode 下会把 _shareLevelIndex 置为 0，进入 _enterAndInitLevel() 时直接从 ShareManager.ensureShareLevelReady(index) 取当前题配置，跳过普通模式里的 StaminaManager.enterLevel()，因此分享挑战不消耗体力，也不依赖普通闯关的 enter 接口回填答案和提示。assets/prefabs/PageLevel.ts assets/prefabs/PageLevel.ts
分享挑战里的作答判定仍然完全在 PageLevel.onSubmitAnswer() 本地完成，即把用户输入与当前 config.answer 做字符串相等比较；答对后走成功弹窗和下一题，答错后走错误弹窗。assets/prefabs/PageLevel.ts
分享模式通关后只会上报 POST /share/progress，参数是 shareCode + levelId + passed + timeSpent。当前代码只在答对时调用，超时和答错不会上报失败结果，所以服务端拿到的是“成功通关进度”，不是完整作答事件流。assets/prefabs/PageLevel.ts assets/scripts/utils/ShareManager.ts
分享模式切下一题时只是 _shareLevelIndex++，直到分享题单做完后清掉 ShareManager 的内存态并 replace('PageHome') 返回首页。中途从超时弹窗回首页，也会先清理分享态。assets/prefabs/PageLevel.ts assets/prefabs/PageLevel.ts

已知约束与缺口

PageLevel 的分享模式标题显示的是“第 1 关、第 2 关”这种分享内序号，不是原题库真实关卡号。assets/prefabs/PageLevel.ts
PassModal 和 TimeoutModal 里的分享按钮仍然发的是普通 level=... query，不是 shareCode 挑战链路；这两处分享目前不能把用户重新带回当前好友挑战，只是普通分享文案。assets/prefabs/PassModal.ts assets/prefabs/TimeoutModal.ts
ShareManager.joinShare() 构造 RuntimeLevelConfig 时没有填 timeLimit，而 PageLevel 会用 config.timeLimit ?? 60 兜底，所以分享题当前统一按 60 秒处理，除非后端后续补字段、前端同步接入。assets/scripts/utils/ShareManager.ts assets/prefabs/PageLevel.ts
PagePreviewLevels 和 PageWriteLevels 的选题/预览都依赖“索引对应同一份 completed list”的前提。如果列表数据在两个页面生命周期之间发生变化，按索引取题会有错位风险，更稳妥的做法其实是直接传 levelIds 或完整快照。assets/prefabs/PageWriteLevels.ts assets/prefabs/PagePreviewLevels.ts

提交与 Pull Request 规范

Git 历史采用 Conventional Commits，且摘要多为中文，例如 feat: 支持分享关卡通关上报、fix: 修复关卡排序、docs: 添加设计文档。请继续使用 feat:、fix:、perf:、docs: 前缀，首行聚焦单一变更。PR 需说明改动范围、影响页面或模块、验证方式；涉及 UI 请附截图或录屏，涉及微信环境差异请写明复现条件与平台。

# Memory Context

[mp-xieyingeng] recent context, 2026-06-01 11:37am GMT+8

Legend: 🎯session 🔴bugfix 🟣feature 🔄refactor ✅change 🔵discovery ⚖️decision 🚨security_alert 🔐security_note Format: ID TIME TYPE TITLE Fetch details: get_observations([IDs]) | Search: mem-search skill

Stats: 50 obs (15,736t read) | 2,461,717t work | 99% savings

Apr 26, 2026

S1309 移除 PageLevel.ts 进入关卡时弹出体力扣减 toast (Apr 26 at 5:16 PM)

Apr 27, 2026

S1308 移除进入游戏关卡时弹出体力扣减的 toast 提示 (Apr 27 at 9:21 AM) S1310 移除进入游戏体力扣减 toast 并在首页添加体力显示 (Apr 27 at 9:22 AM) S1311 移除体力扣减 toast 并完善首页体验 (Apr 27 at 9:23 AM) S1313 Implement object-fit: cover image scaling in Cocos Creator to prevent downloaded images from being distorted (Apr 27 at 9:26 AM) S1312 Fix image distortion in PageLevel.ts by implementing object-fit: cover behavior for downloaded images (Apr 27 at 9:45 AM) 1363 9:45a ✅ Start game button integrated with stamina check and animation flow 1364 " 🟣 Stamina consumption animation fully implemented in PageHome S1314 Implement stamina consumption animation in Cocos Creator game - when clicking StarGame button, IconLive node flies to button with floating "-1" text, then navigates to level (Apr 27 at 9:45 AM) 1365 9:46a 🔴 Animation completes but navigation to PageLevel fails S1315 为 PageLevel.ts 的 mainImage 和 mainImage2 节点实现 CSS cover 模式图片缩放 (Apr 27 at 9:46 AM) 1366 9:50a 🔴 Cocos Creator tween chain broken by premature node destroy 1367 9:55a 🔴 Navigation still failing after first tween chain fix - further debugging needed 1368 " 🔴 Decoupled fly animation from float text timing using setTimeout 1369 9:56a 🔴 Cocos Creator tween chain broken by any node state change mid-animation 1370 9:59a 🟣 CSS cover-style image scaling for PageLevel images 1371 10:01a ✅ PageLevel.ts imports extended for cover-style image scaling 1372 " 🟣 CSS cover-mode image scaling implemented for PageLevel images S1316 Debug cover mode image overflow in PageLevel.ts - image exceeds container bounds despite Mask applied (Apr 27 at 10:02 AM) 1373 10:02a 🔴 Cover mode image overflows container bounds 1374 10:06a 🔵 GRAPHICS_RECT vs GRAPHICS_STENCIL for Mask in Cocos Creator 1375 10:08a 🔴 Mask.Type.RECT does not exist in Cocos Creator API 1376 " 🔵 MaskType enum found in Cocos Creator 3.8 engine declarations 1378 " 🔵 MaskType enum values confirmed - GRAPHICS_RECT exists 1377 10:09a 🔵 MaskType enum definition found at line 46015 1379 10:10a 🔴 Reverted Mask.Type to GRAPHICS_RECT S1317 Implement CSS cover-mode image scaling for PageLevel.ts mainImage nodes (Apr 27 at 10:10 AM)

Apr 29, 2026

1481 6:33p 🟣 Implementing rounded corner images in PageLevel.ts 1482 " 🔵 RoundedRectMask component already exists for image corner rounding 1485 6:34p 🟣 Implemented rounded corners for PageLevel main images 1484 " 🔄 RoundedRectMask component improved with quality standards 1487 6:37p 🔵 TypeScript verification confirms no errors in new rounded corners implementation

May 12, 2026

1542 4:39p 🟣 CommonModal prefab adds conditional dual-button support 1543 " 🔵 CommonModal prefab contains both button node variants 1544 4:40p 🟣 CommonModal prefab upgraded with dual-button support 1545 4:41p 🟣 CommonModal prefab restructured with dual-button ActionDouble container 1546 " 🔵 BaseModal provides modal animation infrastructure 1547 4:43p 🟣 CommonModal.ts upgraded with dual-button support and backward compatibility 1548 4:44p 🟣 CommonModal dual-button implementation completed 1549 " ✅ CommonModal dual-button feature ready for testing 1550 4:45p 🟣 CommonModal dual-button feature completed and validated 1551 4:46p 🔄 CommonModal API refactoring: remove buttonHint, clean button logic 1552 4:47p 🔄 CommonModal dual-button refactor complete with cleaner API

May 14, 2026

1630 4:59p 🟣 PagePKDetail.prefab 新增参与人数标签节点 1631 " 🟣 PagePKDetail 新增参与人数标签

Jun 1, 2026

1771 11:07a 🔵 List Height Adaptation Issue on Different Resolution Phones in PageWriteLevels 1772 " 🔵 PageWriteLevels ScrollView Height Calculation Architecture Fully Mapped 1773 " 🔵 LevelList ScrollView Widget Has Only Top Alignment — View Node Has No Widget 1774 " 🔵 Root Cause Confirmed: VIEW_HEIGHT=1300 Floor Causes List Overflow on Short Phones 1775 11:13a 🔵 PageWriteLevels Prefab Structure Confirmed Clean 1777 " 🔄 _resizeScrollViewport Delegates Layout to Cocos Widget System 1776 11:14a 🔵 PageWriteLevels Prefab Contains 233 JSON Array Entries 1778 11:15a 🟣 PageWriteLevels ScrollView View Node Gets cc.Widget for Auto-Layout 1779 " 🔵 PageWriteLevels Layout Node Tree Verified After Widget Changes 1780 11:16a 🔵 TypeScript Check Requires Cocos Creator to Generate temp/declarations First 1781 " 🔵 New Widget Bottom Inset Produces Shorter Viewport on Small Screens vs Old Minimum 1783 " 🔵 PageWriteLevels Bottom Control Layout Constraints Mapped 1784 " ✅ ScrollView Widget Bottom Inset Revised from 559.076 to 752.53 1782 " 🔵 PageWriteLevels Prefab id Reference Integrity Confirmed Valid 1785 11:19a ✅ PageWriteLevels Widget Layout Refactor Complete — Final Diff Confirmed

Access 2462k tokens of past work via get_observations([IDs]) or mem-search skill.

15 KiB Raw Blame History Unescape Escape