O Filtro PlayerHUD é um plugin complementar obrigatório do Bloco PlayerHUD. Ele permite inserir drops de itens colecionáveis, ofertas de troca e o widget compacto do HUD diretamente no conteúdo do curso Moodle por meio de shortcodes.

Esse filtro possibilita que o professor incorpore elementos interativos dentro de páginas, rótulos, livros e outras atividades que suportem HTML, integrando-se ao sistema de gamificação PlayerHUD.

👈 Use a barra lateral para ir a qualquer seção desta página.

✨ Funcionalidades

• 📍 Drops de Itens: insere drops de itens colecionáveis diretamente no conteúdo do curso — páginas, rótulos, livros, fóruns e qualquer outra atividade com suporte a HTML.
• 🔢 Exibição de Quantidade por Coleta: o card do drop mostra o número real de unidades concedidas por coleta (ex.: x2), lido através do motor de quantidade de item do bloco quando presente, com fallback pra exibição de unidade única numa versão mais antiga do bloco.
• 🏪 Widgets de Troca: incorpora um card de troca da loja NPC do PlayerHUD embutido no conteúdo, resolvido por um código curto de consulta em vez de um ID de banco de dados cru.
• 🧩 Integração Baseada em Shortcode: três shortcodes ([PLAYERHUD_WIDGET], [PLAYERHUD_DROP ...], [PLAYERHUD_TRADE ...]) — veja Como Usar para a sintaxe completa.
• 🎮 Widget Compacto do HUD: o mesmo HUD do jogador exibido no bloco (avatar, XP, nível, itens recentes, ranking, barra de karma), incorporável em qualquer lugar que aceite shortcode.
• ⚡ Interação em Tempo Real: coleta baseada em AJAX via core/ajax do Moodle, sem redirecionamento de página.
• 🎒 Integração Transparente com o Inventário: itens coletados entram diretamente no sistema de inventário do PlayerHUD, respeitando as mesmas regras de tempo de recarga, limite e item secreto do bloco.
• 🚀 Renderização sem N+1: todo código de drop/troca em uma página é carregado em lote em uma única passagem antes da renderização, independente de quantos shortcodes existam no mesmo conteúdo.
• 🔐 Validação no Servidor: tempo de recarga (cooldown), limites de coleta, opt-out da gamificação e a capability block/playerhud:view são todos aplicados no momento da renderização — um shortcode nunca vaza nome de item, XP ou conteúdo de troca para um usuário que não deveria ver.
• 📱 Renderização Compatível com Dispositivos Móveis: shortcodes renderizam um fallback leve (ou nada, no caso do widget) dentro do app do Moodle, onde o fluxo de coleta via AJAX não se aplica.

🕹️ Ecossistema PlayerGames

Este plugin faz parte do ecossistema de gamificação PlayerGames. Juntos, esses plugins transformam o Moodle em uma experiência imersiva:

• Bloco PlayerHUD (Obrigatório): o motor de gamificação — XP, níveis, inventário, missões, troca e progressão RPG. Este filtro não tem efeito nenhum sem ele.

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

• Restrição de Acesso PlayerHUD: restringe o acesso a atividades do curso com base no nível atual do estudante ou nos itens coletados.

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

• PlayerGroup: permite que os estudantes formem seus próprios grupos de forma autônoma diretamente na página da atividade — sem necessidade de intervenção do professor.

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

📦 Requisitos

🛠️ Instalação

1. Certifique-se de que o Bloco PlayerHUD esteja instalado primeiro — o filtro depende do bloco e não será instalado sem ele.

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

2. Baixe o arquivo .zip ou clone este repositório.
3. Extraia a pasta para o diretório filter/ do seu Moodle.
4. Renomeie para playerhud (se necessário). Caminho final: seu-moodle/filter/playerhud/
5. Acesse Administração do site > Notificações para concluir a instalação.
6. Ative o filtro em: Administração do site > Plugins > Filtros > Gerenciar filtros.

📖 Como Usar

1. Certifique-se de que o Bloco PlayerHUD esteja adicionado e configurado no curso.
2. Ative o Filtro PlayerHUD (veja Instalação).
3. Insira um dos shortcodes abaixo em qualquer área de conteúdo que passe pelos filtros do Moodle — páginas, rótulos, capítulos de livro, posts de fórum, etc.
4. Os drops de itens e os widgets de troca são renderizados dinamicamente dentro do curso; os estudantes coletam/trocam conforme as regras definidas no Painel de Gerenciamento do Bloco PlayerHUD.

Os shortcodes são removidos (renderizados como vazio) para convidados, na página inicial do site, para um usuário cuja capability block/playerhud:view esteja proibida, e para um estudante que tenha pausado sua própria gamificação — em todos esses casos nada sobre o item ou a troca subjacente é enviado ao navegador.

Referência de Shortcodes

[PLAYERHUD_WIDGET]

Renderiza o widget compacto do PlayerHUD: avatar, XP/nível, estoque de itens recentes, badge de ranking e (quando o modo RPG está ativado) a barra de karma e o retrato da classe. Não recebe atributos.

[PLAYERHUD_WIDGET]

[PLAYERHUD_DROP code=... mode=... text=... button_text=... button_emoji=...]

Renderiza um gatilho de coleta de item.

