PlayerWords is a word-guessing vocabulary activity for Moodle. Students guess a hidden word letter-by-letter within a configurable number of attempts, receiving colour-coded and symbol feedback on each guess.

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

✨ Features

• 🟩 Word-Guessing Gameplay: Colour-coded + symbol feedback per letter (correct position, wrong position, absent). Each attempt is a row of individual letter boxes — click any one to fix a specific letter without retyping the whole word, or move between boxes with the Left/Right arrow keys, the same verification-code-input convention as a bank 2FA field — and typing works from a physical keyboard even before clicking into a box.
• 📖 Glossary Integration: Import concepts from one or all course glossaries as the word pool, with definitions used as hints.
• ✂️ Split Multi-Word Concepts (optional, off by default): A multi-word glossary concept (e.g. “Operating System”) can be split into separate single-word candidates. Off by default to favour clue quality — when disabled, that concept is simply left out of the pool instead of producing isolated words that do not always make sense to guess on their own.
• 🚧 Configurable Stopwords: A per-activity, comma-separated list of words (e.g. “the, of, and”) to ignore when splitting a multi-word glossary concept into candidates — so a concept like “Kingdom of the Netherlands” can still yield the meaningful term instead of also drawing “of” and “the” as separate one-off words. Only relevant while splitting concepts above is enabled.
• 🤖 AI Word Generation (Optional): Generate candidate words and hints for a given topic via AI Hub (local_aihub) or Moodle’s core_ai fallback. Generated words are treated as untrusted input — only single-token, purely alphabetic terms within the configured length bounds are saved, and they enter the pool pending teacher approval.
• ✍️ Manual Word Pool: Teachers can add, edit, approve, and delete words directly from the management page.
• 🔀 Word Modes: Random word per round (default) or shared sequence mode, where every student receives the same words in the same order.
• 🚧 Restrict Guesses to the Word Pool (Optional): When enabled, a guess is only accepted if it matches one of the activity’s own approved words; any other letter combination of the right length is rejected without spending an attempt. Disabled by default — any letter combination of the right length is accepted, real word or not. Locked once the activity has recorded a real grade, alongside the other scoring-affecting settings.
• 🎲 Word Rotation: In random mode, the same word never repeats on the very next round for a student, unless it is the only word left in the pool.
• 🚫 Duplicate Prevention: The same word text can only exist once per activity pool, regardless of which source added it — a manual entry blocks a colliding glossary import (and vice versa), so random selection is never skewed toward one accidentally-duplicated word.
• 🔤 Manual-Word Validation: A manually added or edited word must be letters only; the form rejects numbers, spaces, and special characters at input time instead of silently accepting a word the game could never actually draw.
• 🧩 Fragmented-Concept Warning: A multi-word glossary concept (e.g. “Second World War”) split into several single-word entries is flagged in the word management table, since each sibling word still carries the full original concept’s definition as its hint.
• 🔍 Live Eligible-Words Count: The settings form shows, live via AJAX, how many words currently fall within the configured length range — against the real pool while editing an existing activity, or a preview of the selected glossary’s content while creating a brand-new one — so a teacher never publishes a range that silently empties the pool.
• ⚠️ Inactive-Words Warning: The game screen tells whoever manages the activity, by name, which approved words are currently excluded from play — outside the configured length range, or containing a character the game cannot use — alongside a standing count of active words. A student never sees this.
• 🎯 Draw-Count Tracking: The word management table shows how many times each word has actually been drawn into a round, counted live from attempt history — no recompute step needed.
• 💡 Hidden Hint System (Toggleable): Hint is hidden by default; students must explicitly reveal it (optionally at an item cost via PlayerHUD). Teachers can turn the reveal-hint mechanic off entirely for the activity — the reveal-hint button then never appears, even for words that have a hint configured.
• 🏳️ Give Up: Students can forfeit the current round at any time — the correct word is revealed immediately.
• ⏱️ Configurable Cooldown: Minimum wait between rounds (minutes, hours, or days), always recomputed from the activity’s current setting — a teacher’s change applies immediately, even to a cooldown already in progress.
• 🔢 Round Limit: Teachers can cap the total number of rounds per student (1–10 or unlimited). Students see a rounds-played counter (e.g. “3 / 10” or “3 / ∞”) both in the lobby and after each round.
• 🛡️ Round-Limit Integrity: A round abandoned mid-play (closed tab, lost session) still counts against the round limit — reserved the moment it starts, not only once it finishes, so it can never grant a free re-roll.
• 🔡 Accent-Insensitive Matching: Diacritics are always stripped before comparing guess and target.
• ⌨️ Accent Picker on the Virtual Keyboard: Long-pressing a key with accented variants (most vowels, plus C, N and S) on the on-screen keyboard opens a popup with those variants, mirroring a mobile keyboard’s own long-press behaviour — sliding the finger picks a variant, releasing confirms it. Covers Portuguese, Spanish, French, Italian and German diacritics (including Ç, Ñ and ß); alphabets outside that set (Nordic, Slavic, Turkish, Icelandic…) are a possible future addition, not covered today. Purely cosmetic: guess matching stays accent-insensitive throughout.
• ⌨️ Keyboard Reflects Guess History: Virtual keyboard keys are colored with the best state (correct, present, or absent) seen for that letter across every guess in the round. “Ç” and “C” always stay in sync with each other, since they count as the same letter for the game.
• ✅ True-Spelling Reveal: When a round ends (win, loss, or forfeit), the word is shown with its real, accented spelling from the word bank, even if the winning guess was typed without accents.
• 📊 Grading Methods: Highest grade, average grade, first attempt, last attempt, or average over all required rounds.
• ⚖️ Configurable Scoring Mode: Choose Binary (all-or-nothing) or Linear (proportional to attempts spared) independently for the grade and for the ranking — see Grading & Ranking. Locked once the activity has recorded a real grade, so every round is guaranteed to be scored under the same rules.
• 🧮 Grading Transparency: Students see the active grading method before playing and their live computed grade after each round, the same way mod_quiz communicates its own grading method.
• 📋 Gradebook Integration: Grades are written automatically on every round completion.
• ✅ Custom Completion Rule: Minimum number of attempts completed, evaluated and applied immediately after each round.
• 🔄 Course Reset Support: “Reset course” clears student attempts and resets grades for the activity, scoped to the target course only.
• 🏆 Top 5 Ranking: Leaderboard scoped to the activity, deliberately capped to the top 5 — never a public ranking of the whole class — with an outsider row so a lower-ranked student still sees their own real position. Respects SEPARATEGROUPS.
• 📋 Attempt History: Students can review every finished round of their own — word, attempts used, time, score, and date — plus their currently computed grade, at any time via the toolbar. Whoever can manage the activity sees that same page too (including their own attempts, if any), plus a separate paginated, sortable, per-student-filterable report covering every student — see Grading & Ranking.
• 🗑️ Attempt Deletion: From the all-students report, whoever can manage the activity can delete attempts individually or in bulk (with a select-the-current-page option). The affected student’s grade is recalculated automatically, including unlocking activity settings that lock once a real grade exists, if every one of their attempts is removed. Already-granted PlayerHUD items are not reverted automatically — an on-page notice covers this whenever the activity grants items for winning.
• ❓ In-Game Help: A dedicated help page explains the letter-feedback colours, attempts, hints, timer, and the activity’s grading method.
• 👋 First-Visit Onboarding: The how-to-play modal opens automatically the very first time a user visits any PlayerWords activity on the site — once, ever, site-wide rather than per course or per instance — and never repeats after that; the toolbar help icon always reopens it on demand.
• ♿ Accessibility: WCAG AA contrast on all grid states; non-colour indicators (✓ correct, ~ present); every cell has its own aria-label, including its position while still empty; a live region announces state changes for screen readers.
• ⚡ AJAX-Powered: Every round transition (guess, hint, forfeit, timeout, start, new round) happens without a page reload.
• 🔔 Toast Feedback: Round-flow outcomes (winning, losing, an insufficient PlayerHUD balance) surface as brief, auto-dismissing toast notifications instead of blocking dialogs, keeping the student in the round.
• 🎮 PlayerHUD Integration (Optional): Require inventory items to start a round or to reveal a hint, with atomic FIFO consumption. The student’s current balance against the required quantity is always shown up front, and the action is disabled — not just rejected after the click — when they can’t afford it; a cost pointing at a deleted or another course’s item is waived rather than locking the student out. Can also grant an item for each round won; matching PlayerHUD’s own anti-farming rule, no XP is awarded from that item while the activity allows unlimited rounds — the item is still delivered, just without XP — and the potential win-grant XP is reflected in PlayerHUD’s own “Total XP in the game” ceiling estimate.
• 🛡️ Safe Cross-Course Integration: Every PlayerHUD item reference is validated against the course’s own block instance, never a stale or another course’s item — even after backup/restore or course duplication. Settings preserve a disabled or deleted item as a clearly labelled option instead of silently resetting the field.
• 🔔 PlayerHUD Dependency Awareness: When PlayerHUD is installed on the site but hasn’t been added to the current course yet, the settings form explains that the integration will appear once the block is added. When the block_playerhud plugin isn’t installed anywhere on the site, the site administrator sees an equivalent notice on the plugin’s own settings page — mirroring the disclosure filter_playerhud and availability_playerhud already give, without making PlayerHUD a hard installation requirement.
• 📦 Backup & Restore: Full Moodle 2 backup/restore support, including the “Duplicate activity” action, word pool, attempts, user/glossary id remapping, and safe PlayerHUD item remapping (dropped rather than kept pointing at another course’s item when it isn’t part of the same restore).
• 🔐 Privacy API: GDPR/LGPD compliant — complete data export and deletion for all stored personal data.

