CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

这是一个 Cocos Creator 3.8.8 项目，用于开发小游戏/可玩广告。

Project Structure

assets/
├── main.ts              # 主入口脚本
├── main.scene           # 主场景
├── PageLoading.ts       # 页面加载组件
├── PageLoading.prefab   # 预制体
├── scripts/
│   └── utils/
│       └── BackgroundScaler.ts  # 背景缩放工具组件
└── resources/
    └── images/          # 图片资源

Development Commands

此项目使用 Cocos Creator 编辑器进行开发：

打开项目: 使用 Cocos Creator 3.8.8 打开此目录
运行预览: 在 Cocos Creator 编辑器中点击 "Play" 按钮
构建: 使用编辑器菜单 Project > Build 或快捷键 Cmd+B

Editor Operations (强制约定)

凡是涉及 prefab、scene、node、component 或 Cocos 编辑器内的任何操作，必须使用 cocos-creator MCP，不要手工编辑 .prefab / .scene 的 YAML/JSON 文件。

适用范围（非穷举）：

创建 / 修改 / 删除 prefab：mcp__cocos-creator__prefab_*
场景增删改、打开/保存场景：mcp__cocos-creator__scene_*
节点结构（增删、移动、改 transform、改属性）：mcp__cocos-creator__node_*
组件挂载、属性赋值、引用绑定（Sprite/Label/Button/自定义脚本等）：mcp__cocos-creator__component_*
资源管理（导入、查询 UUID、刷新、引用校验）：mcp__cocos-creator__project_* / mcp__cocos-creator__assetAdvanced_*
场景脚本执行、调试日志、性能数据：mcp__cocos-creator__debug_* / mcp__cocos-creator__sceneAdvanced_*

允许直接编辑的文件仍是：.ts 脚本源代码（assets/**/*.ts）、纯文本配置（tsconfig.json、package.json 等）。.prefab / .scene / .meta 一律走 MCP，避免 UUID 错位、引用丢失、序列化格式被破坏。

操作前先用 scene_get_current_scene / node_get_all_nodes / prefab_get_prefab_info 等查询类工具确认当前编辑器状态，不要凭记忆操作。

TypeScript Coding

遵循 Cocos Creator 3.x 组件系统架构：

使用 @ccclass 装饰器声明组件
继承 cc.Component 基类
生命周期方法: onLoad -> start -> update -> onDestroy
使用 cc. 命名空间访问引擎 API（如 cc.view, cc.Node, cc.Component 等）

当前项目里的好友分享挑战链路不是普通闯关的变体，而是一条单独的模式切换链路。

发起入口在首页 PageHome 的 PK 按钮，点击后进入 PageWriteLevels 进行选题，而不是从普通关卡页直接发起。assets/prefabs/PageHome.ts
PageWriteLevels 只允许从当前用户“已通关关卡”中选题，数据来自 CompletedLevelsManager.fetch()；当前产品规则要求必须选满 6 关。assets/prefabs/PageWriteLevels.ts assets/prefabs/PageWriteLevels.ts
预览只是本地页面跳转：PageWriteLevels 把 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，好友侧是靠这个码重新拉题单。assets/prefabs/PageWriteLevels.ts assets/scripts/utils/ShareManager.ts
好友从微信卡片打开小游戏时，启动页 PageLoading 会从 WxSDK.getShareCodeFromLaunch() 读取启动参数；只要拿到 shareCode 且登录成功，就会调用 ShareManager.joinShare(code)，然后跳过首页，直接以 shareMode=true 打开 PageLevel。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 进入分享模式后，当前题数据直接来自 ShareManager.ensureShareLevelReady(index)，不会调用 StaminaManager.enterLevel()，因此分享挑战不消耗体力，也不依赖 enter 接口补答案和提示。assets/prefabs/PageLevel.ts assets/prefabs/PageLevel.ts
作答判定仍在 PageLevel.onSubmitAnswer() 本地完成，本质就是把用户输入和 config.answer 做字符串比较；答对后显示通关链路并切到下一题，答错则弹错误弹窗。assets/prefabs/PageLevel.ts
分享模式下只有答对时会调用 ShareManager.reportLevelProgress(levelId, true, timeSpent) 上报 POST /share/progress。当前没有把答错或超时作为失败事件上报，所以服务端拿到的是“成功进度”，不是完整挑战行为流。assets/prefabs/PageLevel.ts assets/scripts/utils/ShareManager.ts
分享模式下切下一题只会 _shareLevelIndex++；全部做完后清空分享态并回首页。超时弹窗点回首页时也会先清理分享态，避免脏状态残留。assets/prefabs/PageLevel.ts assets/prefabs/PageLevel.ts

Current Gaps

分享模式标题展示的是分享内序号 第 1 关 / 第 2 关，不是题库真实关卡号。assets/prefabs/PageLevel.ts
PassModal 和 TimeoutModal 内部的分享按钮发的是普通 level=... query，不是好友挑战 shareCode，所以它们目前不属于这条好友分享挑战链路。assets/prefabs/PassModal.ts assets/prefabs/TimeoutModal.ts
ShareManager.joinShare() 当前没有把后端题目的 timeLimit 写入 RuntimeLevelConfig，而 PageLevel 会用 config.timeLimit ?? 60 兜底，因此分享题默认统一 60 秒。assets/scripts/utils/ShareManager.ts assets/prefabs/PageLevel.ts
选题页和预览页通过 selectedIndices 对同一份 completed list 建立映射，若列表在页面间发生刷新或顺序变化，存在按索引错位的风险；更稳妥的传参应该是 levelIds 或完整快照。assets/prefabs/PageWriteLevels.ts assets/prefabs/PagePreviewLevels.ts

9.1 KiB Raw Blame History Unescape Escape