O Bloco PlayerHUD é um sistema modular de gamificação para Moodle que introduz mecânicas estruturadas de progressão baseadas em XP, Níveis, Inventário e Ranking.

Ele fornece um HUD (Head-Up Display) dinâmico dentro do curso, permitindo que os alunos acompanhem seu progresso em tempo real, enquanto o professor configura as mecânicas de engajamento de acordo com seus objetivos pedagógicos.

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

Código-fonte: github.com/jeanlucio/moodle-block_playerhud

✨ Funcionalidades

• 🎮 Sistema de XP e Níveis: Progressão automática baseada no XP acumulado.
• 🏅 Tiers de Nível: Sistema visual de progressão com código de cores a cada 5 níveis.
• 🎛 Progressão Configurável: O professor define a quantidade de níveis e o XP necessário para cada nível.
• 🎒 Sistema de Inventário: Itens colecionáveis com Tempo de Recarga (intervalo mínimo entre coletas) e limite configurável.
• 🎯 Poderes de Item: Um item pode carregar um efeito especial além do XP — virar o avatar de perfil do aluno, conceder uma extensão de prazo numa atividade escolhida (requer o plugin opcional Late Penalty), ou funcionar como a PlayerCoin colecionável.
• 📜 Sistema de Missões: Missões manuais (nível/XP), de coleção, de conclusão de atividade, de comércio e de capítulo, com uma ferramenta de sugestão heurística.
• 📍 Sistema de Drops: Posicione itens nas seções do curso via shortcodes.
• 🎁 Distribuição Automática de Drops: Insira em lote os drops pendentes na atividade do curso com melhor correspondência de nome, com um clique — com desfazer por item.
• 🏪 Loja NPC: Sistema de trocas configurável — itens por recompensas.
• 🏆 Ranking: Classificação com critério de desempate e controle de visibilidade.
• 🔐 Participação Opcional: O aluno pode escolher participar ou não da gamificação.
• ⚡ Atualização em Tempo Real: Coleta via core/ajax.
• 🎉 Pop-ups Comemorativos com o Mascote: Pop-ups animados com o mascote Huddy marcam momentos-chave — o Huddy se apresenta na primeira visita do aluno ao painel, e depois comemora subir de nível (mostrando o nível alcançado), zerar o jogo (alcançar 100% da pontuação do curso), concluir a primeira missão (um aviso único para ir resgatar a recompensa) e encontrar a primeira PlayerCoin. Totalmente acessível (foco preso no teclado, devolução de foco, rótulos para leitor de tela). Os pop-ups de apresentação, primeira missão e primeira PlayerCoin aparecem uma única vez cada. Toda a arte do mascote é distribuída em WebP leve. O professor pode desativar todas as animações do mascote nas configurações do bloco (seção Mascote).
  • Personalizando a PlayerCoin: você pode trocar a imagem ou o emoji do item PlayerCoin à vontade — o pop-up não é afetado e sempre mostra o mascote. Já o texto do pop-up é fixo no nome ”PlayerCoin”; portanto, se renomear o item, mantenha esse nome ou o texto do pop-up deixará de corresponder.
• 🧙 Personagens RPG: Defina personagens com retratos, alinhamento de reputação e imagens de evolução por tier.
• 📖 História e Capítulos: Sistema narrativo ramificado com nós de escolha e caminhos por personagem.
• ⚖️ Sistema de Reputação: Mecânica de alinhamento moral que evolui o retrato do personagem do aluno ao longo do tempo.
• 📊 Analytics: Logs de auditoria, rastreamento da economia do jogo, um histograma de distribuição de níveis e um gráfico de conclusão de missões, além de um painel de Saúde da Economia que sinaliza um orçamento de XP desequilibrado.
• 🪄 Assistente de Gamificação: Um assistente passo a passo que monta a estrutura gamificada do curso inteiro numa única rodada, com progresso ao vivo, nova tentativa em caso de falha e desfazer com um clique por rodada a partir de uma lista de histórico.
  • Onze mecânicas em três níveis — Itens, PlayerCoin, Pacote de Avatares, Comércio, Ranking, Missões, Colecionável de Conhecimento, Item de Extensão de Prazo, Item RPG, RPG (personagens + história completa) e um Item Secreto oculto, agrupados em Básico / Intermediário / Avançado pela sofisticação da mecânica, não pelo que ela tecnicamente faz.
  • Orçamento de XP compartilhado — mantém toda mecânica gerada dentro do teto de níveis do curso.
  • Distribuição automática de drops — insere os itens gerados nas atividades existentes do curso (ou no próprio fórum de avisos, no caso de PlayerCoin/Item Secreto).
  • Octógono de cobertura Octalysis ao vivo — fiel às 8 Core Drives originais de Yu-Kai Chou, geometria inclusive, mostra quais motivações a configuração atual realmente cobre.
