⚠️ Required Companion Plugin: PlayerHUD requires the PlayerHUD Filter to be installed and enabled. Without it, item drops will not render in course content.

PlayerHUD – Structured Gamification Engine for Moodle

The PlayerHUD Block is a modular gamification system for Moodle that introduces structured progression mechanics based on XP, Levels, Inventory, and Ranking.

It provides a dynamic HUD (Head-Up Display) inside courses, allowing students to track their progress in real time while teachers configure engagement mechanics aligned with pedagogical objectives.

✨ Features

• 🎮 XP & Level System: Automatic level progression based on earned XP.
• 🏅 Level Tiers: The level badge changes color at every 5-level milestone (e.g., 5, 10, 15, 20), giving students a visual sense of progression.
• 🎛 Configurable Progression: Teachers define the number of levels and XP required for each level.
• 🎒 Inventory System: Collectible items with configurable Cooldown (Recharge Time) and usage limits.
• 📜 Quest System: NEW Create manual, collection, activity, reputation, and chapter quests with a built-in auto-suggestion tool.
• 🎭 RPG Characters: NEW Students choose characters with unique portraits, lore, and tiers. Items can be restricted to specific characters.
• 📖 Story & Chapters: NEW Interactive branching narratives with scenes, choices, and chapter progression tied to quests.
• 🏪 NPC Shop & Trades: Allow students to exchange collected items for rewards using a secure, rules-based transaction system.
• 📊 Analytics & Reports: Comprehensive audit logs, game economy tracking, progress visualization, and quest completion charts.
• 📍 Drop System: Place collectible items across course sections (labels, pages, descriptions) using shortcodes provided by the PlayerHUD Filter.
• 🎁 Auto Drop Distribution: NEW Automatically distribute item drops to all enrolled students with undo support.
• 🏆 Ranking System: Leaderboard with tie-breaker logic and visibility controls.
• 🔐 Optional Participation: Students may choose to opt in or opt out of the gamification system.
• ⚡ Real-Time Updates: AJAX-based collection using Moodle’s core API.
• 🤖 AI Generator Tools: Optional productivity tools for generating items, story scenes, and character oracles.
• 📱 Mobile-Ready: Compatible with Moodle web services.

🎓 Educational Purpose

PlayerHUD is designed to encourage active engagement, reinforce mastery-based progression, and support competitive/cooperative learning dynamics while keeping pedagogical integrity intact.

📖 Usage

1. Install the PlayerHUD Filter and enable it in your site's filter settings. This step is required before using the block.
2. Add the PlayerHUD Block to your course.
3. Access the Management Panel (Teacher role required) and consult the dedicated Teacher Help page NEW for Game Masters.
4. Configure:
   • Items and XP values
   • Number of levels and XP thresholds
   • Drop placements and Auto drop distribution NEW
   • Quests, RPG Characters, and Stories NEW
   • NPC Trades and exchange rules
   • Recharge time (Cooldown) and Collection limits
5. Students collect items directly within course sections, complete quests, progress through the story, and trade in the Shop.
6. XP, levels, and ranking update automatically. Monitor everything via the Reports tab.

🔗 Ecosystem Integration

• PlayerHUD Filter (Required)
• PlayerHUD Availability Restriction (Optional) — Restricts access to activities based on the student's Level or items.

🔎 Third-party Service Disclosure (AI)

PlayerHUD includes optional AI-powered features for generating items, story scenes, and character oracle responses. These features are not required. The plugin works fully without any external AI service.

• Supported Providers: Google Gemini, Groq, and custom OpenAI-compatible APIs NEW.
• Bring Your Own Key (BYOK): The plugin does not provide API keys. Keys and custom Base URLs must be configured by the institution.
• Data Privacy: No student data, prompts, or raw responses are stored. Data is only transmitted when a teacher explicitly uses the feature to generate course content.

⚙️ Technical Reliability & Security

• Core Standards: Fully compliant with Moodle coding and accessibility (WCAG 2.1 AA) standards.
• Robust Architecture: Capability-based access control, strict require_sesskey() protection against CSRF, rigorous server-side validation for game rules, and automated test coverage (including new PHPUnit coverage for RPG tables NEW).
• Data Security & Privacy: Full implementation of the Moodle Privacy API (GDPR compliant), Backup & Restore support (now extended to all RPG tables NEW), and privacy-aware ranking participation.
• Scalable & API Ready: Optimized database structure with memory-efficient bulk queries that avoid redundant database calls, and fully Moodle External API compliant.
• Bring Your Own Key (BYOK): The plugin does not provide API keys. Keys must be configured by the site administrator or individually by teachers.