Project02/ProjectFish/Docs/TutorialSystemDesign_Simple.md

# 新手引导系统设计（简化版）

## 一、核心思路

**一句话概括**：用一个 `TutorialManager` 管理引导流程，通过 Widget 的 `Tag` 控制显示/隐藏/高亮。

---

## 二、只需要3个东西

### 1. TutorialManager（一个管理类）

```cpp
// TutorialManager.h
#pragma once

#include "CoreMinimal.h"
#include "Subsystems/GameInstanceSubsystem.h"
#include "TutorialManager.generated.h"

// 简单的步骤配置
USTRUCT(BlueprintType)
struct FTutorialStep
{
    GENERATED_BODY()

    // 步骤ID
    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    int32 StepID = 0;

    // 可见的Widget标签（其他都隐藏）
    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    TArray<FName> VisibleWidgetTags;

    // 高亮的Widget标签
    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    TArray<FName> HighlightWidgetTags;

    // 提示文本（可选）
    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    FText HintText;

    // 对话资产（可选）
    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    class UDialogueAsset* DialogueAsset;
};

UCLASS()
class PROJECTFISH_API UTutorialManager : public UGameInstanceSubsystem
{
    GENERATED_BODY()

public:
    // 开始引导
    UFUNCTION(BlueprintCallable, Category = "Tutorial")
    void StartTutorial();

    // 进入下一步
    UFUNCTION(BlueprintCallable, Category = "Tutorial")
    void NextStep();

    // 完成引导
    UFUNCTION(BlueprintCallable, Category = "Tutorial")
    void FinishTutorial();

    // 是否在引导中
    UFUNCTION(BlueprintPure, Category = "Tutorial")
    bool IsInTutorial() const { return bInTutorial; }

    // 获取当前步骤
    UFUNCTION(BlueprintPure, Category = "Tutorial")
    int32 GetCurrentStep() const { return CurrentStepIndex; }

    // 检查Widget是否应该显示
    UFUNCTION(BlueprintPure, Category = "Tutorial")
    bool ShouldShowWidget(FName WidgetTag) const;

    // 检查Widget是否应该高亮
    UFUNCTION(BlueprintPure, Category = "Tutorial")
    bool ShouldHighlightWidget(FName WidgetTag) const;

    // 隐藏遮罩层
    UFUNCTION(BlueprintCallable, Category = "Tutorial")
    void ShowMask(bool bShow);

protected:
    // 引导步骤配置（在编辑器中配置）
    UPROPERTY(EditDefaultsOnly, Category = "Tutorial")
    TArray<FTutorialStep> TutorialSteps;

    UPROPERTY()
    bool bInTutorial = false;

    UPROPERTY()
    int32 CurrentStepIndex = -1;

private:
    void ApplyCurrentStep();
    void BroadcastStepChanged();
};
```

```cpp
// TutorialManager.cpp
#include "TutorialManager.h"

void UTutorialManager::StartTutorial()
{
    bInTutorial = true;
    CurrentStepIndex = 0;
    ApplyCurrentStep();
}

void UTutorialManager::NextStep()
{
    if (!bInTutorial) return;

    CurrentStepIndex++;
    if (CurrentStepIndex >= TutorialSteps.Num())
    {
        FinishTutorial();
        return;
    }

    ApplyCurrentStep();
}

void UTutorialManager::FinishTutorial()
{
    bInTutorial = false;
    CurrentStepIndex = -1;

    // 保存到存档
    // GameInfoManager->SetTutorialCompleted(true);

    ShowMask(false);
}

bool UTutorialManager::ShouldShowWidget(FName WidgetTag) const
{
    if (!bInTutorial) return true; // 正常模式全显示

    if (!TutorialSteps.IsValidIndex(CurrentStepIndex))
        return true;

    const FTutorialStep& Step = TutorialSteps[CurrentStepIndex];

    // 如果没有配置，默认显示
    if (Step.VisibleWidgetTags.Num() == 0)
        return true;

    // 白名单模式：只显示列表中的
    return Step.VisibleWidgetTags.Contains(WidgetTag);
}

bool UTutorialManager::ShouldHighlightWidget(FName WidgetTag) const
{
    if (!bInTutorial) return false;

    if (!TutorialSteps.IsValidIndex(CurrentStepIndex))
        return false;

    const FTutorialStep& Step = TutorialSteps[CurrentStepIndex];
    return Step.HighlightWidgetTags.Contains(WidgetTag);
}

void UTutorialManager::ApplyCurrentStep()
{
    BroadcastStepChanged();

    if (!TutorialSteps.IsValidIndex(CurrentStepIndex))
        return;

    const FTutorialStep& Step = TutorialSteps[CurrentStepIndex];

    // 如果有对话，播放对话
    if (Step.DialogueAsset)
    {
        // 调用对话系统播放
        // DialogueSystem->PlayDialogue(Step.DialogueAsset);
    }

    // 显示遮罩
    ShowMask(true);
}

void UTutorialManager::BroadcastStepChanged()
{
    // 通知所有UI刷新
    // 可以用事件委托或直接遍历所有Widget
}

void UTutorialManager::ShowMask(bool bShow)
{
    // 创建/显示/隐藏遮罩Widget
    // 遮罩Widget是一个全屏的半透明黑色背景
}
```