🎓 Educational Purpose

PlayerWords is designed to:

• Reinforce learning of concepts covered in the course or subject
• Foster playful, game-based learning experiences
• Simplify and make learning and assessment dynamics more intuitive
• Contribute to achieving educational goals across different courses and disciplines
• Promote active learning methodologies, including game-based learning and gamification
• Support retrieval practice — students must recall a concept from memory before seeing any answer, one of the most effective techniques for long-term retention
• Encourage spaced practice — the configurable recharge time between rounds brings students back to the content across multiple sessions, aligning with the principles of spaced repetition

Suitable for:

• Any course that uses concept-based terminology
• Gamified academic courses using the PlayerGames ecosystem
• Formative assessment and self-study reinforcement
• Engagement reinforcement strategies

🕹️ PlayerGames Ecosystem

PlayerWords is part of the PlayerGames gamification ecosystem for Moodle. Its main direct integration is with the PlayerHUD block:

• PlayerHUD Block (Optional, v1.7.1+): Configure item costs for starting a round or revealing a hint, and an item grant for each round won.

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

• PlayerGroup (Compatible): Standard Moodle groups — created manually or via the PlayerGroup activity — are honoured by the ranking’s SEPARATEGROUPS filtering.

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

See the PlayerGames hub for the full plugin family.

