⚠️ Este plugin está em desenvolvimento ativo. Ainda não foi publicado no Diretório de Plugins do Moodle.

O Bloco PlayerGames é um widget compacto de sidebar para o ecossistema de gamificação PlayerGames. Ele espelha o perfil site-wide do Player Hub de um usuário — avatar, nível, XP de temporada, sequência e rankings — onde quer que um administrador do site o adicione, sem guardar nenhum dado ou lógica de negócio próprios.

Tudo que o widget mostra e faz é delegado ao local_playergames, do qual este bloco depende diretamente.

👈 Use a barra lateral para navegar entre as seções desta página.

🖼️ Capturas de Tela

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

O Bloco PlayerGames na gaveta do Painel: avatar, nível, barra de XP, minijogos do dia e streak — todos os dados site-wide de relance

1 / 3

✨ Funcionalidades

🦊 Avatar em destaque: mostra o avatar equipado; clicar nele abre o mesmo modal de coleção usado no Player Hub, então equipar em um lugar reflete no outro.
📊 Progresso de temporada: nível, XP e barra de progresso até o próximo nível.
🎮 Jogos de hoje: atalhos para os minijogos disponíveis no dia, com estado feito/pendente/bloqueado.
🔥 Sequência, congelamentos e check-ins: estatísticas compactas com rótulos acessíveis.
📘 XP de aprendizado (opcional): mostra o XP espelhado da atividade em cursos via block_playerhud, quando essa ponte e a configuração do admin estão ativas — exclusivo de estudante, nunca somado ao XP de temporada.
🏆 Posição no ranking + opt-in em um clique: posições nos rankings de temporada e de aprendizado, cada um com seu próprio toggle para aparecer ou não — sem precisar abrir o Hub completo.
❓ Ajuda embutida: um modal curto explicando os dois pools de XP, avatares e rankings — o mesmo conteúdo exibido em toda página do Player Hub.
🕐 Atalho para o histórico: link direto para o log completo de eventos de XP, sequência e congelamento.
🔌 Três estados, nenhuma lógica própria:
- Normal — jogador ativo: avatar, nível, barra de XP, jogos do dia, sequência e rankings visíveis.
- Pausado — o usuário optou por sair da gamificação, com link para reativar diretamente do bloco.
- Oculto — sem temporada ativa, ou o usuário é excluído pela configuração de grupo de participantes do site.
Os três estados são calculados pelo local_playergames; o bloco só escolhe qual template renderizar.

🕹️ Ecossistema PlayerGames

O Bloco PlayerGames é um companheiro do local_playergames, o hub central do ecossistema, projetado para complementar — não sobrepor — o block_playerhud:

	Escopo	Onde aparece
`block_playerhud`	XP, itens, missões e história por curso	Dentro de um curso
`block_playergames` (este plugin)	XP de temporada, sequência e rankings site-wide	Página inicial do site e Painel, não dentro de cursos

PlayerGames Hub (local_playergames): a dependência obrigatória — página do hub, rankings, missões, catálogo de avatares, log de atividade. 👉 github.com/jeanlucio/moodle-local_playergames
Bloco PlayerHUD (block_playerhud): bloco de gamificação por curso. Seu XP de curso pode opcionalmente espelhar para o pool “XP de aprendizado” deste ecossistema. 👉 github.com/jeanlucio/moodle-block_playerhud
AI Hub (local_aihub): broker BYOK compartilhado para geração de cartuchos com IA em local_playergames. Opcional. 👉 github.com/jeanlucio/moodle-local_aihub

📦 Requisitos

Componente	Versão
Moodle	4.5+
PHP	8.1+
`local_playergames`	Obrigatório (dependência rígida)

🛠️ Instalação

⚠️ Este plugin ainda não está publicado no Diretório de Plugins do Moodle. Instale manualmente a partir deste repositório.