---

### 2. Widget上设置Tag

在UMG编辑器中，给每个需要控制的Widget设置Tag：

```
HomeUI:
  ├─ Btn_Sail (Tag: "Btn_Sail")
  ├─ Btn_Market (Tag: "Btn_Market")
  ├─ Btn_Shop (Tag: "Btn_Shop")
  └─ Btn_Backpack (Tag: "Btn_Backpack")
```

---

### 3. Widget蓝图中检查是否显示

在每个Widget的蓝图中，添加简单逻辑：

```
Event Construct:
  ├─ Get TutorialManager
  ├─ Bind to OnStepChanged Event
  └─ Call UpdateVisibility()

UpdateVisibility():
  ├─ For each child widget:
  │   ├─ Get widget tag
  │   ├─ TutorialManager->ShouldShowWidget(tag)
  │   └─ Set Visibility (Visible / Collapsed)
  └─ Update Highlight state
```

---

## 三、15步引导配置（简单表格）

在 `TutorialManager` 的 `TutorialSteps` 数组中配置：

| 步骤 | VisibleWidgetTags | HighlightWidgetTags | 说明 |
|------|-------------------|---------------------|------|
| 0 | [] | [] | 初始对话（DialogueAsset配置） |
| 1 | [Btn_Sail] | [Btn_Sail] | 只显示出航按钮并高亮 |
| 2 | [MapNode_0] | [MapNode_0] | 地图只显示一个节点 |
| 3 | [] | [] | 进入Loading |
| 4 | [MovementHint] | [] | 显示移动提示 |
| 5 | [FishingHint] | [] | 显示钓鱼提示 |
| 6 | [BattleUI] | [] | 战斗界面（隐藏背包/返航） |
| ... | ... | ... | ... |

**配置方式**：在编辑器的 `Project Settings -> Tutorial Manager` 中直接填表格。

---

## 四、UI改造（最简单的方式）

### 方式1：蓝图中直接判断（推荐）

在每个Widget的蓝图中：

```blueprint
Event Construct:
  ├─ GetGameInstance
  ├─ GetSubsystem(TutorialManager)
  ├─ Bind Event: OnStepChanged -> UpdateVisibility
  └─ Call UpdateVisibility

Function UpdateVisibility:
  ├─ If TutorialManager->IsInTutorial():
  │   ├─ Set Btn_Sail Visibility: ShouldShowWidget("Btn_Sail")
  │   ├─ Set Btn_Market Visibility: ShouldShowWidget("Btn_Market")
  │   └─ ...
  └─ Else: Show All
```

### 方式2：C++中统一处理

创建一个简单的基类：

```cpp
// TutorialWidget.h
#pragma once

#include "Blueprint/UserWidget.h"
#include "TutorialWidget.generated.h"

UCLASS()
class UTutorialWidget : public UUserWidget
{
    GENERATED_BODY()

public:
    virtual void NativeConstruct() override;

protected:
    // 在子类中填写：Widget名 -> Tag的映射
    UPROPERTY(EditDefaultsOnly, Category = "Tutorial")
    TMap<FName, UWidget*> WidgetTagMap;

    UFUNCTION()
    void UpdateVisibility();

private:
    UPROPERTY()
    class UTutorialManager* TutorialManager;
};
```

