richard/mp-xieyingeng

Fork 0

Files

richarjiang 447e7a944a feat: 支持分享关卡通关上报

2026-04-08 21:34:36 +08:00

11 KiB

Raw Blame History

mp-xieyingeng 项目完整探索报告

📋 项目概述

项目名称: 写英语谐音梗小游戏 (mp-xieyingeng) 引擎: Cocos Creator 3.x (TypeScript) 平台: 微信小游戏架构: 分布式页面管理系统 + 单例工具类

📁 完整目录结构

assets/
├── main.ts                                      # 主入口脚本，初始化 ViewManager
├── PageLoading.ts                               # 加载页面，处理登录、资源预加载、分享码检测
├── prefabs/                                     # 页面预制体和组件
│   ├── PageHome.ts                             # 首页
│   ├── PageLevel.ts                            # 关卡页面（核心游戏逻辑）
│   ├── PageWriteLevels.ts                      # 写关卡页面（创建/编辑关卡）
│   ├── PagePreviewLevels.ts                    # 预览关卡页面
│   ├── PagePKData.ts                           # 挑战数据页面
│   ├── PagePKDetail.ts                         # 挑战详情页面
│   ├── PassModal.ts                            # 通关弹窗
│   └── Toast.ts                                # Toast 提示组件
├── scripts/
│   ├── config/
│   │   └── ApiConfig.ts                        # API 配置（端点、超时时间等）
│   ├── core/
│   │   ├── BaseView.ts                         # 页面基类（生命周期管理）
│   │   └── ViewManager.ts                      # 页面管理器（单例，栈管理）
│   ├── types/
│   │   ├── LevelTypes.ts                       # 关卡数据类型定义
│   │   └── ApiTypes.ts                         # API 响应类型定义
│   └── utils/                                  # 工具类（单例）
│       ├── HttpUtil.ts                         # HTTP 请求工具（GET/POST + JWT 认证）
│       ├── ShareManager.ts                     # 分享管理器（创建分享、加入分享）
│       ├── LevelDataManager.ts                 # 关卡数据管理器（API 拉取、缓存、图片加载）
│       ├── UserAssetsManager.ts                # 用户资产管理器（积分同步）
│       ├── AuthManager.ts                      # 认证管理器（微信登录、Token 管理）
│       ├── StorageManager.ts                   # 本地存储管理器（进度、积分、Token）
│       ├── WxSDK.ts                            # 微信 SDK 封装（登录、分享、震动等）
│       ├── ToastManager.ts                     # Toast 管理器
│       └── [其他工具类...]
└── resources/                                  # 游戏资源
    ├── audios/                                # 音效文件
    ├── images/
    │   ├── level/                             # 关卡图片
    │   ├── pageHome/                          # 首页图片
    │   ├── pageLevel/                         # 关卡页面图片
    │   └── pageLoading/                       # 加载页面图片

🎯 所有 TypeScript 文件列表

核心入口

assets/main.ts - 主脚本，注册所有页面到 ViewManager
assets/PageLoading.ts - 加载页面，并行执行登录 + 资源加载

页面组件（每个继承 BaseView）

assets/prefabs/PageHome.ts - 首页
assets/prefabs/PageLevel.ts - 核心游戏逻辑
assets/prefabs/PageWriteLevels.ts - 写关卡
assets/prefabs/PagePreviewLevels.ts - 预览关卡
assets/prefabs/PagePKData.ts - PK 数据展示
assets/prefabs/PagePKDetail.ts - PK 详情
assets/prefabs/PassModal.ts - 通关弹窗
assets/prefabs/Toast.ts - Toast 提示

核心框架

assets/scripts/core/BaseView.ts - 页面基类（onViewLoad、onViewShow、onViewHide、onViewDestroy）
assets/scripts/core/ViewManager.ts - 页面管理器（栈管理、缓存、生命周期调用）

配置

assets/scripts/config/ApiConfig.ts - API 端点 + 超时配置

类型定义

assets/scripts/types/ApiTypes.ts - API 响应类型
assets/scripts/types/LevelTypes.ts - 关卡数据类型

工具类（单例）

