# 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 描述。

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


<claude-mem-context>
# Memory Context

# [mp-xieyingeng] recent context, 2026-04-29 6:32pm 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 (9,755t read) | 1,857,754t work | 99% savings

### Apr 26, 2026
1330 4:45p 🔄 API Protocol Upgrade - NextLevel-Driven Architecture
1331 " ✅ ApiTypes.ts type definitions updated
1332 " ✅ Task 4 completed: ApiTypes.ts type definitions updated
1333 4:46p ✅ Tasks 4 and 5 completed: type definitions migrated
1334 5:10p 🔵 进度条小百分比时圆角畸形问题
1335 " 🔵 进度条圆角畸形问题调查中
1336 " 🔵 通关弹窗进度条使用 Cocos ProgressBar 组件
1337 5:11p 🔵 进度条圆角畸形调查中 - Prefab 结构检查
1338 " 🔵 ProgressBar 系统架构已定位
1340 " 🔵 找到进度条圆角畸形根本原因
1341 5:12p 🔵 进度条小百分比时圆角变形问题定位
1339 " 🔵 发现 RoundedRectMask 工具组件
S1309 移除 PageLevel.ts 进入关卡时弹出体力扣减 toast (Apr 26 at 5:16 PM)
1342 5:16p 🔵 PassModal 进度值规范化逻辑
1343 5:17p 🔴 进度条圆角畸形问题已修复
1344 " ⚖️ 探索使用 Mask 裁剪替代最小进度值方案
1345 " ⚖️ 否决 Mask 方案，确认最小进度值方案最优
### Apr 27, 2026
1346 9:21a 🔴 移除进入游戏后的体力扣减 toast 提示
1347 " 🔴 移除进入游戏后的体力扣减 toast 提示
1348 " 🟣 首页添加体力值显示功能
S1308 移除进入游戏关卡时弹出体力扣减的 toast 提示 (Apr 27 at 9:21 AM)
S1310 移除进入游戏体力扣减 toast 并在首页添加体力显示 (Apr 27 at 9:22 AM)
S1311 移除体力扣减 toast 并完善首页体验 (Apr 27 at 9:23 AM)
1349 9:25a ✅ PageHome.ts 添加 ToastManager 导入
1350 " ✅ PK按钮点击改为提示"功能开发中"
S1313 Implement object-fit: cover image scaling in Cocos Creator to prevent downloaded images from being distorted (Apr 27 at 9:26 AM)
1351 9:32a 🟣 Stamina animation system for level entry
1352 " 🔵 Cocos Creator game project structure discovered
1354 " 🟣 StarGame 按钮点击动画需求
1356 " 🔵 体力系统架构发现
1353 9:33a 🔵 StaminaManager API confirmed for stamina operations
1355 9:37a 🔵 项目结构和现有代码发现
1357 9:38a 🔵 EnterLevelData 结构分析
1359 9:39a 🟣 Stamina animation system implemented for game entry flow
1358 9:41a ⚖️ 体力值飞行动画实现计划制定完成
1362 9:45a 🟣 Image Cover Mode Scaling in Cocos Creator
S1312 Fix image distortion in PageLevel.ts by implementing object-fit: cover behavior for downloaded images (Apr 27 at 9:45 AM)
1360 " ✅ Cocos Creator animation imports added to PageHome.ts
1361 " ✅ Animation constants added to PageHome class
1363 " ✅ 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)
**Investigated**: Cover mode implementation in _applyCoverSprite() using Mask + scaled child node approach; Cocos Creator 3.8 MaskType enum investigation; root cause analysis of image overflow

**Learned**: Cocos Creator Mask only clips child nodes, NOT the container's own Sprite component; GRAPHICS_RECT = 0 is valid enum value in Cocos 3.8; container Sprite renders outside Mask bounds; solution: disable containerSprite and use child node for image display

**Completed**: _applyCoverSprite() method implemented with: Mask(GRAPHICS_RECT) on container, child node '_coverImg' with Sprite.SizeMode.RAW, cover scale calculation, containerSprite.enabled = false to prevent overflow

**Next Steps**: User to test in Cocos Creator editor to verify image clipping now works correctly


Access 1858k tokens of past work via get_observations([IDs]) or mem-search skill.
</claude-mem-context>