• 🤖 Ferramentas de IA (Opcional): Dois recursos com cadeia de quatro níveis de provedores (veja Cadeia de Provedores de IA abaixo):
  • Gerador de Conteúdo — cria itens, capítulos de história com nós ramificados e backstories de personagens RPG sob demanda.
  • Assistente Game Master — aba de chat conversacional para professores. Tire dúvidas sobre design de jogo, receba sugestões e acione ações (criar item, missão, capítulo) com uma etapa de confirmação antes de salvar.
• 📱 Compatível com Mobile.

🏆 Comportamento do Ranking de Grupos

Quando o ranking de grupos está habilitado, a média de XP de cada grupo é calculada apenas com os membros que estão participando ativamente — ou seja, membros que tenham simultaneamente:

• Gamificação ativa (enable_gamification = 1)
• Ranking visível (ranking_visibility = 1)

Membros que optaram por não participar da gamificação ou que ocultaram seu ranking são completamente excluídos da soma e da contagem do grupo. O denominador usado para calcular a média reflete apenas a quantidade de participantes ativos, não o total de membros do grupo.

Implicação prática: um grupo com muitos membros inativos pode apresentar uma média mais alta do que o esperado, pois o cálculo é feito sobre um subconjunto menor. Professores devem ter em mente que a média exibida não representa todos os matriculados no grupo — apenas os que estão participando ativamente do ranking.

Integração com o PlayerGroup

O ranking de grupos lê diretamente das tabelas nativas de grupos do Moodle ({groups} / {groups_members}). Funciona com qualquer grupo do Moodle — criado manualmente pelo professor ou automaticamente pela atividade PlayerGroup.

Quando o PlayerGroup (mod_playergroup) está instalado junto ao PlayerHUD, uma integração adicional é ativada no cabeçalho do bloco (não na aba de ranking): o badge do grupo do estudante, o nome do grupo, a quantidade de membros e a capacidade (ex.: 3/5) são exibidos no topo do bloco. Essa informação é obtida via API pública do PlayerGroup (\mod_playergroup\api\group_info) e está disponível apenas para grupos criados por atividades do PlayerGroup — grupos manuais do Moodle não aparecem ali.

As duas funcionalidades são independentes:

⚖️ Painel de Saúde da Economia

A aba Configurações do painel de gerenciamento inclui um widget de Saúde da Economia que compara o total de XP que um estudante pode ganhar (todos os itens × seus limites de drop + recompensas de missões) com o teto de XP configurado (XP por nível × número de níveis).

O widget também exibe uma tabela expansível com o detalhamento de cada item e missão e sua contribuição individual de XP, facilitando a identificação do conteúdo que está contribuindo mais ou menos para a economia.

🎓 Finalidade Educacional

O PlayerHUD foi projetado para:

• Estimular engajamento ativo
• Reforçar progressão baseada em domínio
• Criar sistemas estruturados de recompensa
• Permitir dinâmicas competitivas e cooperativas
• Garantir participação voluntária

Indicado para:

• Cursos gamificados
• Formação técnica
• Trilhas de certificação
• Estratégias de reforço de engajamento

🕹️ Ecossistema PlayerGames

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

• Filtro PlayerHUD: Permite inserir drops de itens por meio de shortcodes no conteúdo do curso. 👉 https://github.com/jeanlucio/moodle-filter_playerhud

• Restrição de Acesso PlayerHUD: Restringe o acesso a atividades com base no nível atual do aluno ou nos itens coletados. 👉 https://github.com/jeanlucio/moodle-availability_playerhud

• PlayerGroup: Permite que os alunos 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

🧩 Integração Opcional: Late Penalty

O poder de item Extensão de Prazo (veja Funcionalidades) não funciona sozinho — ele depende do plugin separado Late Penalty (local_latepenalty, do mesmo autor, mas que não faz parte da família PlayerGames). Quando instalado, resgatar um item de Extensão de Prazo adia o prazo efetivo da atividade para aquele estudante e aciona o recálculo automático do Late Penalty, dispensando ou reduzindo qualquer penalidade de nota por atraso já aplicada. Sem o Late Penalty instalado, o poder do item falha de forma controlada, mostrando uma mensagem de “não instalado” em vez de conceder a extensão.

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

