Quest System

Last Updated: 2025-01-16
Primary Source: docs/project_status.md
Service File: backend/src/services/quest.service.ts
Model: backend/src/models/quest.model.ts, backend/src/models/userQuest.model.ts

---

Overview

The Quest System enables the AI Director to dynamically offer, track, and complete quests, providing players with clear objectives, narrative structure, and a sense of agency.

---

Architecture

Quest System Flow

---

Quest Model

Quest Table

Model: backend/src/models/quest.model.ts

Fields:

• id - Primary key
• title - Quest title
• description - Quest description
• prerequisites - Prerequisites (JSONB)
  • quests - Array of required quest IDs
  • level - Required user level
• rewards - Rewards (JSONB)
  • items - Array of {itemId, quantity}
  • currency - Energy coins amount
  • relationshipFlags - Relationship flags to set

User Quest Table

Model: backend/src/models/userQuest.model.ts

Fields:

• id - Primary key
• user_id - User ID
• quest_id - Quest ID
• status - Quest status (available, in_progress, completed)
• progress - Progress tracking (JSONB)
• completed_at - Completion timestamp

---

Quest Status

Available

• Quest is available to the user
• Prerequisites met
• Not yet started

In Progress

• User has accepted the quest
• Quest is active
• Progress being tracked

Completed

• Quest completed
• Rewards granted
• Completion recorded in timeline

---

Quest Service

Key Functions

getQuestsForUser(userId, query)

• Fetches all quests for user
• Includes status and progress
• Filters by prerequisites
• Supports pagination

offerQuest(userId, questId)

• Offers quest to user
• Checks prerequisites
• Creates UserQuest record
• Sets status to in_progress
• Creates timeline event

completeQuest(userId, questId)

• Marks quest as completed
• Grants rewards (items, currency, flags)
• Updates timeline
• Sets completion timestamp

checkPrerequisites(userId, prerequisites)

• Validates quest prerequisites
• Checks required quests completion
• Checks required user level
• Returns boolean

---

AI Director Integration

Quest Offering

Tool Command:

{
  "offerQuest": {
    "questId": 123
  }
}

Process:

1. AI Director decides to offer quest
2. Calls questService.offerQuest()
3. Quest added to user's quest log
4. Timeline event created

Quest Completion

Tool Command:

{
  "completeQuest": {
    "questId": 123
  }
}

Process:

1. AI Director decides quest is complete
2. Calls questService.completeQuest()
3. Rewards granted automatically
4. Timeline event created
5. Status updated to completed

---

Rewards System

Item Rewards

Format:

{
  "items": [
    {"itemId": 1, "quantity": 5},
    {"itemId": 2, "quantity": 1}
  ]
}

Process:

• Calls inventoryService.modifyInventory() for each item
• Items added to user inventory
• Timeline event created

Currency Rewards

Format:

{
  "currency": 100
}

Process:

• Calls inventoryService.modifyCurrency()
• Energy coins added to user balance
• Timeline event created

Relationship Flags

Format:

{
  "relationshipFlags": [
    {"flag": "quest_completed", "value": true}
  ]
}

Process:

• Calls relationshipService.setRelationshipFlag() for each flag
• Flags stored in ASO state
• Timeline event created

---

Data Flow

---

API Endpoints

Quest Management

• GET /api/quests - Get all quests for user
• GET /api/quests/:id - Get specific quest
• POST /api/quests/:id/offer - Offer quest to user
• POST /api/quests/:id/complete - Complete quest

---

Source Files

Primary Sources:

• backend/src/services/quest.service.ts - Quest management
• backend/src/models/quest.model.ts - Quest model
• backend/src/models/userQuest.model.ts - User quest model
• docs/db_schema_quests.sql - Database schema

---

Related Documentation

• AI Director - Quest offering and completion commands
• Inventory System - Quest rewards (items and currency)
• Relationship Milestones - Quest relationship flags
• Tool System - Quest tool implementation
• Timeline System - Quest event tracking
• 00-OVERVIEW.md - Complete system overview