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.

Use the sidebar to jump to any section on this page.

Source code: github.com/jeanlucio/moodle-block_playerhud

✨ Features

• 🎮 XP & Level System: Automatic level progression based on earned XP.
• 🏅 Level Tiers: Visual color-coded progression (every 5 levels).
• 🎛 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.
• 🎯 Item Powers: An item can carry a special effect beyond XP — become the student’s profile avatar, grant a deadline extension on a chosen activity (requires the optional Late Penalty plugin), or act as the collectible PlayerCoin.
• 📜 Quest System: Manual (level/XP), collection, activity-completion, trade, and chapter quests, with a built-in heuristic suggestion tool.
• 📍 Drop System: Place collectible items across course sections via shortcodes.
• 🎁 Auto Drop Distribution: Bulk-insert pending drops into the best-matching course activity in one click, with per-item undo.
• 🏪 NPC Shop: Item-to-reward exchange with configurable trade rules.
• 🏆 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/ajax.
• 🎉 Mascot Celebration Popups: Animated popups featuring the Huddy mascot mark key moments — Huddy introduces himself on the student’s first visit to the dashboard, and then celebrates leveling up (showing the level reached), beating the game (reaching 100% of the course score), completing your first quest (a one-time nudge to go claim its reward), and finding your first PlayerCoin. Fully accessible (keyboard focus trap, focus restore, screen-reader labels). The introduction, first-quest and first-PlayerCoin popups are each shown only once. All mascot art ships as lightweight WebP. Teachers can disable all mascot animations via the block’s configuration form (Mascot section).
  • Customizing the PlayerCoin: you may freely change the PlayerCoin item’s image or emoji — the popup is unaffected and always shows the mascot. The popup text, however, is fixed to the name ”PlayerCoin”, so if you rename the item, keep that name or the popup wording will no longer match.
• 🧙 RPG Characters: Define characters with portraits, reputation alignment, and multi-tier evolution images.
• 📖 Story & Chapters: Branching narrative system with choice nodes and per-character story paths.
• ⚖️ Reputation System: Moral alignment mechanic that evolves the student’s character portrait over time.
• 📊 Analytics: Audit logs, game economy tracking, a level-distribution histogram and a quest-completion chart, plus an Economy Health panel that flags an unbalanced XP budget.
• 🪄 Gamification Wizard: A step-by-step assistant that builds a course’s entire gamified structure in one run, with live progress, retry-on-failure and one-click undo per run from a history list.
  • Eleven mechanics in three tiers — Items, PlayerCoin, Avatar Pack, Trade, Ranking, Missions, Knowledge Collectible, Deadline Extension, Item RPG, RPG (characters + full story) and a hidden Secret Item, grouped into Basic / Intermediate / Advanced by how sophisticated the mechanic is, not by what it technically does.
  • Shared XP budget — keeps every generated mechanic inside the course’s level ceiling.
  • Automatic drop distribution — inserts generated items across existing course activities (or into the course’s own news forum for PlayerCoin/Secret Item).
  • Live Octalysis coverage octagon — faithful to Yu-Kai Chou’s original 8 Core Drives, geometry included, shows which motivational drives the current setup actually covers.
• 🤖 AI Tools (Optional): Two AI-powered features with a tiered provider ladder (see AI Provider Chain below):
  • Content Generator — creates items, story chapters with branching nodes, and RPG character backstories on demand.
  • Game Master Assistant — a conversational chat tab for teachers. Ask questions about game design, get suggestions, and trigger actions (create item, create quest, generate chapter) with a confirmation step before anything is saved.
• 📱 Mobile-Ready: Compatible with Moodle web services.

🏆 Group Ranking Behavior

When the group ranking is enabled, each group’s average XP is calculated only from members who are actively participating — meaning members who have both:

• Gamification enabled (enable_gamification = 1)
• Ranking visible (ranking_visibility = 1)

Members who have opted out of gamification or hidden their ranking are completely excluded from the group’s sum and count. The denominator used to calculate the average reflects only the number of active participants, not the total group size.

Practical implication: a group with many opted-out members may show a higher average than expected, because the average is computed over a smaller subset. Teachers should be aware that a group’s displayed average does not represent all enrolled members — only those actively participating in the ranking.

Integration with PlayerGroup

The group ranking reads directly from Moodle’s native group tables ({groups} / {groups_members}). It works with any Moodle group — whether created manually by a teacher or automatically via the PlayerGroup activity module.

