# 游戏存档系统使用说明

## 概述

本存档系统为Pong游戏提供完整的玩家进度保存和管理功能，记录玩家的关卡进度、货币、道具、统计数据等信息。

## 主要功能

### 1. 玩家数据管理
- **基本信息**：玩家ID、姓名、创建时间、游戏时长等
- **等级系统**：玩家等级、经验值、升级奖励
- **货币系统**：金币、钻石、宝石的获得和消费
- **关卡进度**：当前关卡、最高解锁关卡、各关卡完成情况

### 2. 关卡进度记录
- 关卡完成状态
- 最佳得分和用时
- 星级评价
- 尝试次数
- 首次通关时间

### 3. 道具和装备系统
- 武器收集和升级
- 道具背包管理
- 材料存储

### 4. 统计数据
- 游戏次数、胜负记录
- 总得分、击败敌人数量
- 游戏时长、连胜记录等

### 5. 设置管理
- 音效、音乐设置
- 画质、语言设置
- 自动保存等功能设置

## 使用方法

### 基本使用

```typescript
// 获取存档管理器实例
const saveManager = SaveDataManager.getInstance();
saveManager.initialize();

// 获取墙体等级
const wallLevel = saveManager.getWallLevel();
const currentLevel = saveManager.getCurrentLevel();
const coins = saveManager.getMoney();

// 完成关卡
saveManager.completeLevel(levelId, score, time, stars);

// 添加货币
saveManager.addMoney(amount, 'level_complete');
saveManager.addDiamonds(amount, 'daily_reward');
```

### 在GameManager中集成

```typescript
// 在GameManager中初始化
private saveDataManager: SaveDataManager = null;

start() {
    this.saveDataManager = SaveDataManager.getInstance();
    this.saveDataManager.initialize();
}

// 游戏成功时
private onGameSuccess() {
    const currentLevel = this.saveDataManager.getCurrentLevel();
    const score = this.calculateScore();
    const time = this.getGameDuration();
    const stars = this.calculateStars();
    
    this.saveDataManager.completeLevel(currentLevel, score, time, stars);
}

// 游戏失败时
private onGameDefeat() {
    const currentLevel = this.saveDataManager.getCurrentLevel();
    this.saveDataManager.failLevel(currentLevel);
}
```

### 在主界面显示玩家信息

```typescript
// 在MainUIController中使用
export class MainUIController extends Component {
    private saveDataManager: SaveDataManager = null;
    
    start() {
        this.saveDataManager = SaveDataManager.getInstance();
        this.saveDataManager.initialize();
        this.updateUI();
    }
    
    updateUI() {
        // 更新墙体等级显示
        const wallLevel = this.saveDataManager.getWallLevel();
        this.wallLevelLabel.string = `墙体等级: ${wallLevel}`;
        
        // 更新货币显示
        const coins = this.saveDataManager.getMoney();
        this.coinsLabel.string = coins.toString();
    }
}
```

## 数据结构

### PlayerData
```typescript
interface PlayerData {
    // 基本信息
    playerId: string;
    playerName: string;
    createTime: number;
    lastPlayTime: number;
    totalPlayTime: number;
    
    // 墙体等级
    wallLevel: number;
    
    // 货币系统
    coins: number;
    diamonds: number;
    
    // 关卡进度
    currentLevel: number;
    maxUnlockedLevel: number;
    levelProgress: { [levelId: number]: LevelProgress };
    
    // 道具和装备
    inventory: InventoryData;
    
    // 统计数据
    statistics: GameStatistics;
    
    // 设置
    settings: PlayerSettings;
}
```

### LevelProgress
```typescript
interface LevelProgress {
    levelId: number;
    completed: boolean;
    bestScore: number;
    bestTime: number;
    attempts: number;
    firstClearTime: number;
    lastPlayTime: number;
    rewards: RewardData[];
}
```

## API参考

### 基本信息获取
- `getWallLevel()`: 获取墙体等级
- `getCurrentLevel()`: 获取当前关卡
- `getMaxUnlockedLevel()`: 获取最高解锁关卡
- `getCoins()`: 获取金币数量
- `getDiamonds()`: 获取钻石数量

### 关卡管理
- `completeLevel(levelId, score, time)`: 完成关卡
- `failLevel(levelId)`: 关卡失败
- `getLevelProgress(levelId)`: 获取关卡进度
- `isLevelUnlocked(levelId)`: 检查关卡是否解锁
- `isLevelCompleted(levelId)`: 检查关卡是否完成

### 货币管理
- `addCoins(amount, source)`: 添加金币
- `spendCoins(amount)`: 消费金币
- `addDiamonds(amount, source)`: 添加钻石
- `spendDiamonds(amount)`: 消费钻石

### 墙体等级管理
- `upgradeWallLevel()`: 升级墙体等级
- `getWallUpgradeCost()`: 获取墙体升级费用
- `canUpgradeWall()`: 检查是否可以升级墙体
- 墙体升级只提升血量，不提供奖励

### 道具管理
- `addWeapon(weaponId, rarity)`: 添加武器
- `addItem(itemId, count)`: 添加道具
- `useItem(itemId, count)`: 使用道具

### 数据保存和加载
- `savePlayerData(force)`: 保存玩家数据
- `checkAutoSave()`: 检查自动保存
- `resetAllData()`: 重置所有数据
- `exportSaveData()`: 导出存档数据
- `importSaveData(dataString)`: 导入存档数据

### 设置管理
- `updateSetting(key, value)`: 更新设置
- `getSetting(key)`: 获取设置值

## 游戏流程集成

### 1. 游戏启动
```typescript
// 在游戏启动时初始化存档系统
const saveManager = SaveDataManager.getInstance();
saveManager.initialize();
```

### 2. 主界面显示
```typescript
// 显示玩家信息
const wallLevel = saveManager.getWallLevel();
const currentLevel = saveManager.getCurrentLevel();
const coins = saveManager.getMoney();
```

### 3. 进入关卡
```typescript
// 获取当前关卡信息
const currentLevel = saveManager.getCurrentLevel();
const isUnlocked = saveManager.isLevelUnlocked(currentLevel);
```

### 4. 游戏进行中
```typescript
// 记录游戏统计数据
saveManager.updateStatistic('totalShotsfired', 1);
saveManager.updateStatistic('totalEnemiesDefeated', 1);
```

### 5. 关卡完成
```typescript
// 记录关卡完成
const score = calculateScore();
const time = getGameDuration();
saveManager.completeLevel(currentLevel, score, time);

// 给予奖励
saveManager.addMoney(baseReward, 'level_complete');
```

### 6. 关卡失败
```typescript
// 记录关卡失败
saveManager.failLevel(currentLevel);
```

### 7. 返回主界面
```typescript
// 保存数据
saveManager.savePlayerData(true);
```

## 注意事项

1. **单例模式**：SaveDataManager使用单例模式，确保全局只有一个实例
2. **自动保存**：系统会定期自动保存，避免频繁的手动保存
3. **数据备份**：系统会自动创建备份，防止数据丢失
4. **版本兼容**：支持数据结构的版本迁移和兼容
5. **错误处理**：包含完整的错误处理和恢复机制

## 调试功能

系统提供了多个调试方法：
- `getSaveSummary()`: 获取存档摘要信息
- `exportSaveData()`: 导出存档数据用于调试
- `resetAllData()`: 重置所有数据用于测试

## 扩展性

系统设计具有良好的扩展性，可以轻松添加：
- 新的货币类型
- 更多的统计数据
- 额外的玩家设置
- 新的道具和装备类型

通过修改相应的接口定义即可扩展功能，无需大幅修改现有代码。