assets/scripts/utils/HttpUtil.ts - HTTP 请求（GET/POST + JWT）
assets/scripts/utils/ShareManager.ts - 分享系统
assets/scripts/utils/LevelDataManager.ts - 关卡数据管理
assets/scripts/utils/UserAssetsManager.ts - 积分管理
assets/scripts/utils/AuthManager.ts - 认证 + 登录
assets/scripts/utils/StorageManager.ts - 本地存储
assets/scripts/utils/WxSDK.ts - 微信 SDK 封装
assets/scripts/utils/ToastManager.ts - Toast 管理
其他：RoundedRectMask、BackgroundScaler 等

💾 关卡通关逻辑核心

1. 通关判定（PageLevel.ts 第 660-673 行）

onSubmitAnswer(): void {
    const userAnswer = this.getAnswer();
    if (userAnswer === this._currentConfig.answer) {
        this.showSuccess();
    } else {
        this.showError();
    }
}

2. 通关奖励（PageLevel.ts 第 679-701 行）

private async showSuccess(): Promise<void> {
    // 停止倒计时
    this.stopCountdown();
    
    // 非分享模式才增加积分
    if (!this._isShareMode) {
        const levelId = this._currentConfig?.id;
        const timeSpent = 60 - this._countdown;
        await UserAssetsManager.instance.earnPoint(levelId, timeSpent);
    }
    
    // 显示通关弹窗
    this._showPassModal();
}

3. 进度保存（PageLevel.ts 第 785-816 行）

private async nextLevel(): Promise<void> {
    // 非分享模式才保存进度
    if (!this._isShareMode) {
        StorageManager.onLevelCompleted(this.currentLevelIndex);
    }
    
    this.currentLevelIndex++;
    
    // 检查是否全部通关
    const totalLevels = this._isShareMode
        ? ShareManager.instance.getShareLevelCount()
        : LevelDataManager.instance.getLevelCount();
    
    if (this.currentLevelIndex >= totalLevels) {
        // 全部通关，返回首页
        ViewManager.instance.back();
    } else {
        // 加载下一关
        await this.initLevel();
        this.startCountdown();
    }
}

4. 已通关关卡同步（PageLoading.ts 第 115-139 行）

private _syncProgressFromServer(): void {
    // 服务端返回的已通关关卡 ID
    const completedIds = AuthManager.instance.completedLevelIds;
    
    // 转换为本地索引
    const maxCompletedIndex = LevelDataManager.instance.getMaxCompletedIndex(completedIds);
    
    // 取较大值，防止进度回退
    if (maxCompletedIndex > localMax) {
        StorageManager.onLevelCompleted(maxCompletedIndex);
    }
}

🔗 API 端点一览

已配置的 API（ApiConfig.ts）

API_BASE = 'https://ilookai.cn/api/v1'

端点：
- POST   /auth/wx-login                    # 微信登录
- GET    /user/assets                      # 获取用户积分
- POST   /user/assets/consume              # 消耗积分（解锁线索）
- POST   /user/assets/earn                 # 获得积分（通关奖励）
- GET    /user/game-data                   # 获取用户数据（进度 + 积分）
- GET    /wechat-game/levels                # 获取所有关卡
- POST   /share                            # 创建分享
- POST   /share/{code}/join                # 加入分享
- GET    /user/info                        # 获取用户信息

🏗️ 架构特点

1. 单例模式

ViewManager - 页面管理
LevelDataManager - 关卡数据
ShareManager - 分享管理
UserAssetsManager - 积分管理
AuthManager - 认证
StorageManager - 本地存储（全静态）
ToastManager - Toast 管理
WxSDK - 微信 SDK（全静态）
HttpUtil - HTTP 工具（全静态）

2. 页面栈管理

ViewManager 维护页面栈
open() - 打开页面，压栈
back() - 返回上一页，出栈
replace() - 替换当前页，不压栈

3. 生命周期

每个页面 4 个阶段：

onViewLoad() - 首次创建时调用
onViewShow() - 每次显示时调用
onViewHide() - 隐藏时调用
onViewDestroy() - 销毁时调用

🎯 关键发现

✅ 已有的工具类

HTTP 请求