[PLAYERHUD_DROP code=XPTO123]
[PLAYERHUD_DROP code=XPTO123 mode=text text="Pegue a espada"]
[PLAYERHUD_DROP code=XPTO123 mode=image]
[PLAYERHUD_DROP code=XPTO123 button_text="Coletar!" button_emoji="⚔️"]

Um item secreto (marcado como tal no Painel de Gerenciamento) sempre renderiza como um placeholder de mistério genérico — nome, descrição e XP ocultos — até que o estudante realmente o colete, mesmo que um atributo text customizado seja fornecido.

Um item pode opcionalmente ser restrito a classes RPG específicas; um estudante fora das classes permitidas nunca vê a saída do shortcode (nem mesmo um placeholder).

[PLAYERHUD_TRADE code=...]

Renderiza um card de troca da loja NPC embutido no conteúdo, com verificação de saldo em tempo real contra o inventário atual do usuário.

[PLAYERHUD_TRADE code=A1B2C3]

O code da troca é uma conveniência de consulta curta, não uma barreira de segurança — o acesso à troca em si é sempre revalidado no servidor (sesskey, capability e checagem de grupo) no momento em que o estudante efetivamente a realiza.

Observações

• Múltiplos shortcodes na mesma página são todos resolvidos em uma única passagem de carregamento em lote — adicionar mais drops a uma página não adiciona consultas ao banco de dados proporcionalmente.
• Dentro do app móvel do Moodle, [PLAYERHUD_DROP ...] e [PLAYERHUD_TRADE ...] não renderizam nada (o fluxo de coleta via AJAX é exclusivo da web); os estudantes são direcionados para a própria visão de Mochila do bloco.

🧪 Testes Automatizados

O filtro inclui testes unitários/integração (PHPUnit) e de aceitação em navegador (Behat), executados a cada push de CI contra a matriz completa (Moodle 4.5 → 5.2, PostgreSQL & MariaDB).

PHPUnit — Testes Unitários e de Integração

vendor/bin/phpunit --testsuite filter_playerhud

Cobertura de linhas total (PHPUnit + Xdebug): 79%.

Behat — Testes de Aceitação

php admin/tool/behat/cli/init.php
vendor/bin/behat --tags=@filter_playerhud --profile=chrome

Detalhamento completo dos testes e tabela de cobertura →

🔐 Segurança e Conformidade

• Controle de acesso baseado em capability: todo shortcode reverifica block/playerhud:view no momento da renderização — um usuário sem essa capability vê o shortcode totalmente removido, o mesmo que ocorre com um convidado ou um jogador pausado, mesmo que as checagens determinísticas (login, curso, status de gamificação) passem.
• Aplicação no servidor: tempo de recarga (cooldown) e limites de coleta são sempre validados no servidor; o estado visual do shortcode (pronto/cooldown/coletado) é apenas uma questão de exibição, nunca a barreira real.
• Proteção require_sesskey(): os endpoints de coleta e processamento de troca aos quais os shortcodes apontam (collect.php, process_trade.php, ambos pertencentes ao Bloco PlayerHUD) exigem uma chave de sessão válida em toda requisição.
• Desserialização segura: o configdata armazenado pelo bloco é lido com unserialize_object(), restringindo o payload a stdClass — uma configuração forjada nunca pode disparar instanciação arbitrária de objeto nem uma cadeia POP-gadget como um unserialize() puro permitiria.
• Renderização protegida contra XSS: descrições de item e de classe RPG são sempre higienizadas com format_text() antes de serem entregues ao cliente, e todo fallback de ícone/emoji nos templates Mustache usa saída com escape (double-mustache) — uma descrição já foi enviada crua em um dos caminhos de renderização; isso foi corrigido e está coberto por um teste de regressão dedicado.
• Proteção contra reentrância de shortcode: uma descrição de item ou de classe RPG contendo o próprio shortcode [PLAYERHUD_DROP ...]/[PLAYERHUD_WIDGET] do filtro é renderizada com format_text(..., ['filter' => false]), impedindo que ela reentre em text_filter::filter() e recurse até a requisição esgotar seu limite de memória — a própria cadeia de filtros do Moodle não possui proteção de reentrância.
• Zero N+1 por construção: o pré-carregamento em lote (e não consultas por shortcode) impede que uma página com muitos drops se torne um vetor de negação de serviço por amplificação de consultas.
• Compatível com a API Externa do Moodle: o fluxo de coleta ao qual ele se conecta é exposto como uma função externa própria, com validação de parâmetros/retorno e checagem de capability.
• Consciente de privacidade: veja Provedor de Privacidade abaixo — este plugin não armazena dado nenhum próprio.
• Compatível com dispositivos móveis: os shortcodes degradam com segurança dentro do app do Moodle, em vez de tentar um fluxo AJAX que o app não suporta.

Provedor de Privacidade

O Filtro PlayerHUD implementa o null_provider do Moodle — ele apenas exibe dados pertencentes e armazenados pelo Bloco PlayerHUD (itens, drops, trocas, inventário); nunca persiste nenhum dado pessoal próprio. Veja a documentação do próprio bloco para a cobertura completa de exportação/exclusão GDPR.

📄 Licença

Este projeto é licenciado sob a GNU General Public License v3 (GPLv3).

Copyright: 2026 Jean Lúcio