Echo/Assets/_Project/Docs/TaskSystem_Triggers_and_Flows.md

TaskSystem - 触发器与流程节点方案

本文档描述“任务的添加/删除/状态切换”在项目中的推荐落地方式：通过独立脚本组件（触发器/动作节点）把 TaskSystem 接入任意玩法事件、流程节点或 Timeline/动画/对话节点，而不是把逻辑写死在某个互动脚本里。

适用范围：

• 任务不一定来自交互（门、拉杆等），也可能来自剧情节点、进入区域、时间到、对话选项、成就/教程步骤等。
• 希望策划/关卡在 Inspector 中配置“触发条件 → 任务动作”，尽量减少硬编码与跨模块耦合。

相关基础系统：

• Assets/_Project/Scripts/Core/TaskSystem/TaskService.cs
• Assets/_Project/Scripts/Core/TaskSystem/TaskData.cs
• Assets/_Project/Docs/TaskSystem_Technical_Reference.md

1. 总体思路

将任务系统的“动作”拆成可复用的独立组件：

• 动作基类（GameAction）：定义统一的 public override void Invoke() 接口。
• 动作类（Task Actions）：继承自 GameAction，只做一件事，调用 TaskService 的某个 API。
  • AddTaskAction
  • RemoveTaskAction
  • SetTaskStatusAction
• 触发类（Task Triggers）：监听某个来源事件，满足条件时调用动作（通过 UnityEvent 绑定 Action.Invoke()）。
  • TriggerVolume (进入区域触发)
  • InteractFailedTrigger (交互失败触发)

这样可以保证：

• 任务系统逻辑（添加/移除/状态规则）仍然集中在 TaskService，只通过 API 进入
• 具体玩法/流程只负责“何时触发”，不负责“如何维护任务”
• 同一套任务动作能被任何系统复用（UnityEvent、Timeline、Trigger、脚本回调都能接）

2. 推荐的“任务动作”组件清单（未来要做的脚本）

以下是建议新增的脚本（都应放在 _Project/Scripts/Core/TaskSystem/Actions 或 _Project/Scripts/UI/Tasks/Actions，按你们组织习惯即可），每个脚本尽量只有一个公开入口方法，便于被 UnityEvent 调用。

2.1 AddTaskAction

用途：向任务系统添加一个任务（可选超时秒数）。

Inspector 槽位：

• TaskService taskService（槽位引用；不写死单例）
• TaskData task（要添加的任务定义）
• float timeoutSeconds = -1（<0 表示不超时）
• bool addOrUpdate = true（推荐默认 true：避免重复添加失败）
• bool resetStatusToTodo = false（可选：用于“重复触发时重置为待做”）

公开方法（示例概念）：

• public void Invoke()

内部应调用：

• taskService.AddTask(task, timeoutSeconds) 或
• taskService.AddOrUpdateTask(task, timeoutSeconds, resetStatusToTodo)

2.2 RemoveTaskAction

用途：按任务 ID 移除任务（建议用 TaskData 引用获取 id，避免手写字符串）。

Inspector 槽位：

• TaskService taskService
• TaskData task

公开方法：

• public void Invoke()

内部应调用：

• taskService.RemoveTask(task.id)

2.3 SetTaskStatusAction

用途：把某个任务置为 Completed / Expired / Todo。

Inspector 槽位：

• TaskService taskService
• TaskData task
• TaskStatus status

公开方法：

• public void Invoke()

内部应调用：

• taskService.SetTaskStatus(task.id, status)

3. 推荐的“触发器”组件清单（未来要做的脚本）

触发器组件的核心原则：

• 只监听事件 + 过滤条件 + 调用一个或多个动作
• 尽量支持 UnityEvent：让关卡/流程可以在 Inspector 里做绑定
• 必须提供“防重复触发”的选项（例如只触发一次、冷却时间、按任务是否已存在等）

3.1 OnStartTrigger / OnEnableTrigger

用途：场景开始/对象启用时自动添加任务或设置状态（替代临时的 TaskBootstrap）。

建议用法：

