﻿﻿﻿# 玩家变身次数限制使用说明

## 功能概述

每个SubLevel（TileMap）都有独立的变身次数限制。当玩家切换到新的TileMap时，会自动获得该TileMap配置的变身次数。玩家在当前TileMap内切换鸟类形态时会消耗变身次数，次数用完后将无法再变身。

**核心机制**：
- 每个TileMap在LevelGMBase中配置其最大变身次数
- 玩家切换到新TileMap时，自动重置为该TileMap的最大变身次数
- 玩家在同一个TileMap内变身时消耗次数
- PlayerState持有当前的剩余次数，但由LevelGMBase根据TileMap来设置

## 策划配置

### 1. 在LevelGMBase中配置TileMap变身次数

在GameMode的Details面板中，找到`00_LevelManage`分类：

- **TileMapTransformLimits**: TileMap变身次数配置数组
  - 每个元素包含：
    - `TileMapTag`: TileMap的标签名称（必须与场景中的TileMap标签匹配）
    - `MaxTransformCount`: 该TileMap的最大变身次数
      - `-1`: 无限次变身（默认值）
      - `0`: 无法变身（特殊情况）
      - `> 0`: 具体的可变身次数

### 2. 配置示例

在LevelGMBase蓝图的Details面板中：

```
TileMapTransformLimits:
  [0]
    TileMapTag: SubLevel_Tutorial     // 教学关卡
    MaxTransformCount: -1              // 无限次，让玩家熟悉
  [1]
    TileMapTag: SubLevel_Normal1       // 普通关卡1
    MaxTransformCount: 5               // 5次变身机会
  [2]
    TileMapTag: SubLevel_Hard1         // 困难关卡1
    MaxTransformCount: 3               // 只有3次变身机会
  [3]
    TileMapTag: SubLevel_Puzzle1       // 解谜关卡1
    MaxTransformCount: 4               // 精确配置次数
```

## 工作流程

### 自动次数管理

1. **游戏开始时**：
   - LevelGMBase在BeginPlay时设置初始TileMap
   - 自动调用`UpdatePlayerTransformCount`
   - PlayerState获得该TileMap配置的变身次数

2. **切换TileMap时**：
   - 调用`ChangeSubLevel`或`ChangeSubLevelByName`
   - 自动调用`UpdatePlayerTransformCount`
   - PlayerState的变身次数重置为新TileMap配置的次数

3. **玩家变身时**：
   - 调用PlayerState的`SwitchAbility`
   - 检查`CanTransform()`是否返回true
   - 如果次数为0，拒绝变身
   - 如果有次数，执行变身并减少次数

### 日志输出

系统会输出详细的日志：

```
LogTemp: Switched to TileMap 'SubLevel_Normal1': 5 transform(s) available.
LogTemp: Transform count decreased. Remaining: 4
LogTemp: Warning: Cannot transform - no remaining transform count (0/0)
```

## 蓝图接口

### 1. LevelGMBase接口（配置和查询）

#### GetCurrentTransformCount
```
在LevelGMBase中调用
输出: int32 - 当前TileMap的剩余变身次数（-1表示无限次）
```
获取玩家当前的剩余变身次数。

#### GetTileMapMaxTransformCount
```
在LevelGMBase中调用
输入: TileMapName (Name) - TileMap的标签名称
输出: int32 - 该TileMap配置的最大变身次数（-1表示无限次）
```
查询指定TileMap配置的最大变身次数。

### 2. PlayerState接口（查询和操作）

#### GetRemainingTransformCount
```
在HeronPlayerState中调用
输出: int32 - 剩余变身次数（-1表示无限次）
```
获取当前剩余的变身次数。

#### CanTransform
```
在HeronPlayerState中调用
输出: bool - 是否还能变身
```
检查是否还能进行变身。返回true表示可以变身（剩余次数>0或=-1）。

#### AddTransformCount
```
在HeronPlayerState中调用
输入: Count (int32) - 要增加的次数
```
增加变身次数。可用于：
- 拾取道具增加变身次数
- 完成任务奖励
- 特殊事件

**注意**: 如果当前是无限次（-1），此方法不会生效。

#### SwitchAbility
```
在HeronPlayerState中调用
输入: NewAbilityType (EBirdType) - 要切换到的鸟类型
```
切换到指定的鸟类形态。此方法会：
1. 检查是否还有剩余变身次数
2. 如果次数为0，拒绝变身并输出警告
3. 如果有次数，执行变身并将次数减1
4. 如果是无限次（-1），直接变身不消耗次数

## 工作流程

### 1. 自动次数管理

当调用`SwitchAbility`时：

1. 检查 `CanTransform()` 是否返回true
2. 如果返回false（次数为0），拒绝变身并输出警告日志
3. 如果返回true且次数>0，执行变身并将次数减1
4. 如果次数为-1（无限次），直接变身不消耗次数

### 2. 日志输出

系统会在以下情况输出日志：

- **变身成功**: 显示剩余次数
- **变身失败**: 警告次数已用完

示例日志：
```
LogTemp: Transform count decreased. Remaining: 4
LogTemp: Warning: Cannot transform - no remaining transform count (0/0)
```

## 使用场景

### 场景1: 切换TileMap时自动设置变身次数

**此功能已自动实现，无需额外配置！**

