aurorabot/shared/modules/quest/CLAUDE.md

Quest Module

• Quests are event-driven. The handleEvent method is called by system event listeners (not by commands directly). It matches events by exact name or prefix (e.g., trigger ITEM_COLLECT matches event ITEM_COLLECT:101), enabling both generic and specific quest triggers.
• Max active quests is controlled by gameSettingsService, not hardcoded. Default is 3.
• assignQuest uses onConflictDoNothing -- re-assigning an already-assigned quest silently no-ops. This is intentional to avoid duplicate quest entries.
• Quest progress is a simple integer counter. The weight parameter in handleEvent allows a single event to advance progress by more than 1 (useful for bulk actions).
• Quest completion is automatic: when progress >= target during handleEvent, completeQuest is called within the same transaction. There is no manual "turn in" step.
• Rewards (xp and balance) are distributed via economyService and levelingService inside the completion transaction. The QUEST.COMPLETED event is emitted with systemEvents.emit (fire-and-forget, not async) for bot-layer notifications.
• requirements and rewards are stored as JSON columns. Always expect { target: number } for requirements and { xp?: number, balance?: number } for rewards.
• Completed quests are never deleted -- they stay in userQuests with a completedAt timestamp. getAvailableQuests excludes any quest the user has ever been assigned (completed or not).