When PlayerGroup (mod_playergroup) is installed alongside PlayerHUD, an additional integration activates inside the HUD header (not the ranking tab): the student’s group badge, group name, member count, and capacity (e.g. 3/5) are displayed at the top of the block. This information is fetched via PlayerGroup’s public API (\mod_playergroup\api\group_info) and is only available for groups created through PlayerGroup activities — manually created Moodle groups are not shown there.

The two features are independent:

⚖️ Economy Health Panel

The Config tab in the management panel includes an Economy Health widget that compares the total XP a student can earn (all items × their drop limits + quest rewards) against the configured XP cap (XP per level × number of levels).

The widget also shows a collapsible breakdown table listing every item and quest with its individual XP contribution, making it easy to identify which content is over- or under-contributing to the economy.

🎓 Educational Purpose

PlayerHUD is designed to:

• Encourage active engagement
• Reinforce mastery-based progression
• Provide structured reward systems
• Support competitive and cooperative learning dynamics
• Allow voluntary participation in gamification

Suitable for:

• Gamified academic courses
• Technical and vocational training
• Certification pathways
• Engagement reinforcement strategies

🕹️ PlayerGames Ecosystem

PlayerHUD is part of the PlayerGames gamification ecosystem. Together, these plugins transform Moodle into an immersive experience:

• PlayerHUD Filter: Enables item drops via shortcodes inside course content. 👉 https://github.com/jeanlucio/moodle-filter_playerhud

• PlayerHUD Availability Restriction: Restricts access to course activities based on the student’s current level or collected items. 👉 https://github.com/jeanlucio/moodle-availability_playerhud

• PlayerGroup: Lets students autonomously form their own groups directly from the activity page — no teacher intervention needed. 👉 https://github.com/jeanlucio/moodle-mod_playergroup

🧩 Optional Integration: Late Penalty

The Deadline Extension item power (see Features) does not work on its own — it requires the separate Late Penalty plugin (local_latepenalty, by the same author, but not part of the PlayerGames family). When installed, redeeming a Deadline Extension item pushes back the activity’s effective deadline for that student and triggers Late Penalty’s automatic recalculation, waiving or reducing any late-submission grade penalty already applied. Without Late Penalty installed, the item power fails gracefully with a “not installed” message instead of granting the extension.

👉 https://github.com/jeanlucio/moodle-local_latepenalty

📦 Requirements

🛠️ Installation

1. Download the .zip file or clone this repository.
2. Extract the folder into your Moodle blocks/ directory.
3. Rename the folder to playerhud (if necessary). Final path: your-moodle/blocks/playerhud/
4. Install the required PlayerHUD Filter plugin.
5. Visit Site administration > Notifications to complete installation.
6. Add the block to a course.

📖 Usage

1. Add the PlayerHUD Block to your course.
2. Access the Management Panel (Teacher role required).
3. Choose how to set it up:
   • Quick start: run the Gamification Wizard to auto-generate items, quests, ranking, and other mechanics in one pass (see Features above).
   • Manual setup: configure each mechanic yourself:
     • Items
     • XP values
     • Number of levels
     • XP thresholds
     • Drop placements
     • Recharge time (Cooldown)
     • Collection limits
4. Students collect items directly within course sections.
5. XP, levels, and ranking update automatically.

🌱 Demo Environment (Quick Start)

The plugin includes two CLI seed scripts that create a fully configured demo course in minutes — useful for local development or for evaluating the full feature set without manual setup.

What is created:

• 1 course (playerhud-demo) with 3 sections and completion tracking
• 1 teacher (seed_teacher) + 5 students (seed_alice … seed_eve)
• 3 RPG classes with 5-stage evolving portraits: Warrior, Mage, Rogue
• 5 items with different XP values, cooldowns and collection limits
• 5 drops embedded in course activities via shortcodes (card, image and text render modes)
• 9 quests covering every completion type (level, total XP, unique/specific items, trades)
• 2 story chapters with branching choices and reputation effects
• 2 trade offers (NPC shop), one of them already completed by a student
• A group ranking squad (3 of the 5 students grouped, 2 left ungrouped on purpose)
• A “Deadline Extension” item wired to a real, already-applied Late Penalty deduction — only seeded if local_latepenalty is installed
• Pre-seeded inventory, quest logs and activity completions — ranking is ready to browse immediately

Resulting ranking after seed:

Usage:

# Run once
php blocks/playerhud/cli/seed.php --password=YourDevPassword

# Wipe and recreate from scratch
php blocks/playerhud/cli/seed.php --password=YourDevPassword --reset

