Feature Plan: Player Quest Progress Page

Summary

• Owner: Freddi
• Status: Discovery
• Target Release: 2025.11.x
• Backlog Entry: docs/agendas/uebliche.md → 📥 Inbox (Quest-Seite Progress Tracking)

Goals

• Give players a dedicated dashboard page summarising every active quest, stage progress, completion history, and available follow-up quests.
• Provide filtering by storyline, quest type, and status (active, repeatable, completed) so players can plan their next steps.
• Surface quest rewards, prerequisites, and blockers to reduce reliance on external wikis or staff pings.

Scope

• Define an API contract (/api/quests/progress) delivering per-player quest state (status, current stage, objectives, reward preview, timestamps).
• Build a dashboard module/page that renders quest lists, detail drawers, and progress timelines, including mobile-support layout.
• Add backend support for quest metadata (categories, difficulty, recommended power) to drive sorting/highlighting.
• Include UX for triggering quest assistance actions (e.g., set active quest, request hint, teleport to quest-giver if allowed).
• Out of scope: quest authoring tools and in-game quest tracking UI (handled elsewhere).

Implementation Outline

1. Data Model & API
   • Extend quest domain models to expose player-specific progress snapshot (active stage, objective checklist, percentage).
   • Implement /api/quests/progress (GET) returning grouped quests (main storyline, faction, daily, etc.) plus metadata for pagination.
   • Provide supporting endpoints for actions: set active quest, request hint, mark objective done (if applicable), fetch lore codex.
2. Backend Services
   • Build QuestProgressService aggregating game server state (Minestom) with persisted quest metadata in Mongo/Postgres.
   • Implement caching/invalidations when quest updates arrive from game server events.
   • Ensure permission checks so players only see their own progress; admins get impersonation ability with audit logging.
3. Dashboard Module
   • Create app/dashboard/src/modules/quests with Pinia store maintaining progress data, filters, and active quest selection.
   • Page layout: hero summary (total quests, current act progress, daily resets), tabs for Active / Available / Completed, detail drawer with stage checklist and reward overview.
   • Visual timeline for multi-stage quests; badges for difficulty and recommended group size.
4. Interactions & Assistance
   • Action buttons: set quest active (updates server), request teleport (if quest supports), copy coordinates.
   • Integrate with notifications (show toast when quest completes or hint sent).
   • Provide link to quest codex entry (if available) and embed key lore snippet.
5. Telemetry & Analytics
   • Track quest page visits, active quest switches, hint requests, and drop-off points for balancing.
   • Log API latency and failure rates for debugging.

Dependencies

• Quest tracking events from game server (Minestom plugin) delivered via existing REST/WebSocket channels.
• Quest metadata repository (likely services/gameserver/src/main/java/net/uebliche/features/quests) with categories, rewards, prerequisites.
• Dashboard routing and permission system (editor:quests.view, editor:quests.manage for admin view).
• Notification/toast infrastructure for user feedback.

Risks & Mitigations

• Incomplete quest metadata: Run audit to ensure all quests have essential fields; add placeholder handling in UI with prompts for designers.
• Real-time sync lag: Introduce optimistic UI updates with fallback refresh and manual “Sync progress” button.
• Data volume/performance: Paginate completed quests, prefetch only active & available by default, and lazy-load history.
• Spoilers: Gate future-stage info behind toggle and respect spoiler settings; for repeatables, show last completion timestamp only.

Validation Plan

• Backend unit/integration tests for progress snapshots, filtering, and action endpoints.
• Frontend tests for store state transitions, filter interactions, and detail drawer rendering.
• Stage environment QA: complete quests in-game, verify dashboard updates in near real-time, test admin impersonation view.
• Monitor API error rates, latency, and player feedback post-launch; run usability session with quest-heavy players.

Notes & Decisions

• 2025-11-05 – Initial release focuses on MVP categories (Main Story, Side, Daily). Faction/seasonal quests follow once metadata stabilises.
• 2025-11-05 – Consider integration with roadmap/achievement system later to show quest dependencies visually.

References

• Game server quest events module (to be aligned with services/gameserver/src/main/java/net/uebliche/features/quests once formalised)
• Dashboard module patterns: app/dashboard/src/modules/events, app/dashboard/src/modules/profile