📦 Requisitos

🛠️ Instalação

1. Baixe o arquivo .zip ou clone este repositório.
2. Extraia na pasta blocks/ do seu Moodle.
3. Renomeie para playerhud (se necessário). Caminho final: seu-moodle/blocks/playerhud/
4. Instale o plugin obrigatório Filtro PlayerHUD.
5. Acesse Administração do site > Notificações para concluir a instalação.
6. Adicione o bloco ao curso.

📖 Como Usar

1. Adicione o Bloco PlayerHUD ao seu curso.
2. Acesse o Painel de Gerenciamento (necessário perfil de Professor).
3. Escolha como configurar:
   • Início rápido: rode o Assistente de Gamificação para gerar automaticamente itens, missões, ranking e outras mecânicas em uma única rodada (veja Funcionalidades acima).
   • Configuração manual: configure cada mecânica você mesmo:
     • Itens
     • Valores de XP
     • Quantidade de níveis
     • Limiares de XP para progressão
     • Posicionamento de drops
     • Tempo de Recarga (intervalo entre coletas)
     • Limites de coleta
4. Os alunos coletam itens diretamente nas seções do curso.
5. O sistema atualiza automaticamente XP, níveis e ranking.

🌱 Ambiente de Demonstração (Quick Start)

O plugin inclui dois scripts CLI de seed que criam um curso de demonstração completamente configurado em minutos — útil para desenvolvimento local ou para avaliar o conjunto completo de funcionalidades sem configuração manual.

O que é criado:

• 1 curso (playerhud-demo) com 3 seções e acompanhamento de conclusão
• 1 professor (seed_teacher) + 5 alunos (seed_alice … seed_eve)
• 3 classes RPG com retratos evolutivos de 5 etapas: Guerreiro, Mago, Ladino
• 5 itens com diferentes valores de XP, cooldowns e limites de coleta
• 5 drops inseridos em atividades do curso via shortcodes (modos de exibição: card, imagem e texto)
• 9 quests cobrindo todos os tipos de conclusão (nível, XP total, itens únicos/específicos, trocas)
• 2 capítulos de história com escolhas ramificadas e efeitos de reputação
• 2 ofertas de troca (loja NPC), uma delas já concluída por um aluno
• Um esquadrão de ranking de grupos (3 dos 5 alunos agrupados, 2 deixados sem grupo de propósito)
• Um item “Extensão de Prazo” ligado a uma penalidade real já aplicada pelo Late Penalty — só é semeado se local_latepenalty estiver instalado
• Inventário, log de quests e conclusão de atividades pré-populados — o ranking já está pronto para navegar imediatamente

Ranking resultante após o seed:

Uso:

# Executar uma vez
php blocks/playerhud/cli/seed_pt_br.php --password=SuaSenhaDev

# Apagar e recriar do zero
php blocks/playerhud/cli/seed_pt_br.php --password=SuaSenhaDev --reset

# Ignorar o guard de site não-desenvolvimento (domínios customizados)
php blocks/playerhud/cli/seed_pt_br.php --password=SuaSenhaDev --force

O parâmetro --password é obrigatório e define a senha de login de todas as contas seed. O script recusa executar em URLs que não sejam de desenvolvimento (localhost, *.local, *.test), a menos que --force seja passado.

Via Docker Compose: docker compose exec <servico-webserver> php blocks/playerhud/cli/seed_pt_br.php --password=SuaSenhaDev

🧪 Testes Automatizados

O PlayerHUD inclui uma suíte de testes extensa que cobre tanto a lógica de negócio (PHPUnit) quanto a aceitação em navegador (Behat). Todo push de CI executa a matriz completa (Moodle 4.5 → 5.x, PostgreSQL e MariaDB).

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

Testes de Lógica de Negócio Compartilhada (tests/local/)

Testes de Web Services (tests/external/)

Testes de Controlador (tests/controller/)

Testes de Saída / Renderer (tests/output/)

vendor/bin/phpunit --testsuite block_playerhud

Cobertura de linhas geral (moodle-coverage, PHPUnit + Xdebug): 42%.

Ver o detalhamento completo de cada teste e a tabela de cobertura →