# Bypass the non-development-site guard (custom dev domains)
php blocks/playerhud/cli/seed.php --password=YourDevPassword --force

The --password flag is required and sets the login password for all seed accounts. The script refuses to run on non-development URLs (localhost, *.local, *.test) unless --force is passed.

Via Docker Compose: docker compose exec <webserver-service> php blocks/playerhud/cli/seed.php --password=YourDevPassword

🧪 Automated Tests

PlayerHUD ships with an extensive test suite covering both business logic (PHPUnit) and browser acceptance (Behat). Every CI push runs against the full matrix (Moodle 4.5 → 5.x, PostgreSQL & MariaDB).

PHPUnit — Unit & Integration Tests

Local Business-Logic Tests (tests/local/)

Web Services Tests (tests/external/)

Controller Tests (tests/controller/)

Output / Renderer Tests (tests/output/)

vendor/bin/phpunit --testsuite block_playerhud

Overall line coverage (moodle-coverage, PHPUnit + Xdebug): 42%.

Full test-by-test breakdown and coverage table →

🔐 Security & Compliance

• Capability-based access control
• Server-side validation of recharge time and limits
• require_sesskey() protection
• Moodle External API compliant
• Privacy-aware ranking participation

🔎 Third-party Service Disclosure

PlayerHUD includes optional AI-powered features: a Content Generator (items, chapters, class backstories) and a Game Master Assistant (a conversational chat for teachers that can also trigger game actions).

Is the AI feature required?

No. The plugin works fully without any external AI service. All content can be created manually inside Moodle. The AI features are productivity tools — the assistant also accepts confirmation before saving anything.

AI Provider Chain

PlayerHUD resolves the AI provider tier by tier, following the shared PlayerGames ecosystem ladder. An explicitly configured key always wins over the institutional default; core_ai sits at the bottom.

Resolution ladder (highest priority first):

Tier-first, not provider-first. Each tier above is evaluated as a whole: the first tier that holds any key is used exclusively. So a teacher’s own personal key (tier 1) always wins over a hub key (tier 2) — even a hub key for a higher-priority provider. For example, a teacher’s own custom-endpoint key is not overridden by a Gemini key that happens to live in the hub. core_ai is consulted only when no tier holds a key.

Within the chosen tier, the direct providers are tried in the order Gemini → Groq → OpenAI-compatible (first key found is used; if its call fails, the next is tried).

This also means: if a teacher configured their own key in the AI Hub, PlayerHUD uses it automatically — no need to re-enter the key in PlayerHUD.

Supported Direct Providers

• Google Gemini — https://ai.google.dev/
• Groq — https://console.groq.com/
• OpenAI-compatible APIs — Any provider that follows the OpenAI API format (e.g. OpenRouter, self-hosted models via LM Studio, Ollama proxy, etc.)

These services operate under their own terms of service and privacy policies.

How to obtain an API key

API keys must be created directly on the provider’s official website:

• Google Gemini: https://ai.google.dev/
• Groq: https://console.groq.com/
• OpenAI-compatible: refer to your specific provider’s documentation

Both Gemini and Groq currently offer free usage tiers. However, pricing policies may change and paid plans may apply depending on usage limits.

The PlayerHUD plugin does not provide API keys.

Where API keys are configured

API keys may be configured through any of the following sources (in decreasing priority):

1. PlayerHUD personal key — set by each teacher individually in the Configurações tab of the management panel.
2. AI Hub personal key — set by each teacher in local_aihub → My AI keys (if the hub is installed).
3. PlayerHUD site key — set by the site admin in Site administration → Plugins → Blocks → PlayerHUD.
4. AI Hub site key — set by the site admin in local_aihub settings (if the hub is installed).
5. Moodle core_ai — configured by the site admin in Site administration → AI → AI providers (no key stored in PlayerHUD; used only when no key above is set).

Data Transmission

When the AI feature is used, user-entered prompts are transmitted to the selected provider for processing.

The plugin:

• Does not store prompts or conversation history (chat history is session-only, in the browser)
• Does not store raw AI responses
• Only stores the game objects created inside Moodle (items, quests, chapters)

No external communication occurs unless an AI feature is explicitly used.

Demo Credentials

Not applicable — PlayerHUD requires no credentials to install or use. Every AI feature is entirely opt-in and the block works fully without any key configured.

📄 License

This project is licensed under the GNU General Public License v3 (GPLv3).

Copyright: 2026 Jean Lúcio