🕹️PlayerHUD Filter

The PlayerHUD Filter is a required companion plugin for the PlayerHUD Block. It enables item drops, trade widgets, and the compact HUD widget to be inserted directly inside Moodle course content — pages, labels, books, forums, and any other HTML-supported activity — using simple shortcodes.

👥 Who it is for: teachers already using the PlayerHUD Block who want to place item collection points, trade offers, or the player HUD widget directly inside course content, instead of relying only on the block's sidebar placement.

📋 Requirements

• Moodle 4.5 or later.
• Required dependency: the PlayerHUD Block must be installed first — this filter will not install without it and has no effect on its own.

✨ Features

• 📍 Item Drops: insert collectible item drops directly into course content — pages, labels, books, forums, and other HTML-supported activities.
• 🏪 Trade Widgets: embed a PlayerHUD NPC shop trade card inline, resolved by a short lookup code rather than a raw database ID.
• 🧩 Shortcode-Based Integration: three shortcodes ([PLAYERHUD_WIDGET], [PLAYERHUD_DROP ...], [PLAYERHUD_TRADE ...]) cover every use case.
• 🎮 Compact HUD Widget: the same player HUD shown in the block (avatar, XP, level, recent items, ranking, karma bar), embeddable anywhere a shortcode is accepted.
• ⚡ Real-Time Interaction: AJAX-based collection via Moodle's core/ajax, with no page redirect.
• 🎒 Seamless Inventory Integration: collected items post directly into the PlayerHUD inventory, respecting the same cooldown, limit and secret-item rules as the block.
• 🚀 Zero N+1 Rendering: every drop/trade code on a page is bulk-loaded in a single pass, regardless of how many shortcodes appear.
• 🔐 Server-Side Validation: cooldown, collection limits, gamification opt-out and capability checks are all enforced at render time.
• 📱 Mobile-Compatible Rendering: shortcodes render a lightweight fallback inside the Moodle app, where the AJAX flow does not apply.

🕹️ PlayerGames Ecosystem

PlayerHUD Filter is part of the PlayerGames gamification ecosystem:

• PlayerHUD Block (required): the gamification engine — XP, levels, inventory, quests, trade, and RPG progression. This filter has no effect without it.
• PlayerHUD Availability Restriction (optional): restricts activities by level or items.
• PlayerGroup (optional): lets students form their own groups from the activity page — no teacher intervention needed.

Explore the full ecosystem at jeanlucio.github.io/en/playergames.

🚀 Getting started

• Install the PlayerHUD Block first — the filter depends on it and will not install without it.
• Install PlayerHUD Filter in filter/playerhud and complete the Moodle upgrade.
• Enable the filter at Site administration → Plugins → Filters → Manage filters.
• Use the [PLAYERHUD_WIDGET], [PLAYERHUD_DROP ...] or [PLAYERHUD_TRADE ...] shortcodes inside any HTML-supported course content.

🔐 Security & Compliance

• Capability-based access control: every shortcode re-checks the view capability at render time.
• Server-side enforcement of cooldown and collection limits — the shortcode's visual state is a display concern only.
• require_sesskey() protection on the collect and trade-processing endpoints.
• Safe deserialization: stored configuration is read with unserialize_object(), never raw unserialize().
• Zero N+1 by construction: bulk pre-loading prevents query amplification even with many shortcodes on one page.
• Privacy-aware: implements Moodle's null_provider — it only displays data owned by the PlayerHUD Block and stores none of its own.

📚 Documentation and support

Full documentation — features, the shortcode syntax reference, the PlayerGames ecosystem, security details, and the full test suite — is at jeanlucio.github.io/moodle-filter_playerhud. Found a bug or have a question? Open an issue on the issue tracker.

📄 License

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

Copyright: 2026 Jean Lúcio