godot-quest-system

MANDATORY loads

1. [quest_resource.gd](scripts/quest_resource.gd) — StringName ids, status, objectives/rewards
2. [quest_manager_singleton.gd](scripts/quest_manager_singleton.gd) — accept / progress / complete / chain

Supporting: [kill_objective_trigger.gd](scripts/kill_objective_trigger.gd), [quest_ui_tracker.gd](scripts/quest_ui_tracker.gd), [branching_quest_data.gd](scripts/branching_quest_data.gd), [quest_giver_dialogue_hook.gd](scripts/quest_giver_dialogue_hook.gd), [quest_persistence_loader.gd](scripts/quest_persistence_loader.gd), [timed_quest_challenge.gd](scripts/timed_quest_challenge.gd), [hidden_objective_logic.gd](scripts/hidden_objective_logic.gd), [localized_quest_description.gd](scripts/localized_quest_description.gd), [quest_graph_manager.gd](scripts/quest_graph_manager.gd), [quest_waypoint_helper.gd](scripts/quest_waypoint_helper.gd), [quest_conflict_resolver.gd](scripts/quest_conflict_resolver.gd), [quest_manager.gd](scripts/quest_manager.gd) (alt helper — prefer singleton).

Golden path

accept → event trigger → progress → complete → persist

| Checkpoint | Action |

|---|---|

| Accept | QuestManager.accept_quest(quest) — duplicate Resource if runtime mutation; connect quest_completed once |

| Event trigger | Kill/collect/talk via trigger nodes / bus — not hardcoded in enemy scripts ([kill_objective_trigger.gd](scripts/kill_objective_trigger.gd)) |

| Progress | update_objective(quest_id: StringName, …) — interned ids only |

| Complete | Manager erases active, emits quest_completed, grants via inventory/economy signals |

| Disconnect | Disconnect completion Callables when quest leaves active set — prevent double rewards |

| Persist | Save active/completed id maps + counts ([quest_persistence_loader.gd](scripts/quest_persistence_loader.gd)) — not live Resource graphs |

NEVER Do in Quest Systems

• NEVER store active quests only on the Player node — Autoload / persistent data.
• NEVER use unverified plain string ids — StringName / registry (&"kill_slimes").
• NEVER forget to disconnect completion signals — double rewards.
• NEVER poll objectives in _process — signal-driven.
• NEVER skip save/load for quest state.
• NEVER hardcode quest logic inside enemy/item scripts — triggers/bus.
• NEVER award loot inside the Quest Resource — emit; inventory/economy grant.
• NEVER allow duplicate active instances of the same quest id.

Field alignment (StringName)

Across body + scripts use:

• quest.id: StringName
• objective_id: StringName
• Manager dictionaries keyed by StringName
• Dialogue/quest-giver hooks compare StringName, not free strings

Expert WHY (critical)

> CAUTION: objectives.all(...) on arrays with null entries crashes — null-check in is_complete() (see [quest_resource.gd](scripts/quest_resource.gd)).

• NavMesh waypoints — update NavigationAgent3D.target_position on objective change only ([quest_waypoint_helper.gd](scripts/quest_waypoint_helper.gd)).
• Concurrent progress — Mutex + deferred signals for network/parallel combat ([quest_conflict_resolver.gd](scripts/quest_conflict_resolver.gd)).
• Prerequisites — Resource-linked quest chains in Inspector ([branching_quest_data.gd](scripts/branching_quest_data.gd)).

Deep dive (load on demand)

Quest/Objective/Manager/UI walkthroughs and elite patterns — [references/quest-patterns-deep.md](references/quest-patterns-deep.md).

Reference

> Progressive disclosure: open Official Documentation links only when researching a specific API; load Related Skills when routing to a peer domain — do not preload the whole lattice.

Official Documentation

• Resources — Why quest definitions, objectives, and reward tables belong in reusable Resource assets instead of scene-local scripts.
• Resource — @export, nested Resources, and duplication rules for Inspector-authored quest data and branching chains.
• Singletons (Autoload) — How to register a typed QuestManager that survives scene changes without living on the Player node.
• Autoloads versus regular nodes — When global quest state is justified vs keeping progress on a scene-owned data Resource.
• Using signals — Emit/connect model for quest_accepted / objective_updated without polling in _process().
• Instancing with signals — Wire kill/collect/talk triggers from spawned actors into the manager without hardcoded node paths.
• Saving games — Persist quest IDs and progress counts as dictionaries — never serialize live Quest Resource instances.
• Internationalizing games — Store tr() keys on quest Resources so titles/descriptions localize without forked .tres files.
• Timer — Time-limited challenge fail paths via Timer / SceneTree.create_timer timeout signals.
• Using Containers — Reactive VBoxContainer quest trackers that rebuild Labels from manager signals only.
• StringName — Prefer interned IDs for objectives/quests to avoid silent typo failures from plain strings.
• Scene organization — Signal-up / call-down ownership so NPCs and enemies never own quest completion math.

Related Skills

Prerequisites

• godot-resource-data-patterns — Custom Resources, duplication, and Inspector authoring patterns that quest definitions and objective graphs depend on.
• godot-signal-architecture — Typed emit/connect, disconnect hygiene, and EventBus routing for kill/collect triggers without ghost listeners.
• godot-autoload-architecture — Boot order and ownership rules for a singleton QuestManager that outlives scene swaps.

Complements

• godot-dialogue-system — Quest-giver offer/reminder/thanks branches should query quest status and emit accept/complete through dialogue choices.
• godot-inventory-system — Collect objectives and reward grants should delegate item mutations to inventory, not embed stacks in quest scripts.
• godot-save-load-systems — Slot/versioned save pipelines that serialize active/completed quest dictionaries beside player state.
• godot-ui-containers — Layout and rebuild patterns for objective trackers and journal panels driven only by manager signals.
• godot-economy-system — Currency/XP reward sinks after quest completion; keep grant logic out of the Quest Resource itself.
• godot-monte-carlo-balancer — Simulate reward curves, timed-fail rates, and objective difficulty before locking quest economy numbers.

Downstream / consumers

• godot-rpg-stats — Level gates, XP rewards, and stat prerequisites that unlock or complete quest acceptance checks.
• godot-combat-system — Death/defeat events feed kill objectives through a bus instead of enemy scripts calling QuestManager directly.
• godot-genre-action-rpg — Genre composition that consumes quest tracking, dialogue hooks, and reward distribution as one RPG loop.
• godot-navigation-pathfinding — Objective waypoints and compass helpers update NavigationAgent targets when objectives change.

Master

• godot-master — Library router and mirrored module entry; open when discovering which Domain Skill owns quests vs dialogue, inventory, or save.