godot-quest-system

必须加载

1. quest_resource.gd — StringName ID、状态、目标/奖励
2. quest_manager_singleton.gd — 接取 / 推进 / 完成 / 链接

辅助文件：kill_objective_trigger.gd、quest_ui_tracker.gd、branching_quest_data.gd、quest_giver_dialogue_hook.gd、quest_persistence_loader.gd、timed_quest_challenge.gd、hidden_objective_logic.gd、localized_quest_description.gd、quest_graph_manager.gd、quest_waypoint_helper.gd、quest_conflict_resolver.gd、quest_manager.gd（备用辅助文件——优先使用单例）。

标准流程

accept → event trigger → progress → complete → persist

检查点	操作
接取	QuestManager.accept_quest(quest) — 如果运行时会修改资源，则复制 Resource；只连接一次 quest_completed
事件触发	通过触发节点 / 总线处理击杀/收集/对话 — 不要在敌人脚本中硬编码（kill_objective_trigger.gd）
进度	update_objective(quest_id: StringName, …) — 仅使用驻留化的 ID
完成	管理器移除活跃任务，发出 quest_completed，通过库存/经济系统信号发放奖励
断开连接	任务离开活跃集合时，断开完成回调 Callable — 防止重复奖励
持久化	保存活跃/已完成的 ID 映射表和计数（quest_persistence_loader.gd）— 不保存实时 Resource 图

任务系统中绝对不要做的事

• 绝不要只将活跃任务存储在 Player 节点上 — 使用 Autoload / 持久化数据。
• 绝不要使用未经验证的普通字符串 ID — 使用 StringName / 注册表（&"kill_slimes"）。
• 绝不要忘记断开完成信号 — 否则会重复发放奖励。
• 绝不要在 _process 中轮询目标 — 应由信号驱动。
• 绝不要跳过任务状态的保存/加载。
• 绝不要在敌人/物品脚本中硬编码任务逻辑 — 使用触发器/总线。
• 绝不要在任务 Resource 内发放战利品 — 发出信号；由库存/经济系统发放。
• 绝不允许同一任务 ID 存在多个活跃实例。

字段对齐（StringName）

在主体内容和脚本中统一使用：

• quest.id: StringName
• objective_id: StringName
• 管理器字典以 StringName 为键
• 对话/任务给予者钩子比较 StringName，而不是普通字符串

专家说明（关键）

CAUTION： 数组中存在 null 条目时，objectives.all(...) 会崩溃——在 is_complete() 中进行 null 检查（参见 quest_resource.gd）。

• NavMesh 路径点 — 仅在目标变化时更新 NavigationAgent3D.target_position（quest_waypoint_helper.gd）。
• 并发进度 — 网络/并行战斗场景使用 Mutex 和延迟信号（quest_conflict_resolver.gd）。
• 前置条件 — 在 Inspector 中通过 Resource 关联任务链（branching_quest_data.gd）。

深入了解（按需加载）

任务/目标/管理器/UI 指南和高级模式 — references/quest-patterns-deep.md。

参考

渐进式披露：仅在研究特定 API 时打开官方文档链接；切换到相邻领域时再加载相关技能——不要预加载整个技能网络。

官方文档

• Resources — 为什么任务定义、目标和奖励表应放在可复用的 Resource 资源中，而不是场景局部脚本中。
• Resource — 用于在 Inspector 中编辑任务数据和分支任务链的 @export、嵌套 Resources 和复制规则。
• Singletons (Autoload) — 如何注册一个类型化的 QuestManager，使其在场景切换后继续存在，而不依附于 Player 节点。
• Autoloads versus regular nodes — 何时应使用全局任务状态，何时应将进度保存在场景拥有的数据 Resource 中。
• Using signals — 使用 quest_accepted / objective_updated 信号发出/连接模型，避免在 _process() 中轮询。
• Instancing with signals — 将生成的角色中的击杀/收集/交谈触发器连接到管理器，无需硬编码节点路径。
• Saving games — 将任务 ID 和进度计数保存为字典；切勿序列化运行中的 Quest Resource 实例。
• Internationalizing games — 在任务 Resources 中存储 tr() 键，以便本地化标题/描述，而无需创建分支 .tres 文件。
• Timer — 通过 Timer / SceneTree.create_timer 超时信号实现限时挑战的失败路径。
• Using Containers — 使用响应式 VBoxContainer 任务追踪器，仅根据管理器信号重新生成 Labels。
• StringName — 目标/任务 ID 优先使用驻留字符串，以避免普通字符串中的拼写错误未被发现。
• Scene organization — 采用信号向上发送、调用向下传递的所有权模式，确保 NPC 和敌人不负责计算任务完成情况。

相关技能

前置条件

• godot-resource-data-patterns — 自定义 Resources、复制和 Inspector 编辑模式，是任务定义和目标图所依赖的基础。
• godot-signal-architecture — 类型化的信号发出/连接、断开连接规范，以及用于击杀/收集触发器的 EventBus 路由，避免出现残留监听器。
• godot-autoload-architecture — 单例 QuestManager 跨场景切换持续存在时的启动顺序和所有权规则。

配套

• godot-dialogue-system — 任务发布者的提供任务、提醒和致谢分支应查询任务状态，并通过对话选项触发接受或完成任务。
• godot-inventory-system — 收集目标和奖励发放应将物品变更交由库存系统处理，而不是把物品堆叠逻辑写进任务脚本。
• godot-save-load-systems — 带槽位和版本号的存档流水线，用于将进行中和已完成任务字典与玩家状态一并序列化。
• godot-ui-containers — 目标追踪器和日志面板的布局与重建模式，仅由管理器信号驱动。
• godot-economy-system — 任务完成后的货币和经验值奖励去向；奖励发放逻辑应与任务资源分离。
• godot-monte-carlo-balancer — 在确定任务经济数值前，模拟奖励曲线、限时失败率和目标难度。

下游／使用方

• godot-rpg-stats — 等级门槛、经验值奖励和属性前置条件，用于解锁或完成任务接受检查。
• godot-combat-system — 死亡／击败事件通过事件总线传递给击杀目标，而不是由敌人脚本直接调用 QuestManager。
• godot-genre-action-rpg — 将任务追踪、对话钩子和奖励发放整合为一套 RPG 循环的类型组合。
• godot-navigation-pathfinding — 目标路标和指南针辅助工具会在目标变更时更新 NavigationAgent 的目标。

主索引

• godot-master — 库路由器和镜像模块入口；查找任务由哪个领域技能负责，以及它与对话、库存或存档的分工时，请打开此项。