Skip to main content
The Quest system is the core feature of Quest Hunter, allowing you to discover and complete location-based adventures. Each quest consists of multiple locations you must visit in order, earning XP as you progress.

​
Quest Structure

Every quest in Quest Hunter includes the following properties:

Basic Information

  • Name: Quest title displayed in the app
  • Description: Detailed overview of what you’ll experience
  • Image URL: Visual representation of the quest

Quest Metadata

  • Estimated Time: Duration in minutes
  • Difficulty Level: einfach, mittel, or schwer
  • XP Reward: Points earned upon completion
  • Category: Quest theme (see below)

​
Quest Categories

Quests are organized into six distinct categories, each offering unique experiences:
Action-packed quests focused on exploration and discovery. These quests often take you off the beaten path to find hidden gems and exciting locations.
Learn about historical landmarks, events, and cultural heritage. Perfect for discovering the stories behind your city’s most important sites.
Experience art, museums, theaters, and cultural institutions. These quests immerse you in the artistic and cultural fabric of your area.
Explore parks, gardens, natural landmarks, and outdoor spaces. Ideal for those who want to connect with nature while completing quests.
Discover culinary hotspots, local restaurants, food markets, and gastronomic experiences. A delicious way to explore your city.
Visit cafes, bars, breweries, and other beverage-focused locations. Perfect for social quests with friends.

​
Difficulty Levels

Quests are rated on three difficulty levels based on physical demands, complexity, and time commitment:
DifficultyGermanCharacteristics
EasyeinfachShort duration, simple navigation, minimal physical effort
MediummittelModerate duration, some navigation skills needed, average fitness
HardschwerLonger duration, complex routes, higher physical demands
Difficulty levels help you choose quests that match your available time, fitness level, and experience with location-based navigation.

​
XP Rewards

Each quest awards experience points (XP) upon completion. XP values are defined per quest and typically correlate with:
  • Quest difficulty level
  • Number of locations to visit
  • Estimated time to complete
  • Overall complexity of the challenge
XP is only awarded when you successfully complete all locations in a quest and mark it as finished. Partial completion does not earn XP.

​
Quest Lifecycle

Understand how quests progress from discovery to completion:

​
1. Discovery

You can discover quests in multiple ways:
  • Recommended: Quests you haven’t completed yet
  • New: Quests created within the last 7 days
  • Done: Quests you’ve already completed
The quest list filters are implemented in convex/quests.ts:31-91: 
// Recommended quests exclude completed ones
export const listRecommended = query({
  handler: async (ctx) => {
    const completedQuestIds = deriveCompletedQuestIds(userQuests);
    return allQuests.filter((quest) => !completedQuestIds.has(quest._id));
  },
});

// New quests are those created in the last 7 days
export const listNew = query({
  handler: async (ctx) => {
    const cutoff = Date.now() - SEVEN_DAYS_MS;
    return allQuests.filter(
      (quest) => quest._creationTime >= cutoff && !completedQuestIds.has(quest._id)
    );
  },
});

​
2. Starting a Quest

When you start a quest:
  1. A userQuests record is created with a startedAt timestamp
  2. You cannot start the same quest twice
  3. You’re navigated to the first location automatically
Starting a quest is tracked in the database but doesn’t award any XP. You must complete all locations to finish the quest.

​
3. In Progress

Once started:
  • The quest appears in your “in progress” list
  • You can resume from your last completed location
  • You can cancel the quest at any time (progress is saved)
  • Each location must be visited in order

​
4. Completion

To complete a quest:
  1. Visit all locations in sequential order
  2. Complete photo verification at each location
  3. Mark the quest as complete after the final location
  4. Receive your XP reward
The completion logic validates all locations are done (convex/quests.ts:172-188): 
const requiredIds = new Set(questLocations.map((l) => l._id));
const completedIds = new Set(completedLocations.map((cl) => cl.locationId));
if ([...requiredIds].some((id) => !completedIds.has(id)))
  throw new ConvexError("Quest not finished");

​
Quest Details Screen

When you view a quest, you’ll see:
  • Quest image (16:9 aspect ratio)
  • Metadata: estimatedTime · category · difficulty · xp
  • Full description
  • Start or Continue button (depending on status)
Example metadata display from app/(tabs)/(quests)/[id]/index.tsx:113-118: 
{[
  `${quest.estimatedTime} min`,
  capitalize(quest.category),
  capitalize(quest.difficulty),
  `${quest.xp} XP`,
].join(" · ")}

​
Best Practices

Choose Wisely

Select quests that match your available time and fitness level. Check the estimated time and difficulty before starting.

Plan Your Route

Review the quest details and location count before heading out. Some quests require specific travel arrangements.

Check the Weather

Nature and outdoor quests are weather-dependent. Choose indoor quests (culture, food, drinks) for rainy days.

Complete in Order

Locations must be visited sequentially. You cannot skip ahead to later locations in the quest.

Build docs developers (and LLMs) love

Get started for freeTalk to us