🧩 Optional Integration: AI Hub

PlayerWords’ optional AI Word Generation feature 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 PlayerWords — no key needs to be re-entered. PlayerWords never contacts an AI provider directly; without AI Hub installed, it falls back to Moodle’s own core_ai subsystem, routing to whatever provider the site administrator has configured there instead.

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

📦 Requirements

🛠️ Installation & Configuration

1. Download the .zip file or clone this repository.
2. Extract the folder into your Moodle mod/ directory.
3. Rename the folder to playerwords (if necessary). Final path: your-moodle/mod/playerwords/
4. Visit Site administration > Notifications to complete installation.
5. Add a PlayerWords activity to any course.

This plugin has no site-level settings for an admin to configure — every setting is configured by the teacher when adding the activity to a course, as covered in Usage below. If block_playerhud isn’t installed on the site, the plugin’s own settings page under Site administration → Plugins → Activity modules → PlayerWords shows an informational notice about it — there’s nothing to configure there either way.

📖 Usage

1. Add a PlayerWords activity to your course.
2. Configure:
   • Word length range and maximum attempts
   • Cooldown between rounds and round limit
   • Whether hints are allowed at all
   • Word mode (random or shared sequence)
   • Grading method and gradebook settings
   • Word sources (manual, Glossary), Glossary source, and a stopword list to skip when splitting multi-word glossary concepts (all optional) — AI generation is always available on the Manage words page, independent of these source checkboxes
   • PlayerHUD item costs and win grant (optional, when PlayerHUD block is present)
