# 新手引导系统

<cite>
**本文档引用的文件**
- [Guide.ts](file://assets/script/game/common/config/Guide.ts)
- [GuideConComp.ts](file://assets/script/game/map/GuideConComp.ts)
- [GuideSetpComp.ts](file://assets/script/game/map/GuideSetpComp.ts)
- [GameUIConfig.ts](file://assets/script/game/common/config/GameUIConfig.ts)
- [GameEvent.ts](file://assets/script/game/common/config/GameEvent.ts)
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts)
- [guide_step.prefab](file://assets/resources/gui/element/guide_step.prefab)
</cite>

## 目录
1. [简介](#简介)
2. [系统架构](#系统架构)
3. [核心数据结构](#核心数据结构)
4. [引导配置管理](#引导配置管理)
5. [引导流程控制](#引导流程控制)
6. [UI高亮与交互](#ui高亮与交互)
7. [事件监听与进度管理](#事件监听与进度管理)
8. [与Oops GUI系统集成](#与oops-gui系统集成)
9. [实际应用示例](#实际应用示例)
10. [跳过逻辑与资源清理](#跳过逻辑与资源清理)
11. [总结](#总结)

## 简介

新手引导系统是游戏中的重要组成部分，用于指导新玩家了解游戏的基本操作和核心玩法。本系统基于Oops框架构建，采用组件化设计，支持多种引导类型，具备完善的进度管理和事件驱动机制。

系统的主要特点包括：
- 支持点击、拖拽、提示、等待等多种引导类型
- 基于事件驱动的触发机制
- 完善的进度跟踪和状态管理
- 与Oops GUI系统的深度集成
- 可扩展的配置化引导方案

## 系统架构

新手引导系统采用分层架构设计，包含配置层、控制层和UI层三个主要部分：

```mermaid
graph TB
subgraph "配置层"
GC[GuideConfig<br/>引导配置]
GEC[EndEventToKey<br/>事件映射]
GT[GuideTypes<br/>引导类型]
end
subgraph "控制层"
GCC[GuideConComp<br/>引导控制器]
SM[SingletonModule<br/>单例模块]
GE[GameEvent<br/>游戏事件]
end
subgraph "UI层"
GSC[GuideSetpComp<br/>引导步骤UI]
GUI[Oops GUI<br/>界面管理]
GS[Guide Step<br/>引导步骤]
end
subgraph "资源层"
PREFAB[guide_step.prefab<br/>引导UI预制体]
CONFIG[GameUIConfig<br/>UI配置]
end
GC --> GCC
GEC --> GCC
GT --> GCC
GCC --> GSC
SM --> GCC
GE --> GCC
GSC --> GUI
GUI --> GS
PREFAB --> GSC
CONFIG --> GUI
```

**图表来源**
- [Guide.ts](file://assets/script/game/common/config/Guide.ts#L1-L283)
- [GuideConComp.ts](file://assets/script/game/map/GuideConComp.ts#L1-L220)
- [GuideSetpComp.ts](file://assets/script/game/map/GuideSetpComp.ts#L1-L268)

## 核心数据结构

### 引导步骤类型枚举

系统定义了四种基本的引导步骤类型：

| 类型 | 枚举值 | 描述 | 适用场景 |
|------|--------|------|----------|
| 点击操作 | `CLICK` | 用户需要点击目标节点 | 按钮激活、功能解锁 |
| 拖拽操作 | `DRAG` | 用户需要拖拽目标节点 | 物品移动、场景探索 |
| 显示提示 | `TIP` | 显示文字提示信息 | 游戏说明、规则介绍 |
| 等待操作 | `WAIT` | 等待特定时间或条件 | 动画播放、效果展示 |

### 引导步骤配置接口

每个引导步骤都遵循统一的配置接口规范：

```mermaid
classDiagram
class IGuideStep {
+string id
+GuideStepType type
+number key
+string targetPath
+string tipParent
+string tipText
+Vec2 tipOffset
+Vec2 handOffset
+string nextStep
+boolean skippable
+function condition
+UIID uiId
+number waitTime
+string end_event
+boolean noInput
}
class GuideStepType {
<<enumeration>>
CLICK
DRAG
TIP
WAIT
}
class UIID {
<<enumeration>>
Guide = 1001
}
IGuideStep --> GuideStepType
IGuideStep --> UIID
```

**图表来源**
- [Guide.ts](file://assets/script/game/common/config/Guide.ts#L25-L50)

**章节来源**
- [Guide.ts](file://assets/script/game/common/config/Guide.ts#L1-L283)

## 引导配置管理

### 引导配置数据结构

引导系统采用数字ID与字符串ID双重索引的方式管理引导配置：

```mermaid
erDiagram
GuideConfig {
number key PK
string id UK
GuideStepType type
number target_key
string target_path
string tip_text
vec2 hand_offset
string next_step
number wait_time
string end_event
boolean skippable
}
EndEventToKey {
string end_event PK
array guide_keys
}
SingletonModule {
array guides
number current_guide
}
GuideConfig ||--o{ EndEventToKey : "maps to"
SingletonModule ||--o{ GuideConfig : "tracks progress"
```

**图表来源**
- [Guide.ts](file://assets/script/game/common/config/Guide.ts#L52-L120)
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L35-L40)

### 引导配置示例

系统提供了完整的三步引导示例，展示了不同类型引导的实际应用场景：

| 步骤ID | 类型 | 目标路径 | 提示文本 | 手指偏移 |
|--------|------|----------|----------|----------|
| welcome | WAIT | root/gui/LayerUI/role_controller/mission_home/start/name | "伟大的勇者,欢迎来到 『像素模拟战』" | {42, -45} |
| start_battle | CLICK | root/gui/LayerUI/role_controller/mission_home/start/name | "请带领您的英雄抵御兽人的入侵吧！" | {42, -45} |
| hero_page | CLICK | root/gui/LayerUI/role_controller/mission_home/btns/heros | "在酒馆招募更多英雄增强队伍" | {42, -45} |

**章节来源**
- [Guide.ts](file://assets/script/game/common/config/Guide.ts#L52-L120)

## 引导流程控制

### 引导控制器架构

引导控制器负责整个引导流程的协调和管理：

```mermaid
sequenceDiagram
participant Player as 玩家
participant GCC as GuideConComp
participant SM as SingletonModule
participant GSC as GuideSetpComp
participant GUI as Oops GUI
Player->>GCC : 触发引导事件
GCC->>GCC : 验证引导权限
GCC->>GSC : 创建引导步骤UI
GSC->>GUI : 打开引导界面
GUI-->>GSC : UI加载完成
GSC->>GSC : 显示引导内容
Player->>GSC : 完成引导操作
GSC->>GCC : 步骤完成回调
GCC->>GCC : 检查下一步骤
GCC->>GSC : 启动下一引导
Note over GCC,GSC : 循环直到引导完成
```

**图表来源**
- [GuideConComp.ts](file://assets/script/game/map/GuideConComp.ts#L40-L80)
- [GuideSetpComp.ts](file://assets/script/game/map/GuideSetpComp.ts#L80-L120)

### 引导启动机制

引导系统采用事件驱动的启动方式，支持多种触发条件：

```mermaid
flowchart TD
Start([引导启动请求]) --> CheckPermission{检查权限}
CheckPermission --> |权限不足| ReturnError[返回错误]
CheckPermission --> |权限充足| GetGuide[获取引导配置]
GetGuide --> ValidateConfig{验证配置}
ValidateConfig --> |配置无效| ReturnError
ValidateConfig --> |配置有效| ClosePrevious[关闭之前引导]
ClosePrevious --> OpenUI[打开引导UI]
OpenUI --> ShowStep[显示引导步骤]
ShowStep --> WaitInput[等待用户输入]
WaitInput --> CompleteStep[完成步骤]
CompleteStep --> CheckNext{是否有下一步}
CheckNext --> |有| StartNext[启动下一引导]
CheckNext --> |无| CompleteGuide[完成引导]
StartNext --> ShowStep
CompleteGuide --> End([引导结束])
ReturnError --> End
```

**图表来源**
- [GuideConComp.ts](file://assets/script/game/map/GuideConComp.ts#L50-L90)

**章节来源**
- [GuideConComp.ts](file://assets/script/game/map/GuideConComp.ts#L1-L220)

## UI高亮与交互

### 引导步骤UI组件

引导步骤UI组件负责显示引导内容和处理用户交互：

```mermaid
classDiagram
class GuideSetpComp {
+Label tipLabel
+Node tipNode
+Node handNode
+Button skipButton
-IGuideStep currentStep
-number currentStepIndex
-number totalSteps
-Node _targetNode
-Node _tipParent
-boolean _showTip
-boolean _showHand
-any _callback
-boolean _noInput
-boolean _hasTouchListener
+onAdded(args) void
+handleStepInfo(data) void
+findTargetNode(path) Node
+showStep(step, index, total) void
+onTouchStart(event) void
+addTouchListener() void
+removeTouchListener() void
+onSkipButtonClick() void
+cleanup() void
}
class GuideStepType {
<<enumeration>>
CLICK
DRAG
TIP
WAIT
}
GuideSetpComp --> GuideStepType
```

**图表来源**
- [GuideSetpComp.ts](file://assets/script/game/map/GuideSetpComp.ts#L10-L50)

### 目标节点查找机制

系统提供了灵活的目标节点查找机制，支持相对路径和绝对路径两种方式：

```mermaid
flowchart TD
Start([开始查找目标节点]) --> SplitPath[分割路径字符串]
SplitPath --> GetScene[获取场景根节点]
GetScene --> LoopPath{遍历路径段}
LoopPath --> |路径段存在| GetChild[获取子节点]
LoopPath --> |路径段不存在| NotFound[节点未找到]
GetChild --> CheckChild{检查子节点}
CheckChild --> |找到| NextSegment[下一段]
CheckChild --> |未找到| NotFound
NextSegment --> MoreSegments{还有更多段?}
MoreSegments --> |是| LoopPath
MoreSegments --> |否| Found[节点找到]
NotFound --> LogError[记录错误日志]
Found --> ReturnNode[返回节点对象]
LogError --> ReturnNull[返回null]
```

**图表来源**
- [GuideSetpComp.ts](file://assets/script/game/map/GuideSetpComp.ts#L180-L220)

**章节来源**
- [GuideSetpComp.ts](file://assets/script/game/map/GuideSetpComp.ts#L1-L268)

## 事件监听与进度管理

### 事件监听机制

引导系统实现了完善的事件监听机制，支持多种交互方式：

```mermaid
sequenceDiagram
participant GSC as GuideSetpComp
participant Node as UI节点
participant Touch as 触摸系统
participant Callback as 回调函数
GSC->>Node : 添加触摸监听器
Node->>Touch : 注册事件监听
Touch-->>Node : 触摸事件发生
Node->>GSC : 触摸事件回调
GSC->>GSC : 验证引导类型
GSC->>Callback : 调用完成回调
Callback->>GSC : 清理资源
GSC->>Node : 移除监听器
```

**图表来源**
- [GuideSetpComp.ts](file://assets/script/game/map/GuideSetpComp.ts#L50-L90)

### 进度管理系统

系统采用数组形式管理引导进度，每个引导步骤对应数组的一个元素：

| 状态 | 数值 | 描述 | 影响 |
|------|------|------|------|
| 未开始 | 0 | 引导尚未执行 | 可以正常启动 |
| 进行中 | 0 | 引导正在执行 | 阻止重复启动 |
| 已完成 | 1 | 引导已经完成 | 不再显示该引导 |
| 已跳过 | 2 | 用户主动跳过 | 标记状态但不影响其他引导 |

**章节来源**
- [GuideConComp.ts](file://assets/script/game/map/GuideConComp.ts#L130-L170)
- [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L80-L90)

## 与Oops GUI系统集成

### GUI集成架构

新手引导系统与Oops GUI系统深度集成，利用其强大的界面管理能力：

```mermaid
graph LR
subgraph "Oops GUI系统"
GM[GUI Manager]
LM[Layer Manager]
PM[Prefab Manager]
end
subgraph "引导系统"
GCC[GuideConComp]
GSC[GuideSetpComp]
UI[UI Config]
end
subgraph "资源管理"
PREFAB[guide_step.prefab]
ASSETS[引导资源]
end
GCC --> GM
GSC --> LM
UI --> PM
PREFAB --> PM
ASSETS --> PM
GM --> UI
LM --> GSC
PM --> PREFAB
```

**图表来源**
- [GameUIConfig.ts](file://assets/script/game/common/config/GameUIConfig.ts#L20-L35)
- [GuideConComp.ts](file://assets/script/game/map/GuideConComp.ts#L170-L200)

### UI配置管理

系统通过统一的UI配置管理引导界面的加载和显示：

| 配置项 | 值 | 说明 |
|--------|-----|------|
| UIID.Guide | 1001 | 引导界面的唯一标识 |
| LayerType | UI | 界面层级类型 |
| Prefab路径 | gui/element/guide_step | 引导UI预制体路径 |
| Bundle | resources | 资源包名称 |

**章节来源**
- [GameUIConfig.ts](file://assets/script/game/common/config/GameUIConfig.ts#L1-L36)

## 实际应用示例

### 新增三步引导流程

以下是如何新增一个完整的三步引导流程的完整示例：

#### 1. 配置引导数据

```typescript
// 在Guide.ts中添加新的引导配置
export const GuideConfig: { [key: number]: IGuideStep } = {
    // ... 现有引导配置 ...
    
    11: {
        id: "new_feature_tutorial",
        type: GuideStepType.CLICK,
        key: 11,
        targetPath: "root/gui/LayerUI/new_feature_panel/button",
        tipText: "点击这里体验新功能！",
        handOffset: { x: 42, y: -45 },
        nextStep: "feature_explanation",
        skippable: true
    },
    
    12: {
        id: "feature_explanation",
        type: GuideStepType.TIP,
        key: 12,
        targetPath: "root/gui/LayerUI/new_feature_panel/explanation",
        tipText: "这是全新的功能特性，让游戏更加有趣！",
        tipOffset: { x: 0, y: 100 },
        waitTime: 3000,
        nextStep: "feature_usage"
    },
    
    13: {
        id: "feature_usage",
        type: GuideStepType.CLICK,
        key: 13,
        targetPath: "root/gui/LayerUI/new_feature_panel/usage_button",
        tipText: "现在尝试使用这个功能吧！",
        handOffset: { x: 42, y: -45 },
        skippable: true
    }
};
```

#### 2. 触发引导启动

```typescript
// 在适当的游戏事件中触发引导
oops.message.dispatchEvent(GameEvent.GuideStart, 11);
```

#### 3. 处理用户交互

系统会自动处理用户的点击、拖拽等交互行为，并根据配置自动推进到下一步骤。

#### 4. 完成回调处理

当引导完成后，系统会自动更新进度状态并清理相关资源。

**章节来源**
- [Guide.ts](file://assets/script/game/common/config/Guide.ts#L52-L120)
- [GuideConComp.ts](file://assets/script/game/map/GuideConComp.ts#L50-L90)

## 跳过逻辑与资源清理

### 跳过按钮实现

引导系统提供了完善的跳过功能，允许用户主动终止引导流程：

```mermaid
flowchart TD
Start([用户点击跳过]) --> HideTips[隐藏提示内容]
HideTips --> DestroyHands[销毁手势动画]
DestroyHands --> RemoveListeners[移除事件监听器]
RemoveListeners --> CallCallback[调用完成回调]
CallCallback --> CleanupResources[清理资源]
CleanupResources --> CloseUI[关闭引导界面]
CloseUI --> End([跳过完成])
```

**图表来源**
- [GuideSetpComp.ts](file://assets/script/game/map/GuideSetpComp.ts#L240-L260)

### 资源清理机制

系统实现了多层次的资源清理机制，确保内存使用效率：

| 清理阶段 | 清理内容 | 触发时机 |
|----------|----------|----------|
| 步骤完成 | 移除触摸监听器 | 每个步骤结束后 |
| 引导取消 | 销毁UI组件 | 用户跳过时 |
| 组件销毁 | 清理所有资源 | 组件生命周期结束 |
| 内存回收 | 释放引用 | 系统垃圾回收 |

**章节来源**
- [GuideSetpComp.ts](file://assets/script/game/map/GuideSetpComp.ts#L240-L268)

## 总结

新手引导系统是一个功能完善、架构清晰的游戏辅助系统。它具有以下核心优势：

1. **模块化设计**：采用分层架构，职责明确，易于维护和扩展
2. **事件驱动**：基于事件的触发机制，灵活性强，适应各种游戏场景
3. **配置化管理**：支持通过配置文件管理引导流程，减少代码耦合
4. **资源优化**：完善的资源清理机制，确保良好的性能表现
5. **用户体验**：直观的UI设计和流畅的交互体验

开发者可以通过本系统快速实现各种类型的引导功能，为新用户提供良好的游戏体验。系统的可扩展性也确保了随着游戏发展，可以轻松添加新的引导内容和功能。