HttpUtil.ts - GET/POST + JWT 认证
- 支持自定义超时时间
- 自动添加 Authorization 头
- 泛型支持

数据管理

LevelDataManager.ts - 关卡数据 + 图片缓存
- API 请求重试机制
- 图片懒加载（预加载下一关）
- URL -> SpriteFrame 缓存
UserAssetsManager.ts - 积分管理
- 消耗积分（解锁线索）
- 获得积分（通关奖励）
- 自动降级本地处理
AuthManager.ts - 认证 + 登录
- 微信登录流程
- Token 恢复与验证
- 获取通关进度
StorageManager.ts - 本地存储
- 积分、Token、进度、用户信息
- 全静态工具类

游戏逻辑

ShareManager.ts - 分享系统
- 创建分享、加入分享
- 独立数据管理，不影响正常进度
ViewManager.ts - 页面管理
- 栈管理
- 缓存机制
- 生命周期管理
WxSDK.ts - 微信 API 封装
- 登录、分享、震动
- 隐私授权、用户信息
- 非微信环境自动降级

📊 游戏流程图

正常模式

启动 → PageLoading
  ├─ 并行加载：登录 + 关卡数据
  ├─ 检测分享码（无）
  └─ 打开 PageHome
     ├─ 开始游戏 → PageLevel
     │   ├─ 加载关卡
     │   ├─ 倒计时 60s
     │   ├─ 提交答案
     │   ├─ 判定成功/失败
     │   ├─ 通关 → PassModal
     │   │   ├─ earnPoint()（加积分）
     │   │   ├─ onLevelCompleted()（保存进度）
     │   │   └─ nextLevel()
     │   └─ 重复 2-7
     └─ PK → PageWriteLevels

分享模式

微信分享链接（含 shareCode）
  ↓
PageLoading
  ├─ 检测到分享码
  └─ ShareManager.joinShare(code)
     ↓
  PageLevel（shareMode=true）
  ├─ 从 ShareManager 加载关卡
  ├─ 不增加积分
  ├─ 不保存本地进度
  └─ 全部通关 → 返回首页

💡 核心要点

HTTP 工具 ✅
- HttpUtil.ts 已完整实现
- 支持 JWT 认证
- 可配置超时
关卡数据 ✅
- LevelDataManager 从 API 拉取
- 支持图片缓存 + 懒加载
- 支持重试机制
通关逻辑 ✅
- 判定：字符串比对（PageLevel.ts:660）
- 奖励：earnPoint()（PageLevel.ts:679）
- 进度：StorageManager.onLevelCompleted()（PageLevel.ts:785）
- 服务端同步：PageLoading.ts:115
分享系统 ✅
- 创建 + 加入完全独立
- 不影响正常游戏进度
- 懒加载关卡数据
页面管理 ✅
- ViewManager 栈管理
- 4 个生命周期回调
- 缓存机制
认证系统 ✅
- 微信登录 + Token 恢复
- 自动添加授权头
- 获取用户通关记录
本地存储 ✅
- StorageManager 集中管理
- 支持进度 + 积分 + Token
- 带有默认值和数据校验
微信 API ✅
- WxSDK 完整封装
- 非微信环境自动降级
- 支持分享、登录、震动等

11 KiB Raw Blame History Unescape Escape

mp-xieyingeng 项目完整探索报告

📋 项目概述

📁 完整目录结构

🎯 所有 TypeScript 文件列表

核心入口

页面组件（每个继承 BaseView）

核心框架

配置

类型定义

工具类（单例）

💾 关卡通关逻辑核心

1. 通关判定（PageLevel.ts 第 660-673 行）

2. 通关奖励（PageLevel.ts 第 679-701 行）

3. 进度保存（PageLevel.ts 第 785-816 行）

4. 已通关关卡同步（PageLoading.ts 第 115-139 行）

🔗 API 端点一览

已配置的 API（ApiConfig.ts）

🏗️ 架构特点

1. 单例模式

2. 页面栈管理

3. 生命周期

🎯 关键发现

✅ 已有的工具类

HTTP 请求

数据管理

游戏逻辑

📊 游戏流程图

正常模式

分享模式

💡 核心要点

11 KiB

Raw Blame History