🔐 Segurança e Conformidade

• Controle de acesso baseado em capabilities
• Validação no servidor do tempo de recarga e limites
• Proteção com require_sesskey()
• Compatível com a API externa do Moodle
• Participação no ranking com controle de privacidade

🔎 Divulgação de Serviço de Terceiros

O PlayerHUD inclui recursos opcionais de IA: um Gerador de Conteúdo (itens, capítulos, backstories de classes) e um Assistente Game Master (chat conversacional para professores que também pode acionar ações no jogo).

O recurso de IA é obrigatório?

Não. O plugin funciona de forma completa sem qualquer serviço externo. Todo o conteúdo pode ser criado manualmente dentro do Moodle. Os recursos de IA são ferramentas de produtividade — o assistente exige confirmação antes de salvar qualquer coisa.

Cadeia de Provedores de IA

O PlayerHUD seleciona o provedor de IA nível por nível, seguindo a escada compartilhada do ecossistema PlayerGames. Uma chave explicitamente configurada sempre prevalece sobre o padrão institucional; o core_ai fica na base.

Escada de resolução (maior prioridade primeiro):

Nível primeiro, não provedor primeiro. Cada nível acima é avaliado como um todo: o primeiro nível que contiver qualquer chave é usado exclusivamente. Assim, a chave pessoal do professor (nível 1) sempre prevalece sobre uma chave do hub (nível 2) — mesmo que a chave do hub seja de um provedor de maior prioridade. Por exemplo, a chave de endpoint personalizado do professor não é substituída por uma chave Gemini que esteja no hub. O core_ai é consultado apenas quando nenhum nível possui uma chave.

Dentro do nível escolhido, os provedores diretos são testados na ordem Gemini → Groq → OpenAI-compatível (a primeira chave encontrada é usada; se a chamada falhar, o próximo é tentado).

Isso também significa: se o professor configurou sua própria chave no hub PlayerGames, o PlayerHUD a utiliza automaticamente — sem necessidade de recadastrar no PlayerHUD.

Provedores diretos suportados

• Google Gemini — https://ai.google.dev/
• Groq — https://console.groq.com/
• APIs compatíveis com OpenAI — Qualquer provedor que siga o formato da API OpenAI (ex.: OpenRouter, modelos locais via LM Studio, proxy Ollama, etc.)

Esses serviços seguem seus próprios termos de uso e políticas de privacidade.

Como obter a chave de API

As chaves de API devem ser criadas diretamente no site oficial do provedor:

• Google Gemini: https://ai.google.dev/
• Groq: https://console.groq.com/
• APIs compatíveis com OpenAI: consulte a documentação do provedor específico

Gemini e Groq atualmente oferecem planos gratuitos, porém as políticas de preços podem variar conforme o volume de uso.

O PlayerHUD não fornece chaves de API.

Onde a chave é configurada

As chaves de API podem ser configuradas por qualquer uma das seguintes origens (em ordem decrescente de prioridade):

1. Chave pessoal no PlayerHUD — configurada individualmente por cada professor na aba Configurações do painel de gerenciamento.
2. Chave pessoal na Central de IA — configurada pelo professor em local_aihub → Minhas chaves de IA (se o hub estiver instalado).
3. Chave de site no PlayerHUD — configurada pelo admin em Administração do site → Plugins → Blocos → PlayerHUD.
4. Chave de site na Central de IA — configurada pelo admin nas configurações do local_aihub (se o hub estiver instalado).
5. Moodle core_ai — configurado pelo admin em Administração do site → IA → Provedores de IA (nenhuma chave armazenada no PlayerHUD; consultado apenas quando nenhuma das origens acima tiver chave configurada).

Transmissão de dados

Quando o recurso de IA é utilizado, os prompts informados são enviados ao provedor selecionado para processamento.

O plugin:

• Não armazena prompts nem histórico de conversa (o histórico do chat é apenas da sessão, no navegador)
• Não armazena respostas brutas da IA
• Apenas salva os objetos do jogo criados dentro do Moodle (itens, missões, capítulos)

Nenhuma comunicação externa ocorre sem ativação explícita de um recurso de IA.

Credenciais de Demonstração

Não aplicável — o PlayerHUD não exige nenhuma credencial para instalar ou usar. Todo recurso de IA é totalmente opcional e o bloco funciona plenamente sem nenhuma chave configurada.

📄 Licença

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

Copyright: 2026 Jean Lúcio