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

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.

🖼️ Screenshots

Browse with the arrows, the dots, or the left/right keys. Click the image to zoom.

‹

›

The student's HUD sidebar: avatar, level, XP bar, and recent item stash, always in view alongside the course

1 / 3

✨ 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 Quantities: Items track a real numeric balance instead of one row per unit collected. A drop’s Quantity per collection controls how many units it grants each time (independent of its collection limit), quests can reward any quantity of their item, and trades can require/give any quantity per item. Large balances display compactly (e.g. 1.5k) throughout the Collection tab, item details, and audit history.
• 🎯 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, shown 50 players per page; a student outside the page sees their own row pinned below it, with their real position.
• 🔐 Optional Participation: Students may choose to opt in or opt out of the gamification system. A student who opts out disappears from the ranking and from the gamification section of the course profile. Hiding only from the ranking, or the teacher turning the ranking off, does not hide that profile section.
• ⚡ 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. The students table of the Reports tab shows 50 students per page and has a name search; the one-click student dropdown is kept for courses with up to 200 players.
• 🩺 Usage & Diagnostics (administrators): a site-wide page with adoption and engagement figures and a cleanup of data left by removed blocks, with a copy saved first — see Usage & Diagnostics Page.
• 🪄 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:

Student in more than one PlayerGroup group

A course can host multiple PlayerGroup activity instances, each with its own grouping. Within a single instance a student can only belong to one group, but nothing stops them from joining a group in each different instance within the same course.

When that happens, the HUD header shows the group the student joined most recently (the highest timeadded in the groups_members table), not a “primary” group or one tied to a specific instance. The Group Ranking tab has no such limitation — since it reads directly from Moodle’s native group tables, all of the student’s groups appear normally.

⚖️ 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.

Drops that are not placed yet

The figures above count every drop, but a drop only pays XP once its shortcode sits where students can see it. When the panel finds drops in no activity description, page content or the news forum, it adds a notice under the balance message with how many drops they are and how much XP they would pay, and links to Distribute Drops. That XP is part of the total above but cannot be earned until the drops are placed.

The check reads the same places as the Distribute Drops screen. A drop placed somewhere it does not look (a book chapter, a section summary, a forum post) is reported as “not found”; in that case the notice can be ignored.

🩺 Usage & Diagnostics Page

Site administrators get a page at Site administration > Reports > PlayerHUD usage and diagnostics (capability moodle/site:config). Every figure is counted on the site itself — nothing is sent outside it.

Adoption

How widely the block is used, counted per course (the block allows one instance per course):

• Courses with the block, split into courses with items, with players but no items, and with an empty block — the three add up to the total.
• Courses with each feature on: RPG mode, quests, ranking, items.
• Blocks left on user Dashboards by earlier releases, shown only when there are some. They no longer work, and each user can delete theirs in the Dashboard edit mode.

Engagement

• Players, players who turned gamification off, and the XP currently held by players.
• Over the last 90 days: players who earned XP, items received, quests completed, trades made, AI requests (per provider) and assistant runs.

Figures are cached for 10 minutes; a Refresh button recounts them.

Data integrity and cleanup

Sites that removed the block before v1.7.0 may still hold the data of those blocks, and earlier versions could leave rows behind when an item, quest, chapter, scene, trade or assistant run was deleted. None of it appears on any page or counts towards anything in the game.

• Removed block instances: one row per removed block, with its players, XP, items, activity dates and course. The course is recovered from the log when possible; instances whose course still exists start unticked, since the block may have been removed by mistake. Only the ticked ones are deleted. At most 100 are listed at a time — the rest appear after that cleanup.
• Leftovers of old deletions: described in words (e.g. “Story scenes whose chapter no longer exists”). They are always included in the cleanup, and deleting them changes nothing in the courses in use.

Deleting needs an explicit confirmation and runs in one transaction. Before deleting, a copy of every row is saved as a JSON file in the site data directory (moodledata/block_playerhud/orphan_backups/). The page lists these copies with Download and Delete buttons. The copies contain personal data (user IDs and XP) of the deleted rows, so a scheduled task deletes them automatically after 30 days (you can delete them earlier from the page), and they are removed when the plugin is uninstalled.

🎓 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: AI Hub

PlayerHUD’s optional AI features (Content Generator and Game Master Assistant) can draw on AI Hub (local_aihub, by the same author, part of the shared PlayerGames ecosystem services). When AI Hub is installed, any personal or site key a teacher or admin has already configured there is automatically available to PlayerHUD — no key needs to be re-entered. AI Hub’s keys sit between PlayerHUD’s own keys and Moodle’s core_ai fallback in the AI Provider Chain. Without AI Hub installed, PlayerHUD simply skips those two tiers and resolves from its own keys or core_ai.

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

🧩 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 recommended PlayerHUD Filter plugin (needed to place item drops via shortcodes in course content).
5. Visit Site administration > Notifications to complete installation.
6. Add the block to a course.

Administrators can follow how the block is used, and clean data left by removed blocks, at Site administration > Reports > PlayerHUD usage and diagnostics — see Usage & Diagnostics Page.

📖 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.

Removing the block from a course deletes the whole game and every student’s progress at once, and it cannot be undone from the block. Back up the course with user data first, or use Hide in the block menu to take the game out of sight without losing anything. The teacher manual (the ? button of the management panel) explains this under Removing the block.

🌱 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): 81%.

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
• Usage & Diagnostics page: aggregate figures only, counted on the site — nothing is sent outside it. A cleanup first saves a JSON copy of the deleted rows, which contains personal data (user IDs and XP), in moodledata/block_playerhud/orphan_backups/; it is deleted automatically after 30 days, earlier if an administrator deletes it from the page, and when the plugin is uninstalled

🔎 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