• 教程任务：开场添加“打开背包”“查看平板”等
• 剧情开场：进入房间后添加“寻找钥匙”

防重复建议：

• onlyOnce（触发一次后禁用自身）
• requireTaskNotPresent（任务已存在则不触发）

3.2 InteractFailedTrigger（交互失败触发）

用途：当玩家“按下交互键且条件不满足”时触发任务添加。

关键注意点：

• 不要挂在“瞄准提示”的高频检测上，否则会重复触发
• 必须挂在“按键交互尝试”的失败分支上（目前失败分支在 PlayerController 里）

推荐做法：

• PlayerController 暴露一个“交互失败事件”（UnityEvent 或 C# event）
  • 参数至少应包含：目标 collider / 交互者 / failReason
• InteractFailedTrigger 订阅该事件，并做过滤：
  • 只关心指定门/指定根物体（hit 是否在该物体层级里）
  • 可选：只对某类条件失败生效（例如 RequireUnlockedInteractCondition）

3.3 UnlockStateChangedTrigger（解锁状态变化触发）

用途：当 InteractUnlockState 变为 unlocked 时：

• 自动完成某个任务（例如“寻找钥匙”完成）
• 或移除过期任务

当前工程里 InteractUnlockState 没有事件回调，只有 SetUnlocked/Unlock/Lock 改字段并 Apply 视觉。

推荐改造方向（未来做）：

• 在 InteractUnlockState 增加 event Action<bool> Changed 或 UnityEvent<bool> onChanged
• 或者新增一个 Watcher 组件轮询 IsUnlocked（成本更低但不够优雅）

3.4 TriggerVolume / TimelineSignal / DialogueNode

用途：将任务动作接到“流程节点”上：

• 进入触发区：添加任务
• Timeline Signal：切任务状态
• 对话节点：选择某个选项后添加/移除任务

建议统一入口：

• 这些系统最终都调用 AddTaskAction/SetTaskStatusAction/RemoveTaskAction 的 Invoke()

4. 配置规范（强烈建议遵守）

4.1 不写死引用

所有动作脚本都应该用 Inspector 槽位引用：

• TaskService：拖场景里的 TaskService（或者由上层管理注入）
• TaskData：拖 ScriptableObject 资产

不要在脚本里用：

• 查找路径 transform.Find("...")
• GameObject.Find(...)
• 用字符串写 taskId（除非迫不得已）

4.2 去重策略（默认建议 AddOrUpdate）

任务添加最常见的坑是“重复触发导致重复添加/报错/刷 UI”。

推荐默认策略：

• 触发器 → 调用 AddOrUpdateTask(taskData, ...)
• 如确实需要“只添加一次”：在触发器侧增加 onlyOnce 或 requireTaskNotPresent

4.3 任务生命周期归属

建议统一归属：

• 任务的超时判定：由 TaskService（已实现）
• 任务的自动移除：由 TaskService 的 autoRemove 配置（已实现，可关）
• 任务的产生与完成：由“触发器 + 动作”拼装（关卡/流程可配置）

5. 示例：门未解锁 → 交互失败 → 添加“寻找钥匙”任务

目标：

• 门上挂了 RequireUnlockedInteractCondition，未解锁时交互失败
• 失败后添加任务 task_find_key

推荐配置：

• Scene:
  • TaskSystem（TaskService）
  • DoorRoot
    • InteractUnlockState（unlocked=false）
    • RequireUnlockedInteractCondition（failReason=“尚未解锁”）
    • InteractFailedTrigger
      • targetFailReason=“尚未解锁”（或留空）
      • onInteractFailedEvent -> 拖入下方的 AddTaskAction，选择 GameAction.Invoke()
    • AddTaskAction
      • taskService -> TaskSystem(TaskService)
      • task -> task_find_key(TaskData)

6. 临时测试与正式接入的区别

• TaskBootstrap：仅用于快速在场景启动时塞入测试任务（方便 UI 验证）
• 正式玩法：应该由“触发器 + 动作”驱动任务变化，避免 Start 时就塞进任务导致误判