当调用`ChangeSubLevel`或`ChangeSubLevelByName`时，会自动：
- 根据TileMapTransformLimits配置查找该TileMap的最大变身次数
- 更新PlayerState的MaxTransformCount和RemainingTransformCount
- 玩家获得新TileMap的变身次数

### 场景2: UI显示当前剩余变身次数

```blueprint
Event Tick (in UI Widget)
  -> Get Game Mode (cast to LevelGMBase)
  -> Get Current Transform Count
  -> Branch
     >= 0 -> Set Text (剩余: X 次)
     < 0  -> Set Text (剩余: ∞)
```

或者直接从PlayerState获取：

```blueprint
Event Tick (in UI Widget)
  -> Get Owning Player
  -> Get Player State (cast to HeronPlayerState)
  -> Get Remaining Transform Count
  -> Set Text
```

### 场景3: 拾取道具增加变身次数

```blueprint
Event OnPickupTransformItem
  -> Get Owning Player
  -> Get Player State (cast to HeronPlayerState)
  -> Add Transform Count (Count = 1)
  -> Print String ("获得额外变身次数！")
```

### 场景4: 检查能否变身

```blueprint
// 玩家按下变身键时
Event OnTransformKeyPressed
  -> Get Player State (cast to HeronPlayerState)
  -> Can Transform?
     True -> Switch Ability (NewAbilityType)
     False -> Show "变身次数已用完" Message
```

### 场景5: 查询指定TileMap的配置

```blueprint
// 在UI中显示关卡信息
Event UpdateLevelInfo
  -> Get Game Mode (cast to LevelGMBase)
  -> Get TileMap Max Transform Count
     TileMapName: SubLevel_Hard1
  -> Set Text ("该关卡变身次数: " + ToString)
```

## 配置建议

### 不同关卡的次数配置

| SubLevel类型 | 建议次数 | 说明 |
|------------|---------|------|
| 教学关卡 | -1 (无限) | 让玩家熟悉各种形态 |
| 普通关卡 | 5-10 | 需要策略性使用变身 |
| 困难关卡 | 3-5 | 更具挑战性 |
| Boss关卡 | -1 或 很多 | 根据boss机制设计 |
| 解谜关卡 | 精确数量 | 根据解谜需要的最少变身次数+1或2 |

### 道具增加次数建议

- **小道具**: +1次
- **中道具**: +2-3次
- **大道具**: +5次或直接设为无限

## 注意事项

1. **自动管理**: 切换TileMap时会自动重置变身次数，无需手动调用
2. **配置优先**: 变身次数由LevelGMBase的TileMapTransformLimits配置决定
3. **未配置的TileMap**: 如果某个TileMap没有在配置数组中，默认为无限次（-1）
4. **标签匹配**: TileMapTag必须与场景中TileMap Actor的标签完全一致
5. **首次变身**: 第一次切换形态也会消耗次数（除非是无限次）
6. **道具增加**: 使用AddTransformCount可以在同一TileMap内增加额外次数
7. **跨TileMap**: 切换到新TileMap时，之前TileMap剩余的次数会丢失，重新获得新TileMap的次数
8. **保存系统**: 如果需要保存变身次数，应该保存当前TileMap和剩余次数

## 调试建议

1. 在屏幕上实时显示剩余变身次数
2. 设置较少的次数（如1-2次）快速测试限制逻辑
3. 观察日志输出确认次数变化
4. 测试无限次（-1）和有限次两种模式
5. 测试道具增加次数的功能
6. 测试重置次数的功能

## 示例：完整的配置流程

### 步骤1: 在LevelGMBase中配置TileMap变身次数

在GameMode蓝图（继承自LevelGMBase）的Details面板中：

```
TileMapTransformLimits:
  [0]
    TileMapTag: SubLevel_Tutorial
    MaxTransformCount: -1           // 教学关卡：无限次
  [1]
    TileMapTag: SubLevel_Level1
    MaxTransformCount: 8            // 第一关：8次
  [2]
    TileMapTag: SubLevel_Level2
    MaxTransformCount: 6            // 第二关：6次
  [3]
    TileMapTag: SubLevel_Boss1
    MaxTransformCount: -1           // Boss关：无限次
```

### 步骤2: 使用ChangeSubLevel切换关卡

```blueprint
// 在关卡触发器或通关逻辑中
Event OnLevelComplete
  -> Get Game Mode (cast to LevelGMBase)
  -> Change SubLevel By Name
     TileMapName: SubLevel_Level2
     TransitionTime: 1.0
  // 此时会自动设置玩家的变身次数为6次
```

### 步骤3: （可选）显示变身次数UI

```blueprint
// 在HUD Widget中
Event Tick
  -> Get Game Mode
  -> Get Current Transform Count
  -> Branch
     Count >= 0 -> Set Text ("变身: " + Count + "次")
     Count < 0  -> Set Text ("变身: ∞")
```

### 步骤4: （可选）道具增加变身次数

```blueprint
// 在道具Actor中
Event OnActorBeginOverlap
  -> Cast to HeronPlayer
  -> Get Player State
  -> Add Transform Count (Count = 2)
  -> Show Message ("获得2次额外变身机会！")
  -> Destroy Self
```

这样就完成了整个变身次数限制系统的配置！


