Echo/Assets/_Project/Docs/NarrationSystem_Technical_Reference.md

# NarrationSystem 技术参考

本文档定义并说明项目内的“旁白系统（NarrationSystem）”，以及它如何与任务系统（TaskSystem）配合，通过按钮继续/翻页在关键节点触发事件（例如添加/删除任务）。

相关脚本：
- `Assets/_Project/Scripts/Core/NarrationSystem/NarrationSystem.cs`
- `Assets/_Project/Scripts/Core/NarrationSystem/NarrationSequence.cs`
- `Assets/_Project/Scripts/Core/NarrationSystem/NarrationPage.cs`
- `Assets/_Project/Scripts/UI/Narration/NarrationPanelView.cs`
- （可选动作）`Assets/_Project/Scripts/Core/NarrationSystem/NarrationPlayByIdAction.cs`

任务系统动作脚本（用于旁白事件里绑定）：
- `Assets/_Project/Scripts/Core/TaskSystem/Actions/AddTaskAction.cs`
- `Assets/_Project/Scripts/Core/TaskSystem/Actions/RemoveTaskAction.cs`
- `Assets/_Project/Scripts/Core/TaskSystem/Actions/SetTaskStatusAction.cs`

## 1. 设计目标

- 旁白内容以“序列（Sequence）→ 多页（Page）”组织，可在 Inspector 中动态增删页数。
- 每一页都提供事件：
  - `onEnter`：进入该页时触发
  - `onContinue`：玩家点击继续离开该页时触发
- 旁白系统提供统一触发入口，可被开场流程/剧情节点/触发器/互动等系统调用。
- 旁白显示时自动切换为 UI 操作模式并显示鼠标，允许玩家点击继续：
  - 复用 `PlayerControlLockService.Lock/Unlock`（项目内既定范式）。

## 2. 数据结构

### 2.1 NarrationDataSO（基于 ScriptableObject 的数据容器）

脚本：`NarrationDataSO.cs`
- 在 Project 窗口右键 `Create -> Systems -> Narration -> Narration Data` 创建。
- 字段：
  - `id`：序列 ID（用于按 ID 播放）
  - `pages`：页列表（动态长度）

### 2.2 NarrationPageData（单页旁白数据）

脚本：位于 `NarrationDataSO.cs` 内
- 字段：
  - `text`：该页显示的文本
  - `enterActionId`：进入该页时触发的 Action ID（字符串）
  - `continueActionId`：点击继续离开该页时触发的 Action ID（字符串）

### 2.3 NarrationEventListener（场景事件监听器）

脚本：`NarrationEventListener.cs`
- 用于将 `NarrationDataSO` 中的字符串 Action ID 映射到场景内的 `UnityEvent`，从而触发具体的动作（如 `AddTaskAction`）。

## 3. 核心系统

### 3.1 NarrationSystem

脚本：`NarrationSystem.cs`

Inspector 槽位：
- `Panel View`：旁白 UI 视图（`NarrationPanelView`）
- `Data / Narration Database`：将所有需要支持 `PlayById` 的 `NarrationDataSO` 拖入此列表。
- `Lock Player Controls While Showing`：显示时是否锁定玩家控制并显示鼠标（推荐开启）

主要接口：
- `PlayById(string sequenceId)`：按 ID 播放序列
- `Play(NarrationDataSO sequence)`：直接播放序列引用
- `Stop()`：停止当前旁白
- `Continue()`：继续到下一页（由 UI 按钮驱动）

行为说明：
- 播放开始：显示 UI，显示鼠标（Lock），进入第 0 页并触发全局事件（带 `enterActionId`）
- 点击继续：
  - 先触发当前页全局事件（带 `continueActionId`）
  - 再进入下一页并触发新页全局事件（带 `enterActionId`）
- 最后一页点击继续：结束播放，隐藏 UI，恢复控制（Unlock）

### 3.2 NarrationPanelView

脚本：`NarrationPanelView.cs`

Inspector 槽位：
- `Root`：UI 根节点（用于 Show/Hide）
- `Narration Text`：TMP 文本控件
- `Continue Button`：Reach 的 `ButtonManager`（推荐）
- `Fallback Continue Button`：如果你不用 Reach Button，可填 Unity `Button`
- `Continue Label / Finish Label`：按钮文案（继续/确认）

## 4. 与 TaskSystem 配合（在旁白页事件里加/删任务）

因为 `TaskService.AddTask(...)` 这类方法需要参数，UnityEvent 直接绑不方便，推荐通过“动作脚本”承接：

- `AddTaskAction`：
  - 槽位：`taskService`、`task`、`timeoutSeconds`、`addOrUpdate`、`resetStatusToTodo`
  - 事件里绑定：`AddTaskAction.Invoke()`
