285 lines
10 KiB
Markdown
285 lines
10 KiB
Markdown
# FTUE / 新手引导系统架构设计
|
||
# Tutorial & Onboarding System Architecture
|
||
|
||
> **范围**：本文档涵盖游戏的首次用户体验（FTUE）、上下文提示、引导状态机，以及
|
||
> `TutorialManager` Autoload 的完整设计规范。
|
||
> 本文档以 `architecture_design.md` 为基础，所有运行时接口遵循 §6.1 语言分区原则。
|
||
|
||
---
|
||
|
||
## 一、设计目标
|
||
|
||
| 目标 | 度量标准 |
|
||
| :--- | :--- |
|
||
| 前 3 分钟玩家留存 | 90%+ 玩家完成首波（Wave 1）且尝试第一次施法 |
|
||
| 零文字强制阅读 | 教学信息通过上下文提示传达，不弹出强制阅读对话框 |
|
||
| 可跳过原则 | 所有引导步骤可在设置中永久关闭，或在进行中跳过 |
|
||
| 渐进式复杂度 | W1–W3 仅展示核心移动+射击；W4+ 逐步解锁进阶提示 |
|
||
|
||
---
|
||
|
||
## 二、TutorialManager Autoload
|
||
|
||
### 2.1 职责边界
|
||
|
||
- **GDScript 层**（`tutorial_manager.gd`）：状态读写、EventBus 订阅、提示节点显示/隐藏。
|
||
- **不含热路径**：提示触发频率极低（每场景级别），全部保留在 GDScript。
|
||
|
||
```gdscript
|
||
# scripts/autoloads/tutorial_manager.gd
|
||
extends Node
|
||
|
||
## 教学步骤枚举（顺序即解锁顺序）
|
||
enum TutorialStep {
|
||
MOVE = 0, # WASD 移动
|
||
CAST = 1, # 首次自动施法（Wand 冷却后自动提示）
|
||
PICK_SPELL = 2, # 首次拾取法术卡
|
||
OPEN_SHOP = 3, # 首次进入商店
|
||
EQUIP_CORE = 4, # 首次装备 Core
|
||
KILL_10 = 5, # 击杀 10 个敌人
|
||
WAVE_CLEARED = 6, # 通过 Wave 1
|
||
RESONANCE_HINT = 7, # 首次触发共鸣（S3 解锁）
|
||
COMPLETED = 99, # 引导全部完成
|
||
}
|
||
|
||
## 已完成步骤的持久化集合（存入 ProfileManager）
|
||
var _completed_steps: PackedInt32Array = PackedInt32Array()
|
||
|
||
## 当前激活提示步骤（-1 = 无）
|
||
var _active_step: int = -1
|
||
|
||
func _ready() -> void:
|
||
# 从 ProfileManager 恢复已完成状态
|
||
_completed_steps = ProfileManager.get_int_array(
|
||
"tutorial_completed", PackedInt32Array())
|
||
# 订阅进度事件
|
||
EventBus.subscribe(EventID.PLAYER_SPAWNED, _on_player_spawned)
|
||
EventBus.subscribe(EventID.SPELL_CAST, _on_spell_cast)
|
||
EventBus.subscribe(EventID.SHOP_OPENED, _on_shop_opened)
|
||
EventBus.subscribe(EventID.ENEMY_KILLED, _on_enemy_killed)
|
||
EventBus.subscribe(EventID.WAVE_CLEARED, _on_wave_cleared)
|
||
EventBus.subscribe(EventID.RESONANCE_TRIGGERED, _on_resonance)
|
||
```
|
||
|
||
### 2.2 状态机定义
|
||
|
||
```
|
||
[初始状态]
|
||
│
|
||
▼
|
||
MOVE ──────────────── 检测：玩家首帧输入 WASD 后标记完成
|
||
│
|
||
▼
|
||
CAST ──────────────── 检测：EventID.SPELL_CAST 首次触发
|
||
│
|
||
▼
|
||
PICK_SPELL ─────────── 检测：拾取 loot 掉落的法术卡
|
||
│
|
||
▼
|
||
OPEN_SHOP ──────────── 检测：Wave 1 通关后自动弹出商店提示
|
||
│
|
||
▼
|
||
EQUIP_CORE ─────────── 检测：首次从商店装备任意 Core
|
||
│
|
||
▼
|
||
KILL_10 ────────────── 检测：ENEMY_KILLED 事件累计 10 次
|
||
│
|
||
▼
|
||
WAVE_CLEARED ───────── 检测：WAVE_CLEARED（wave_num=1）
|
||
│
|
||
▼
|
||
RESONANCE_HINT ─────── 检测：RESONANCE_TRIGGERED（S3 起激活）
|
||
│
|
||
▼
|
||
COMPLETED ──────────── 持久化到 ProfileManager，停止所有提示
|
||
```
|
||
|
||
- **前向跳跃**：若玩家自行完成某步（无提示出现），步骤自动标记完成，无需显示提示。
|
||
- **后向保护**：已完成步骤不会因新 Run 而重置（存 ProfileManager 而非 RunData）。
|
||
|
||
### 2.3 核心接口
|
||
|
||
```gdscript
|
||
# 查询某步骤是否已完成
|
||
func is_completed(step: TutorialStep) -> bool:
|
||
return step in _completed_steps
|
||
|
||
# 手动标记完成（商店系统 / 法杖编辑器调用）
|
||
func mark_complete(step: TutorialStep) -> void:
|
||
if is_completed(step): return
|
||
_completed_steps.append(int(step))
|
||
ProfileManager.set_int_array("tutorial_completed", _completed_steps)
|
||
_hide_hint()
|
||
EventBus.emit(EventID.TUTORIAL_STEP_COMPLETED, step)
|
||
|
||
# 显示上下文提示（锚定到 UI 节点旁）
|
||
func show_hint(step: TutorialStep, anchor: Control,
|
||
offset: Vector2 = Vector2.ZERO) -> void:
|
||
if is_completed(step): return
|
||
_active_step = step
|
||
# 委托给 UIManager 渲染气泡提示
|
||
UIManager.show_tutorial_hint(
|
||
TutorialHintData.build(step), anchor, offset)
|
||
|
||
func _hide_hint() -> void:
|
||
if _active_step == -1: return
|
||
UIManager.hide_tutorial_hint()
|
||
_active_step = -1
|
||
```
|
||
|
||
---
|
||
|
||
## 三、上下文提示系统（Contextual Hints）
|
||
|
||
### 3.1 提示数据结构
|
||
|
||
```gdscript
|
||
# resources/tutorial/tutorial_hint_data.gd
|
||
class_name TutorialHintData
|
||
extends Resource
|
||
|
||
@export var step: int # TutorialStep 枚举值
|
||
@export var icon_key: String # 对应 UIAtlas 中的图标键（如 "wasd_icon"）
|
||
@export var text_key: String # i18n 键（tr(text_key) 使用）
|
||
@export var arrow_dir: int # 0=上, 1=右, 2=下, 3=左（箭头指向目标）
|
||
@export var duration: float = 0.0 # 0 = 手动关闭，>0 = 自动消失秒数
|
||
|
||
static func build(step: TutorialManager.TutorialStep) -> TutorialHintData:
|
||
return _HINT_TABLE[step]
|
||
|
||
# 提示内容表（运行时常量，避免 JSON 热加载）
|
||
const _HINT_TABLE: Dictionary = {
|
||
0: preload("res://resources/tutorial/hint_move.tres"),
|
||
1: preload("res://resources/tutorial/hint_cast.tres"),
|
||
2: preload("res://resources/tutorial/hint_pick_spell.tres"),
|
||
3: preload("res://resources/tutorial/hint_shop.tres"),
|
||
4: preload("res://resources/tutorial/hint_equip_core.tres"),
|
||
5: preload("res://resources/tutorial/hint_kill10.tres"),
|
||
6: preload("res://resources/tutorial/hint_wave_cleared.tres"),
|
||
7: preload("res://resources/tutorial/hint_resonance.tres"),
|
||
}
|
||
```
|
||
|
||
### 3.2 提示触发时机
|
||
|
||
| 步骤 | 触发时机 | 自动消失 | 跳过方式 |
|
||
| :--- | :--- | :--- | :--- |
|
||
| MOVE | 游戏开始后 1s（玩家还未移动） | 首次移动后 | 任意移动 |
|
||
| CAST | 法杖冷却恢复后 2s（玩家未施法） | 首次施法后 | 施法 |
|
||
| PICK_SPELL | 首个法术 loot 落地后 3s | 拾取后 | 走到 loot 上 |
|
||
| OPEN_SHOP | Wave 1 通关时自动进入商店流程 | 商店打开后 | 自动 |
|
||
| EQUIP_CORE | 商店内有 Core 可购买时 | 购买后 | 购买 |
|
||
| KILL_10 | 击杀计数达 5 时预显提示 | 计数达 10 | 击杀 |
|
||
| WAVE_CLEARED | Wave 1 通关瞬间 | 5s 后 | 点击 |
|
||
| RESONANCE_HINT | 首次编辑法杖时检测邻接 | 触发共鸣后 | 触发共鸣 |
|
||
|
||
### 3.3 提示 UI 节点结构
|
||
|
||
```
|
||
CombatScene
|
||
└── UILayer (CanvasLayer z_index=100)
|
||
└── TutorialHintContainer # UIManager 管理的专用节点
|
||
├── HintBubble (Panel)
|
||
│ ├── Icon (TextureRect)
|
||
│ └── Label (text = tr(hint.text_key))
|
||
└── Arrow (TextureRect, 根据 arrow_dir 旋转)
|
||
```
|
||
|
||
- `TutorialHintContainer` 随 `anchor` 节点世界坐标定位（`force_update_transform` 每帧同步）。
|
||
- 气泡使用 `AnimationPlayer` 播放 0.2s 淡入动画，消失时 0.15s 淡出。
|
||
- 同一时刻最多显示 1 个提示（显示新提示时先隐藏旧提示）。
|
||
|
||
---
|
||
|
||
## 四、首 3 分钟玩家流（First 3 Minutes Flow）
|
||
|
||
```
|
||
T=0s 游戏载入 → CombatScene 初始化
|
||
T=1s [提示] WASD 移动（气泡锚定玩家位置右侧，arrow→左）
|
||
T=~5s 玩家完成移动 → MOVE 标记完成 → 提示消失
|
||
T=~8s 法杖冷却结束 → [提示] 观察法术已自动施发（施法为自动）
|
||
T=~15s 首个敌人被击杀 → loot 掉落 → [提示] 拾取法术卡
|
||
T=~30s 玩家拾取法术卡 → PICK_SPELL 标记完成
|
||
T=~60s Wave 1 清场 → 自动进入商店
|
||
T=商店 [提示] 尝试装备 Core（若商店有 Core，arrow→Core 格）
|
||
T=~90s 购买/关闭商店 → Wave 2 开始
|
||
T=~120s 已掌握基本循环，FTUE 完成度 ~70%
|
||
T=Wave 4+ 触发共鸣时 → 最终提示显示
|
||
```
|
||
|
||
---
|
||
|
||
## 五、关键 EventID 扩展
|
||
|
||
> 以下 EventID 需追加到 `event_id.gd`（当前最大 ID = 17）：
|
||
|
||
| ID | 常量名 | 负载 | 触发方 | 监听方 |
|
||
| :--- | :--- | :--- | :--- | :--- |
|
||
| 18 | `TUTORIAL_STEP_COMPLETED` | `step: int` | TutorialManager | UIManager（显示解锁提示）|
|
||
| 19 | `SHOP_OPENED` | — | ShopManager | TutorialManager |
|
||
| 20 | `RESONANCE_TRIGGERED` | `recipe_id: String` | SpellEvaluator | TutorialManager, VFXManager |
|
||
| 21 | `ACHIEVEMENT_UNLOCKED` | `achievement_id: String` | AchievementManager | Steam 插件层 |
|
||
|
||
> **注意**：ID 0 为 `CRASH_DETECTED`（CrashReporter 专用，已定义）。
|
||
|
||
---
|
||
|
||
## 六、可跳过 & 关闭机制
|
||
|
||
```gdscript
|
||
# settings_manager.gd 新增项
|
||
const KEY_TUTORIAL_DISABLED: String = "tutorial_disabled"
|
||
|
||
# TutorialManager._ready() 中检查
|
||
func _ready() -> void:
|
||
if ProfileManager.get_bool(SettingsManager.KEY_TUTORIAL_DISABLED, false):
|
||
# 将所有步骤标记为已完成，彻底关闭引导
|
||
for s in TutorialStep.values():
|
||
_completed_steps.append(s)
|
||
return
|
||
# 正常初始化...
|
||
```
|
||
|
||
设置菜单提供「关闭新手提示」开关，写入 `ProfileManager`（持久化跨 Run）。
|
||
**重置入口**：`SettingsManager.reset_tutorial()` → 清空 `tutorial_completed` 并重置标志，
|
||
下次启动重新触发完整 FTUE 流程（适用于练习账号 / QA 测试）。
|
||
|
||
---
|
||
|
||
## 七、文件清单
|
||
|
||
```
|
||
scripts/autoloads/
|
||
tutorial_manager.gd # 核心 Autoload（本文档 §2 实现）
|
||
|
||
resources/tutorial/
|
||
hint_move.tres # TutorialHintData（MOVE 步骤）
|
||
hint_cast.tres
|
||
hint_pick_spell.tres
|
||
hint_shop.tres
|
||
hint_equip_core.tres
|
||
hint_kill10.tres
|
||
hint_wave_cleared.tres
|
||
hint_resonance.tres
|
||
|
||
scenes/ui/
|
||
tutorial_hint_bubble.tscn # HintBubble + Arrow 节点树
|
||
```
|
||
|
||
**Autoload 注册顺序**（`project.godot`）：
|
||
|
||
> `TutorialManager` 在 `EventBus` 和 `ProfileManager` 之后注册，
|
||
> 确保 `_ready()` 时可正常读取持久化数据并订阅事件。
|
||
|
||
---
|
||
|
||
## 八、与其他系统的接口约定
|
||
|
||
| 系统 | 接口 | 说明 |
|
||
| :--- | :--- | :--- |
|
||
| `UIManager` | `show_tutorial_hint(data, anchor, offset)` / `hide_tutorial_hint()` | 渲染和动画委托给 UIManager |
|
||
| `ProfileManager` | `get_int_array / set_int_array("tutorial_completed", ...)` | 跨 Run 持久化已完成步骤 |
|
||
| `EventBus` | 订阅 ID 1/6/11/18~21 等 | 只读订阅，不 emit 游戏逻辑事件 |
|
||
| `SpellEvaluator` | 无直接依赖 | 共鸣触发通过 `RESONANCE_TRIGGERED` 事件解耦 |
|
||
| `SettingsManager` | `KEY_TUTORIAL_DISABLED` 常量 | 关闭引导的持久化开关 |
|