用途:为 Godot 项目提供任务追踪系统的实现思路,覆盖目标(objectives)、进度推进、奖励发放与分支任务链,适用于 RPG 任务或任务制玩法。
主要能力:用 Resource 定义任务(Quest Resource、QuestObjective),任务管理器以单例(AutoLoad)形式持有接受/推进/完成/链接逻辑;通过信号驱动更新,避免在 _process 中轮询;支持击杀/收集/对话等触发节点、任务 UI 追踪、分支任务数据、任务给予者对话钩子、任务持久化、限时挑战、隐藏目标、本地化描述、任务图管理、路径点助手与任务冲突解析等脚本模块。
使用方式:强制加载 quest_resource.gd 与 quest_manager_singleton.gd,其余为支持脚本。黄金流程为 accept → event trigger → progress → complete → persist。接受任务用 QuestManager.accept_quest(quest),运行时修改需复制 Resource;事件触发通过触发节点/总线而非敌人脚本硬编码;进度用 update_objective(quest_id: StringName, …);完成后管理器清除活动任务、发出 quest_completed 并由背包/经济系统发放奖励;任务离开活动集时断开完成回调;持久化保存活动/已完成 id 映射与计数,不保存实时 Resource 图。字段统一使用 StringName,如 quest.id、objective_id,管理器字典键也用 StringName,对话钩子比较 StringName 而非自由字符串。
限制:资料给出多项 NEVER 规则,如不要把活动任务只存在 Player 节点、不要用未验证的普通字符串 id、不要忘记断开完成信号(会重复奖励)、不要在 _process 轮询目标、不要跳过任务状态存读、不要在敌人/物品脚本中硬编码任务逻辑、不要在 Quest Resource 内直接发放掉落实物、不要允许同一任务 id 重复活动实例。还提示目标数组含 null 条目时 objectives.all(...) 会崩溃,需在 is_complete() 中判空;并发进度需 Mutex 与延迟信号;前置条件通过 Inspector 中 Resource 关联任务链。具体实现与更多模式见 references/quest-patterns-deep.md,官方 API 链接按需查阅。