godot-quest-system

name	godot-quest-system
description	Expert blueprint for quest tracking systems (objectives, progress, rewards, branching chains) using Resource-based quests, signal-driven updates, and AutoLoad managers. Use when implementing RPG quests or mission systems. Keywords quest, objectives, Quest Resource, QuestObjective, signal-driven, branching, rewards, AutoLoad.

MANDATORY loads

1. quest_resource.gd — StringName ids, status, objectives/rewards
2. quest_manager_singleton.gd — accept / progress / complete / chain

Supporting: 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 (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)
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) — 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).

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

Deep dive (load on demand)

Quest/Objective/Manager/UI walkthroughs and elite patterns — 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.