```cpp
// TutorialWidget.cpp
#include "TutorialWidget.h"
#include "TutorialManager.h"

void UTutorialWidget::NativeConstruct()
{
    Super::NativeConstruct();

    TutorialManager = GetGameInstance()->GetSubsystem<UTutorialManager>();
    if (TutorialManager)
    {
        // 绑定步骤改变事件
        // TutorialManager->OnStepChanged.AddDynamic(this, &UTutorialWidget::UpdateVisibility);
    }

    UpdateVisibility();
}

void UTutorialWidget::UpdateVisibility()
{
    if (!TutorialManager || !TutorialManager->IsInTutorial())
    {
        // 正常模式：全部显示
        for (auto& Pair : WidgetTagMap)
        {
            if (Pair.Value)
                Pair.Value->SetVisibility(ESlateVisibility::Visible);
        }
        return;
    }

    // 引导模式：根据Tag判断
    for (auto& Pair : WidgetTagMap)
    {
        if (!Pair.Value) continue;

        bool bShouldShow = TutorialManager->ShouldShowWidget(Pair.Key);
        Pair.Value->SetVisibility(bShouldShow ? ESlateVisibility::Visible : ESlateVisibility::Collapsed);

        // 高亮效果
        bool bShouldHighlight = TutorialManager->ShouldHighlightWidget(Pair.Key);
        if (bShouldHighlight)
        {
            // 添加高亮动画或材质效果
            // PlayAnimation(HighlightAnim);
        }
    }
}
```

然后让 HomeUI 继承这个基类，在构造函数中填写映射：

```cpp
// HomeUIWidget.cpp
void UHomeUIWidget::NativeConstruct()
{
    Super::NativeConstruct();

    // 填写映射
    WidgetTagMap.Add(TEXT("Btn_Sail"), Btn_Sail);
    WidgetTagMap.Add(TEXT("Btn_Market"), Btn_Market);
    WidgetTagMap.Add(TEXT("Btn_Shop"), Btn_Shop);
    WidgetTagMap.Add(TEXT("Btn_Backpack"), Btn_Backpack);
}
```

---

## 五、特殊情况处理

### 1. 战斗特殊配置

不需要新的配置类，直接在战斗开始时检查：

```cpp
// AProjectFishGameMode.cpp
void AProjectFishGameMode::StartBattle()
{
    UTutorialManager* Tutorial = GetGameInstance()->GetSubsystem<UTutorialManager>();

    if (Tutorial && Tutorial->IsInTutorial())
    {
        int32 Step = Tutorial->GetCurrentStep();

        // 第一场战斗（步骤6）
        if (Step == 6)
        {
            // 使用特定的鱼配置
            CurrentFish = LoadObject<UFishInfoConfigAsset>(..., TEXT("Tutorial_Fish_01"));

            // 强制掉落
            bForceDropItem = true;
            ForcedDropItems.Add(TEXT("Item_Bass"));
        }
        // 第二场战斗（步骤9）
        else if (Step == 9)
        {
            CurrentFish = LoadObject<UFishInfoConfigAsset>(..., TEXT("Tutorial_Fish_02"));
            ForcedDropItems.Add(TEXT("Item_Bass"));
            ForcedDropItems.Add(TEXT("Item_MagicBook"));
        }
    }
}
```

### 2. 地图单节点

```cpp
// FishingMapSubSystem.cpp
void UFishingMapSubSystem::GenerateMap()
{
    UTutorialManager* Tutorial = GetGameInstance()->GetSubsystem<UTutorialManager>();

    if (Tutorial && Tutorial->IsInTutorial() && Tutorial->GetCurrentStep() == 2)
    {
        // 只生成1个节点
        AllNodes.Empty();
        UFishingMapNode* Node = NewObject<UFishingMapNode>();
        Node->NodeType = EMapNodeType::Battle;
        AllNodes.Add(Node);
        return;
    }

    // 正常生成
    GenerateMapWithConfig(DefaultMapConfig);
}
```

### 3. 强制拾取奖励