3. Open the Manage words page to add, generate with AI, approve, edit, or delete words.
4. Students play directly from the activity page — guessing, revealing hints, and forfeiting rounds, with no page reload. The page’s own toolbar gives access to the rules (help), attempt history, and the ranking.
5. Grades and ranking update automatically after each round.

🧮 Grading & Ranking

PlayerWords computes a grade and a ranking total from the same finished rounds, but the two are configured completely independently — a teacher can keep the grade simple while still rewarding efficient play in the ranking, or the other way around.

Both are entirely optional, and each is switched on or off on its own:

• Grade: leave the standard Grade field set to None to run the activity fully ungraded — no grade is ever computed or written to the gradebook, and the Grading method / Grade scoring settings disappear from the form.
• Ranking: leave Show ranking set to No to hide the ranking everywhere — in-game, on the dedicated ranking page, and the extra column in the attempt history — and the Ranking scoring setting disappears from the form too.

Turning one off never affects the other: an activity can be graded with no ranking, ranked with no grade, both, or neither.

Per-round scoring decides how much a single round is worth, chosen separately for the grade and for the ranking (Grade scoring / Ranking scoring settings, both default to Binary). The grade is scored against the activity’s own configured maximum grade; the ranking always uses its own fixed 100-point base, completely independent of the grade — even when the activity has no grade at all (Grade = None, the form’s default), the ranking still works normally:

Linear gives full credit on the first two attempts — a confident second guess is not treated as less deserving than a first-try one, since this is a non-punitive educational game rather than a luck-based guessing contest — then scales the remaining attempts down proportionally, never fully zeroing out a win: even winning on the very last allowed attempt still earns a positive share. Example with 6 maximum attempts — the grade column assumes a 100-point maximum grade, but the ranking column is exactly this in any activity, even one with no grade configured at all:

With Maximum attempts set to 2 or fewer, Linear is numerically identical to Binary — every allowed attempt already falls within the full-credit plateau.

Combining several rounds into one final grade is a separate setting, Grading method (highest grade, average grade, first attempt, last attempt, or average over all required rounds). It works the same regardless of whether the per-round scoring above is Binary or Linear: it only ever aggregates whatever value each round already recorded.

The ranking is the sum of every finished round’s ranking points for a student (SUM), ordered highest first; ties are broken by fewer attempts used on average, then less time spent on average. It only appears when the teacher enables “Show ranking”, and never reveals a round still in progress.

Only the top 5 are shown — deliberately, not a bug: both the in-game ranking widget and the dedicated ranking page cap the list at 5 rows, to avoid publicly ranking every student in the class. A student ranked lower still sees exactly where they stand: an extra row, separated by “…”, shows their own real position and score, without exposing anyone else’s rank below 5th. Anyone who can manage the activity (editingteacher, manager) never appears in the ranking at all, even if they play the activity themselves — the same way their own attempts are excluded from the attempt report below.

“Show ranking” only controls visibility, not data collection: ranking points are computed and stored for every finished round regardless of whether the setting is on or off at the time. Turning it on after students have already played reveals the full total accumulated since the activity started, not just the points earned from that moment forward — nothing is lost, and nothing needs to be “recovered” by switching it off and back on.

Locked once graded: the moment the activity records a real grade for any student, Maximum attempts and Grade scoring lock — the same way Moodle already locks a graded activity’s own “Maximum grade” field once real grades exist. This guarantees every round ever recorded for that activity was scored under the exact same grade rules for the activity’s whole lifetime.