- `RemoveTaskAction`：
  - 槽位：`taskService`、`task`
  - 事件里绑定：`RemoveTaskAction.Invoke()`
- `SetTaskStatusAction`：
  - 槽位：`taskService`、`task`、`status`
  - 事件里绑定：`SetTaskStatusAction.Invoke()`

典型用法：
- 进入第一页（onEnter）：添加“寻找钥匙”任务
- 点击继续离开某页（onContinue）：把“寻找钥匙”改为完成/移除

## 5. 场景搭建步骤（按顺序）

### 5.1 创建旁白系统根节点

1) Hierarchy 新建空物体：`_NarrationSystem`
2) 在 `_NarrationSystem` 上 Add Component：`Core.NarrationSystem.NarrationSystem`
3) 在 `_NarrationSystem` 下新建空物体：`Sequences`
4) 将 `NarrationSystem.Sequences Root` 绑定到 `_NarrationSystem/Sequences`

### 5.2 绑定 UI

前提：你已经制作好了旁白 UI（对话框 Text + Button）。

1) 在旁白 UI 根对象上 Add Component：`UI.Narration.NarrationPanelView`
2) 依次绑定槽位：
   - `Root`：旁白 UI 根对象（用于开关）
   - `Narration Text`：你的 TMP 文本
   - `Continue Button`：你的 Reach 按钮（ButtonManager）
3) 把该 `NarrationPanelView` 拖到 `_NarrationSystem/NarrationSystem.Panel View` 槽位
4) 初始建议让 UI 根对象处于隐藏（SetActive=false），由系统播放时显示

### 5.3 制作一段开场旁白（示例）

1) 在 Project 窗口右键 `Create -> Systems -> Narration -> Narration Data` 创建一个 ScriptableObject 资产，命名为 `IntroNarrationData`
2) 选中它，在 Inspector 中设置：
   - `id`：`intro_awake`
   - `pages` 添加 3 页（示例文本，可替换为你指定内容）：
     - 第 0 页：`你醒了。头还有些疼。`
     - 第 1 页：`先四处看看，找到能离开这里的方法。`
     - 第 2 页：`如果门打不开，也许需要一把钥匙。`
3) 将这个 `IntroNarrationData` 拖入 `_NarrationSystem` 上的 `Narration Database` 列表中。

### 5.4 在旁白节点绑定任务事件（示例：添加“寻找钥匙”任务）

1) 准备一个任务数据 `TaskData`：例如 `task_find_key`
2) 在 `IntroNarrationData` 的第 2 页配置：
   - `continueActionId`：填入 `intro_awake_p2_continue`
3) 在场景里创建一个空物体（建议挂在 `_NarrationSystem` 下）：`NarrationEventRouter`
4) 在 `NarrationEventRouter` 上 Add Component：`Core.NarrationSystem.NarrationEventListener`
5) 在同物体（或子物体）上 Add Component：`Core.TaskSystem.Actions.AddTaskAction`
   - `Task Service`：拖场景里的 `TaskSystem(TaskService)`
   - `Task`：拖 `task_find_key`
   - `Add Or Update`：建议勾上（防止重复触发）
6) 回到 `NarrationEventListener`：
   - 添加一个 Action Mapping
   - `actionId` 填入 `intro_awake_p2_continue`
   - `onTrigger` 事件里拖入挂着 `AddTaskAction` 的物体，并选择 `GameAction -> Invoke()`

### 5.5 将开场动画结束点接到旁白（AwakeningSequenceController）

工程已为唤醒流程增加了可绑定事件：
- `AwakeningSequenceController.onAwakeningFinished`
- `invokeFinishedWhenSkipped`（继续游戏是否也触发同一事件）

按以下步骤绑定：
1) 选中场景中负责开场唤醒动画的对象（挂了 `AwakeningSequenceController`）
2) 在组件 `Events` 分组里找到 `On Awakening Finished`
3) 新建一个空物体（建议挂在 `_NarrationSystem` 下）：`IntroNarrationAction`
4) 给 `IntroNarrationAction` Add Component：`Core.NarrationSystem.NarrationPlayByIdAction`
   - `Narration System`：拖 `_NarrationSystem (NarrationSystem)`
   - `Sequence Id`：填 `intro_awake`
5) 把 `IntroNarrationAction.NarrationPlayByIdAction.Invoke()` 绑定到 `On Awakening Finished`

运行效果：
- 唤醒动画结束 → 自动弹出旁白 UI → 鼠标可点 → 点击继续翻页 → 最后一页确认后关闭 UI 并恢复控制