tanqiu/assets/scripts/LevelSystem/LevelManagerSetupGuide.md

LevelManager 使用指南

📋 重要说明

LevelManager 已经改为纯 TypeScript 类，不需要挂载到任何节点上！

🔧 设计原理

为什么不继承 Component？

1. 数据管理器性质: LevelManager 主要负责关卡数据的存储和管理，不需要节点生命周期
2. 全局访问: 作为单例模式，应该在任何地方都能访问，不依赖特定节点
3. 性能考虑: 避免不必要的 Component 开销
4. 场景切换: 纯类不会因为场景切换而被销毁，数据更加稳定

单例模式优势

• ✅ 全局唯一实例
• ✅ 自动初始化
• ✅ 数据持久化
• ✅ 内存占用小

🚀 使用方法

在代码中使用

// 获取 LevelManager 实例（自动初始化）
const levelManager = LevelManager.getInstance();

// 获取当前关卡
const currentLevel = levelManager.getCurrentLevel();

// 完成关卡
levelManager.completeLevel(1, 1000, 3);

// 检查关卡是否解锁
const isUnlocked = levelManager.isLevelUnlocked(2);

GameManager 中的集成

GameManager 已经正确集成了 LevelManager：

// 在 initializeManagers() 中
this.levelManager = LevelManager.getInstance();

// 使用示例
if (this.levelManager) {
    const currentLevel = this.levelManager.getCurrentLevel();
    this.levelManager.completeLevel(currentLevel, score, stars);
}

🏗️ 项目结构建议

推荐的节点结构

Canvas
├── GameLevelUI
│   ├── GameManager (挂载 GameManager 组件)
│   ├── LevelConfigManager (挂载 LevelConfigManager 组件)
│   └── ... (其他游戏UI)
└── ... (其他Canvas子节点)

各组件职责

• GameManager: 游戏状态管理、UI控制、系统协调
• LevelConfigManager: 关卡配置文件管理（需要挂载）
• LevelManager: 关卡进度数据管理（纯类，不挂载）

📝 配置步骤

1. 不需要创建 LevelManager 节点

❌ 不要创建 LevelManager 节点 ❌ 不要添加 LevelManager 组件

2. 确保 GameManager 正确配置

在 GameManager 节点上：

1. 添加 GameManager 组件
2. 配置相关属性（血量显示节点、UI节点等）
3. LevelManager 会自动通过 getInstance() 初始化

3. 验证初始化

在控制台中检查：

// 检查 LevelManager 是否正常工作
const levelManager = window.LevelManager?.getInstance();
if (levelManager) {
    console.log('当前关卡:', levelManager.getCurrentLevel());
    console.log('最大解锁关卡:', levelManager.getMaxUnlockedLevel());
} else {
    console.error('LevelManager 未正确初始化');
}

🔍 调试方法

控制台命令

// 获取 LevelManager 实例
const lm = LevelManager.getInstance();

// 查看当前状态
console.log('当前关卡:', lm.getCurrentLevel());
console.log('最大解锁关卡:', lm.getMaxUnlockedLevel());

// 解锁所有关卡（调试用）
lm.unlockAllLevels(10);

// 重置所有进度
lm.resetAllProgress();

// 完成当前关卡
lm.completeLevel(lm.getCurrentLevel(), 1000, 3);

⚠️ 注意事项

1. 不要手动创建实例: 始终使用 LevelManager.getInstance()
2. 数据持久化: 关卡数据自动保存到 localStorage
3. 初始化时机: 首次调用 getInstance() 时自动初始化
4. 场景切换: 数据在场景切换时保持不变
5. 错误处理: 包含完整的数据加载和保存错误处理

🆚 与其他管理器的区别

管理器	类型	是否挂载	主要用途
LevelManager	纯类	❌ 不挂载	关卡进度数据管理
LevelConfigManager	Component	✅ 需挂载	关卡配置文件管理
GameManager	Component	✅ 需挂载	游戏状态和UI管理
ConfigManager	纯类	❌ 不挂载	游戏配置数据管理
ShopManager	纯类	❌ 不挂载	商店数据管理

🎯 最佳实践

1. 在 GameManager 中初始化: 通过 GameManager 统一管理所有系统
2. 数据访问: 需要关卡数据时，直接调用 LevelManager.getInstance()
3. 错误处理: 始终检查返回值，处理可能的 null 情况
4. 性能优化: LevelManager 是轻量级的，可以频繁调用
5. 调试友好: 提供了完整的调试方法和日志输出

这种设计使得 LevelManager 更加简洁、高效，并且易于维护！