pan/heros

Files

panw 4235e3b776 refactor(game): 移除已弃用的事件常量

- 删除 UpdateHero 和 UpdateFightHero 事件
- 移除 MISSION_UPDATE 事件常量
- 优化游戏事件枚举定义

2025-10-28 16:15:47 +08:00

15 KiB

Raw Blame History

新手引导系统

**本文档引用的文件** - [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)

简介

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

系统的主要特点包括：

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

系统架构

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

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

图表来源

核心数据结构

引导步骤类型枚举

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

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

引导步骤配置接口

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

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

章节来源

Guide.ts

引导配置管理

引导配置数据结构

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

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"

图表来源

引导配置示例

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

步骤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

引导流程控制

引导控制器架构

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

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 : 循环直到引导完成

图表来源

引导启动机制

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

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

章节来源

GuideConComp.ts

UI高亮与交互

引导步骤UI组件

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

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

目标节点查找机制

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

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

章节来源

GuideSetpComp.ts

事件监听与进度管理

事件监听机制

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

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

进度管理系统

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

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

章节来源

与Oops GUI系统集成

GUI集成架构

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

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

图表来源

UI配置管理

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

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

章节来源

GameUIConfig.ts

实际应用示例

新增三步引导流程

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

1. 配置引导数据

// 在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. 触发引导启动

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

3. 处理用户交互

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

4. 完成回调处理

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

章节来源

跳过逻辑与资源清理

跳过按钮实现

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

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

图表来源

GuideSetpComp.ts

资源清理机制

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

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

章节来源

GuideSetpComp.ts

总结

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

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

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

15 KiB Raw Blame History Unescape Escape

新手引导系统

目录

简介

系统架构

核心数据结构

引导步骤类型枚举

引导步骤配置接口

引导配置管理

引导配置数据结构

引导配置示例

引导流程控制

引导控制器架构

引导启动机制

UI高亮与交互

引导步骤UI组件

目标节点查找机制

事件监听与进度管理

事件监听机制

进度管理系统

与Oops GUI系统集成

GUI集成架构

UI配置管理

实际应用示例

新增三步引导流程

1. 配置引导数据

2. 触发引导启动

3. 处理用户交互

4. 完成回调处理

跳过逻辑与资源清理

跳过按钮实现

资源清理机制

总结

15 KiB

Raw Blame History