521 lines
15 KiB
Markdown
521 lines
15 KiB
Markdown
# 新手引导系统
|
||
|
||
<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设计和流畅的交互体验
|
||
|
||
开发者可以通过本系统快速实现各种类型的引导功能，为新用户提供良好的游戏体验。系统的可扩展性也确保了随着游戏发展，可以轻松添加新的引导内容和功能。 |