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, Missões, Trocas e progressão RPG.

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.

🖼️ Capturas de Tela

Navegue pelas setas, pelos pontos, ou pelas teclas de seta do teclado. Clique na imagem para ampliar.

‹

›

A barra lateral do HUD do estudante: avatar, nível, barra de XP e estoque de itens recentes, sempre visível ao lado do curso

1 / 3

✨ 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.
• 🔢 Quantidade de Item: Itens mantêm um saldo numérico real em vez de uma linha por unidade coletada. A Quantidade por coleta de um drop controla quantas unidades ele concede a cada coleta (independente do limite de coleta), quests podem premiar qualquer quantidade do item, e trocas podem exigir/entregar qualquer quantidade por item. Saldos altos são exibidos de forma compacta (ex.: 1.5k) na aba Coleção, nos detalhes do item e no histórico de auditoria.
• 🎯 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, com 50 jogadores por página; o estudante que está fora da página vê a própria linha fixada abaixo dela, com a posição real.
• 🔐 Participação Opcional: O aluno pode escolher participar ou não da gamificação. Quem sai da gamificação some do ranking e da seção de gamificação do perfil do curso. Ocultar-se só do ranking, ou o professor desligar o ranking, não esconde essa seção do perfil.
• ⚡ 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. A tabela de estudantes da aba Relatórios mostra 50 por página e tem busca por nome; a lista de seleção de estudante continua nos cursos com até 200 jogadores.
• 🩺 Uso e Diagnóstico (administradores): uma página do site com números de adoção e engajamento e a limpeza dos dados deixados por blocos removidos, com cópia salva antes — veja Página de Uso e Diagnóstico.
• 🪄 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:

Estudante em mais de um grupo do PlayerGroup

Um curso pode ter várias instâncias da atividade PlayerGroup, cada uma com seu próprio agrupamento. Dentro de uma mesma instância o estudante só pode pertencer a um grupo, mas nada impede que ele participe de um grupo em cada instância diferente do mesmo curso.

Quando isso acontece, o cabeçalho do bloco exibe o grupo em que o estudante entrou por último (o de timeadded mais recente na tabela groups_members), não um grupo “principal” ou de uma instância específica. A aba de Ranking de Grupos não tem essa limitação — como lê diretamente das tabelas nativas do Moodle, todos os grupos do estudante aparecem normalmente.

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

Drops que ainda não foram colocados

Os números acima contam todos os drops, mas um drop só paga XP quando o shortcode dele está num lugar que os estudantes enxergam. Quando o painel encontra drops que não estão na descrição de nenhuma atividade, no conteúdo de nenhuma página nem no fórum de avisos, ele acrescenta um aviso abaixo da mensagem de equilíbrio, com quantos drops são e quanto XP eles pagariam, e um link para Distribuir drops. Esse XP faz parte do total acima, mas não pode ser ganho enquanto os drops não forem colocados.

A verificação lê os mesmos lugares que a tela Distribuir drops. Um drop colocado onde ela não olha (um capítulo de livro, o resumo de uma seção, uma postagem de fórum) aparece como “não encontrado”; nesse caso, o aviso pode ser ignorado.

🩺 Página de Uso e Diagnóstico

Administradores do site têm uma página em Administração do site > Relatórios > PlayerHUD: uso e diagnóstico (permissão moodle/site:config). Todos os números são contados no próprio site — nada é enviado para fora dele.

Adoção

Quanto o bloco é usado, contado por curso (o bloco permite uma instância por curso):

• Cursos com o bloco, divididos em cursos com itens, com jogadores mas sem itens e com o bloco vazio — os três somam o total.
• Cursos com cada recurso ativado: modo RPG, missões, ranking, itens.
• Blocos que versões anteriores deixaram no Painel de usuários, mostrados só quando existem. Eles não funcionam mais, e cada usuário pode excluir o seu no modo de edição do Painel.

Engajamento

• Jogadores, jogadores que desativaram a gamificação e o XP acumulado pelos jogadores.
• Nos últimos 90 dias: jogadores que ganharam XP, itens recebidos, missões concluídas, trocas realizadas, solicitações à IA (por provedor) e execuções do assistente.

Os números ficam em cache por 10 minutos; o botão Atualizar recalcula na hora.

Integridade dos dados e limpeza

Sites que removeram o bloco antes da v1.7.0 podem ainda guardar os dados desses blocos, e versões anteriores podiam deixar registros para trás ao apagar um item, missão, capítulo, cena, troca ou execução do assistente. Nada disso aparece em nenhuma tela nem entra em nenhuma conta do jogo.

• Instâncias de blocos removidos: uma linha por bloco removido, com jogadores, XP, itens, datas de atividade e curso. O curso é recuperado do log quando possível; instâncias cujo curso ainda existe começam desmarcadas, porque o bloco pode ter sido removido por engano. Só as marcadas são apagadas. São listadas no máximo 100 por vez — as demais aparecem depois dessa limpeza.
• Restos de exclusões antigas: descritos em palavras (por exemplo, “Cenas de história cujo capítulo não existe mais”). São sempre incluídos na limpeza, e apagá-los não muda nada nos cursos em uso.

A exclusão exige confirmação explícita e roda numa única transação. Antes de apagar, uma cópia de cada registro é salva num arquivo JSON no diretório de dados do site (moodledata/block_playerhud/orphan_backups/). A página lista essas cópias com os botões Baixar e Apagar. As cópias contêm dados pessoais (identificadores de usuários e XP) dos registros apagados, então uma tarefa agendada as exclui automaticamente após 30 dias (você pode apagá-las antes pela página), e elas são removidas quando o plugin é desinstalado.

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

Os recursos opcionais de IA do PlayerHUD (Gerador de Conteúdo e Assistente Game Master) podem recorrer ao AI Hub (local_aihub, do mesmo autor, parte dos serviços compartilhados do ecossistema PlayerGames). Quando o AI Hub está instalado, qualquer chave pessoal ou de site que um professor ou administrador já tenha configurado nele fica automaticamente disponível para o PlayerHUD — sem precisar reinserir a chave. As chaves do AI Hub ficam entre as próprias chaves do PlayerHUD e o fallback core_ai do Moodle na Cadeia de Provedores de IA. Sem o AI Hub instalado, o PlayerHUD simplesmente pula esses dois níveis e resolve a partir das próprias chaves ou do core_ai.

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

🧩 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 recomendado Filtro PlayerHUD (necessário para posicionar drops de itens via shortcodes no conteúdo do curso).
5. Acesse Administração do site > Notificações para concluir a instalação.
6. Adicione o bloco ao curso.

Administradores podem acompanhar o uso do bloco, e limpar dados deixados por blocos removidos, em Administração do site > Relatórios > PlayerHUD: uso e diagnóstico — veja Página de Uso e Diagnóstico.

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

Remover o bloco de um curso apaga na hora todo o jogo e o progresso de todos os estudantes, e não é possível desfazer pelo bloco. Faça antes um backup do curso com os dados dos usuários, ou use Ocultar no menu do bloco para tirar o jogo da vista sem perder nada. O Manual do Mestre (botão ? do painel de gerenciamento) explica isso em Remover o bloco.

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

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
• Página de Uso e Diagnóstico: só números agregados, contados no próprio site — nada é enviado para fora dele. A limpeza salva antes uma cópia JSON dos registros apagados, que contém dados pessoais (identificadores de usuários e XP), em moodledata/block_playerhud/orphan_backups/; ela é apagada automaticamente após 30 dias, antes se um administrador a apagar pela página, e quando o plugin é desinstalado

🔎 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