```cpp
// RewardWidget.cpp
void URewardWidget::NativeConstruct()
{
    Super::NativeConstruct();

    UTutorialManager* Tutorial = GetGameInstance()->GetSubsystem<UTutorialManager>();

    if (Tutorial && Tutorial->IsInTutorial())
    {
        int32 Step = Tutorial->GetCurrentStep();
        if (Step == 7 || Step == 10) // 两场战斗后
        {
            // 隐藏关闭按钮，直到拾取完毕
            Btn_Close->SetVisibility(ESlateVisibility::Collapsed);
            bMustCollectAll = true;
        }
    }
}

void URewardWidget::OnAllItemsCollected()
{
    if (bMustCollectAll)
    {
        Btn_Close->SetVisibility(ESlateVisibility::Visible);
        // 显示提示："点击关闭继续"
    }
}
```

---

## 六、遮罩和高亮效果（简单实现）

### 遮罩Widget（WBP_TutorialMask）

创建一个简单的UMG：
```
Canvas Panel (全屏)
└─ Image (黑色，透明度0.7)
```

在 TutorialManager 中显示/隐藏它。

### 高亮效果（3种简单方案）

**方案1：边框发光**
```cpp
// 给按钮添加一个Border，设置发光颜色
Btn_Sail->SetBorderBrush(HighlightBrush);
```

**方案2：缩放动画**
```
创建UMG动画：
  0.0s -> Scale 1.0
  0.5s -> Scale 1.1
  1.0s -> Scale 1.0
循环播放
```

**方案3：后处理材质**
给高亮Widget添加后处理效果（最炫酷，但稍复杂）。

---

## 七、完整流程示例

### 配置TutorialSteps（在编辑器中）

```cpp
TutorialSteps[0]:
  StepID: 0
  DialogueAsset: DA_Tutorial_Intro
  VisibleWidgetTags: []
  HintText: ""

TutorialSteps[1]:
  StepID: 1
  VisibleWidgetTags: [Btn_Sail]
  HighlightWidgetTags: [Btn_Sail]
  HintText: "点击【出航】按钮"

TutorialSteps[2]:
  StepID: 2
  VisibleWidgetTags: [MapNode_0]
  HighlightWidgetTags: [MapNode_0]
  HintText: "选择一个地点"

// ... 继续配置到步骤15
```

### 调用流程

```cpp
// 游戏启动时
void AMyGameInstance::Init()
{
    Super::Init();

    UTutorialManager* Tutorial = GetSubsystem<UTutorialManager>();

    // 检查存档
    bool bCompletedTutorial = GameInfoManager->HasCompletedTutorial();
    if (!bCompletedTutorial)
    {
        Tutorial->StartTutorial();
    }
}

// 出航按钮点击时
void UHomeUIWidget::OnSailButtonClicked()
{
    UTutorialManager* Tutorial = GetGameInstance()->GetSubsystem<UTutorialManager>();

    if (Tutorial && Tutorial->IsInTutorial() && Tutorial->GetCurrentStep() == 1)
    {
        // 完成步骤1，进入步骤2
        Tutorial->NextStep();
    }

    // 打开地图
    OpenMapUI();
}

// 地图节点点击时
void UMapWidget::OnNodeClicked()
{
    UTutorialManager* Tutorial = GetGameInstance()->GetSubsystem<UTutorialManager>();

    if (Tutorial && Tutorial->IsInTutorial() && Tutorial->GetCurrentStep() == 2)
    {
        Tutorial->NextStep();
    }

    // 进入战斗
    StartBattle();
}
```

---

## 八、总结

### 只需要做3件事：

1. **创建 TutorialManager**（1个类，~200行代码）
2. **给UI Widget设置Tag**（在UMG编辑器中操作）
3. **配置TutorialSteps表格**（在编辑器中填数据）

### 改造工作量：

- ✅ 新增代码：2个文件（TutorialManager + TutorialWidget基类）
- ✅ UI改造：继承基类或蓝图中加几行代码
- ✅ 特殊逻辑：在现有代码中加if判断
- ✅ 总代码量：<500行

### 优势：

- 🟢 **极简**：只有1个核心类
- 🟢 **直观**：配置就是一个表格
- 🟢 **灵活**：可蓝图可C++
- 🟢 **低侵入**：不破坏现有结构

---

## 九、文件结构

```
Source/ProjectFish/Tutorial/
├── TutorialManager.h          # 管理类（核心）
├── TutorialManager.cpp
├── TutorialWidget.h           # UI基类（可选）
└── TutorialWidget.cpp

Content/UI/Tutorial/
└── WBP_TutorialMask.uasset    # 遮罩Widget
```

就这么简单！🎉