Ranking scoring locks separately, the moment any finished attempt exists — it doesn’t wait for a real grade, because ranking points are already computed and stored for every finished round regardless of whether Grade or Show ranking are even on (see above). An entirely ungraded, ranking-only activity already accumulates real history from its very first round; locking the scoring mode once that history exists prevents the same scale inconsistency the lock above prevents for the grade.

Attempt history: each student can review their own past rounds — word, attempts used, time, grade score and (when ranking is enabled) ranking points — on a dedicated toolbar page. Whoever can manage the activity sees that same page too, including their own attempts if they have played the activity. The all-students report lives on a separate page, visible only to whoever can manage the activity: one table with every student’s attempts, 30 rows per page, sortable by clicking any column header, and filterable to a single student. Like the ranking, that report never includes a manager’s own attempts.

Deleting attempts reverses these locks when they no longer apply. From the all-students report, whoever can manage the activity can delete a student’s attempts individually or in bulk. Deleting genuinely clears that student’s grade rather than leaving a stale value behind, so if every attempt for every student is removed, Maximum attempts and Grade scoring unlock again exactly as grade_item::has_grades() expects — the same way they would on an activity that was never played at all. Ranking scoring follows the same logic against the attempts table directly, independent of whether grading is even on.

🧪 Automated Tests

PlayerWords ships with a PHPUnit test suite covering business logic, repository queries, web services, and Privacy API compliance, plus a Behat suite covering gameplay, PlayerHUD integration, and reports end-to-end in a real browser. Every CI push runs against the full matrix (Moodle 4.5 → 5.x, PostgreSQL & MariaDB).

PHPUnit — Core Tests

Local Business-Logic Tests (tests/local/)

Web Services Tests (tests/external/)

vendor/bin/phpunit --testsuite mod_playerwords

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

Behat — End-to-End Tests

Full test-by-test breakdown and coverage table →

🔐 Security & Compliance

• Capability-based access control (mod/playerwords:view, mod/playerwords:addinstance)
• require_sesskey() protection on all POST actions; AJAX calls are validated by Moodle’s core/ajax dispatcher
• Server-side enforcement of round limits and cooldown, always recomputed from current settings
• Round timeout is re-validated against the server’s own deadline (with a small network-latency tolerance) instead of trusting the client’s countdown alone
• Guess charset validation — only Unicode letters accepted
• AI-generated words are treated as untrusted input: only single-token, alphabetic terms within the configured length bounds are saved, and they enter pending teacher approval
• Session round state is isolated per activity instance and per user — a word id or session key from one activity is never accepted by another
• A wrong guess never leaks the correct word or its definition; the word is only ever revealed once the round has actually finished
• Moodle External API compliant
• Privacy API fully implemented (GDPR/LGPD)

🔒 Third-party Service Disclosure

AI word generation is optional and disabled by default. When a teacher uses it, the activity topic (never student data or attempt records) is sent through AI Hub (local_aihub) — using that user’s or the site’s own BYOK key, if the plugin is installed — or, as a fallback, through Moodle’s own core AI subsystem (core_ai), which routes to whatever provider the site administrator has configured. PlayerWords never contacts an AI provider directly; the request and its disclosure/consent are entirely owned by local_aihub or by core_ai. If neither is installed or configured, the AI word source is unavailable and every other feature keeps working normally.

• Cost: None required by PlayerWords itself. If used, any cost is whatever the underlying provider charges through a local_aihub BYOK key, or nothing at all via a free/institutional core_ai provider the site admin may have already configured.
• API keys / credentials: Not configured in PlayerWords. Obtain and configure a personal or site key inside AI Hub (local_aihub), or ask the site administrator to configure a core_ai provider instead.
• Demo credentials: Not applicable — no credentials are required to install or use PlayerWords; AI generation is entirely opt-in.

📄 License

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

Copyright: 2026 Jean Lúcio