Instale o local_playergames primeiro — este bloco não instala sem ele.
Baixe o arquivo .zip ou clone este repositório.
Extraia na pasta blocks/ do seu Moodle.
Renomeie para playergames (se necessário). Caminho final: seu-moodle/blocks/playergames/
Acesse Administração do site → Notificações para concluir a instalação.

📖 Como Usar

Para Administradores

Ative o modo de edição na página inicial do site ou no Painel.
Use “Adicionar um bloco” → PlayerGames para posicionar o widget.
Clique no avatar para trocar, no ícone ❓ para uma explicação rápida, ou no ícone 🕐 para o histórico completo de atividade.

💡 Recomendação: este bloco foi pensado para a página inicial do site e o Painel, não para cursos individuais (esse papel é do block_playerhud). Para que o widget fique visível automaticamente para todos:

Adicione-o na página inicial do site em modo de edição — como a página inicial é compartilhada por todo o site, essa única ação já torna o bloco visível para qualquer usuário.

Adicione-o também na página de Painel padrão (Administração do site → Aparência → Página do Painel padrão), para que novos painéis já comecem com ele. Usuários que já personalizaram o próprio Painel não recebem isso retroativamente, a menos que você também use “Redefinir Painel para todos os usuários” — uma ação destrutiva, use com critério.

Para Estudantes

O bloco aparece automaticamente na página inicial do site e/ou no Painel assim que um administrador o adiciona.
Clique na miniatura do avatar para abrir a coleção e equipar um diferente.
Clique no ícone ❓ para uma explicação rápida sobre XP, avatares e rankings.
Clique no ícone 🕐 para abrir o log completo de histórico de atividade.
Alterne “Mostrar no ranking” diretamente do bloco — sem precisar visitar o Player Hub completo.

🧪 Testes Automatizados

A única lógica de negócio deste plugin — qual dos três estados renderizar — é coberta por PHPUnit. Todo o resto é orquestração de managers do local_playergames, já testados naquele plugin.

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

Arquivo de teste	Casos	O que é coberto
`output/widget_test.php`	9	Seleção de estado: pausado quando a gamificação está desativada, oculto sem temporada ativa ou quando excluído pela configuração de grupo de participantes, normal nos demais casos; sanidade dos dados do estado normal (nome, nível, XP); link do estado normal para pausar a gamificação; XP de aprendizado oculto quando a configuração do admin está desligada; posição e texto do toggle de opt-in nos rankings de temporada e de aprendizado quando o usuário adere a cada um
`privacy/provider_test.php`	2	Implementa `null_provider`; `get_reason()` aponta para uma string de idioma real
Total	11

Cobertura de linhas por classe (PHPUnit + Xdebug):

Classe	Cobertura de linhas
`output\widget`	100%
`privacy\provider`	100%
Total	100%

vendor/bin/phpunit --testsuite block_playergames

Behat — Testes de Aceitação

Arquivo de feature	Cenários	O que é coberto
`block_playergames_widget.feature`	3	Link de pausa no estado normal abre a página de preferências de gamificação; desativar pelo widget mostra o estado pausado; reativar a partir do estado pausado restaura o widget normal
Total	3

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

🔐 Segurança e Privacidade

Controle de Acesso

Controle de acesso baseado em capability: block/playergames:view é concedida a todo usuário autenticado, já que o widget vive em páginas compartilhadas e site-wide, não dentro de um curso.

Privacy API

Este bloco implementa a interface null_provider — ele não guarda nenhum dado pessoal próprio. Todos os dados pessoais (perfil, XP, sequência, log de atividade, avatar) são de propriedade e declarados pelo local_playergames.

Operações de Escrita

Toda ação de escrita — equipar um avatar, alternar visibilidade no ranking — passa pelos web services já validados e protegidos pelo local_playergames. Este bloco não realiza escritas próprias.

📄 Licença

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

Mantido por Jean Lúcio.

PlayerGames Block