Implementing Quest/Mission Systems for Mobile App Gamification
Quests are achievements with narrative and sequence. "Complete 3 workouts this week" is an achievement. "Follow the beginner path: first workout → 3 workouts per week → 7-day streak → first personal record" is a quest with progression. The retention difference is significant: a quest creates a story where the user is the hero.
Quest Structure
A quest consists of steps (QuestStep) executed sequentially or in parallel. Each step is a condition based on user events:
Quest:
id, title, description, icon
type: ENUM(linear, parallel, branching)
is_repeatable: BOOL -- daily/weekly missions
expires_at: nullable TIMESTAMP
xp_reward, badge_id
QuestStep:
id, quest_id, step_order
title, description
trigger_event: VARCHAR -- "workout_completed"
trigger_condition: JSON -- {"count": 3, "period": "week"}
is_optional: BOOL -- for branching quests
xp_partial_reward
UserQuestProgress:
user_id, quest_id, current_step, status: ENUM(not_started, in_progress, completed)
started_at, completed_at
step_progress: JSON -- {"step_1": {"completed": true}, "step_2": {"count": 2}}
Storing step_progress as JSON allows heterogeneous step progress without normalization. On PostgreSQL, JSONB with GIN indexing is efficient for queries.
Quest Types for Different Scenarios
Onboarding quests guide new users through key product features. "Set up profile → add first entry → invite friend → set a goal." Completed once. Critical for activation rate.
Daily/weekly missions (is_repeatable = true) provide regular reasons to return. Three new missions every Monday for the week. Random selection from a pool but weighted by user behavior: simple for beginners, harder for veterans. Requires a mission_pool with weights and selection logic.
Story quests form a chain of 5–10 steps revealed gradually. The next step is visible only after completing the previous one. Creates a long-term goal.
Branching quests let users choose a path at a fork. "Do you prefer cardio or strength training?" — the choice determines subsequent steps. Implement via QuestStep.is_optional + choice logic in UserQuestProgress.step_progress.
Progress Updates
Event-driven, synchronous with other gamification logic. On receiving a workout_completed event:
- Award XP to the user
- Update achievement progress
- Update active quest progress with matching trigger_event
- Check for step and quest completion
- Return to client
GamificationUpdate { xp_gained, level_up, achievements_unlocked, quest_step_completed, quest_completed }
All in one transaction. The client receives a ready-made set of events for animation.
Quest UX
Quest card: progress bar with steps, description of current step, reward. Don't show all steps at once for story quests — reveal the next step on completion (mystery motivates).
On step completion — inline celebration: green checkmark with animation, brief haptic, + XP toast. On quest completion — full-screen or bottom sheet with animation, reward, CTA "Start next quest."
Quest list split into tabs: "Active," "Available," "Completed." Show completed quests — users should see their progress.
Daily Missions as Retention Mechanic
Three random missions daily, generated in the morning (cron job at 00:00 in the user's local time). Easy, medium, and hard difficulty. Completion rate for the first two is high. The third is a stretch goal but achievable.
Server push at 10:00 "New missions ready" — soft reminder. Not every day — every other day if the user was active yesterday.
Timeline Estimates
Basic onboarding quests + daily missions — 3–5 days (client) + 5–7 days (backend). Full system with story quests, branching, mission randomization, and completion rate analytics — 3–4 weeks. Pricing is calculated individually.