⚠️ Este plugin está em desenvolvimento ativo. Ainda não foi publicado no Diretório de Plugins do Moodle. Algumas funcionalidades descritas abaixo são planejadas e ainda não estão implementadas.

O PlayerGames (local_playergames) é o hub central do ecossistema de gamificação PlayerGames para o Moodle. Serve a quatro propósitos principais:

1. Dashboard do Ecossistema — visão geral visual de todos os plugins Player instalados no site, com status, dependências e links de acesso rápido.
2. Player Hub — plataforma de gamificação site-wide para estudantes e/ou outros usuários do Moodle (professores, managers, administradores), com XP, níveis, temporadas, missões, conquistas, avatares e streak diário. O administrador configura quais grupos participam.
3. Minijogos Diários — minijogos de reforço de conceitos e um check-in diário, alimentados por cartuchos de conteúdo (JSON, opcionalmente gerados por IA via o plugin companheiro local_aihub) — funcionando como um loop de aprendizado estilo Duolingo.
4. Bloco Companheiro de Sidebar — o block_playergames espelha o perfil do jogador (avatar, nível, XP, streak, jogos do dia, ranking) na página inicial do site e no Painel.

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

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

✨ Funcionalidades

✅ Implementado

• 🗺️ Dashboard do Ecossistema: Visão SVG de todos os plugins Player — instalados, ausentes, dependências, status e links de ação rápida para admins.
• 🎮 Player Hub — XP e Níveis: XP site-wide ao longo de temporadas configuráveis. Cada minijogo concede uma quantidade fixa de XP, e o admin define quantas jogadas pontuáveis por dia cada jogo permite — o XP é ganho exclusivamente jogando, então professores com diferentes cargas de turmas e estudantes matriculados em quantidades diferentes de cursos competem em igualdade de condições.
• 🪜 Player Hub — Escada de Níveis Configurável: O admin edita os limiares de XP e os títulos de cada nível na página Escada de Níveis — restaura a escada padrão de 5 faixas ou gera uma progressão linear mais longa com um clique.
• 📅 Player Hub — Check-in Diário: Ganhe XP apenas por acessar o hub uma vez ao dia, com limite por temporada. Opcionalmente conta para o streak diário.
• 🏆 Player Hub — Ranking de Temporada: Ranking com controle de privacidade (opt-in), desempate e separação por staff/estudante — ver Como o Ranking Funciona.
• 📘 Player Hub — XP de Aprendizado: Um pool de XP opcional e separado, espelhado da atividade do estudante por curso no block_playerhud, com seu próprio ranking opt-in — ver XP de Aprendizado.
• 🔥 Player Hub — Streak e Freeze: Acompanhamento de streak diário. Consumíveis de freeze evitam a perda de streak e são ganhos via missões; o check-in diário pode manter o streak vivo quando configurado.
• 🎯 Player Hub — Missões: Missões diárias, por streak, cumulativas de XP e por vitória, com recompensas de XP configuráveis.
• 🏅 Player Hub — Conquistas: Conquistas permanentes que persistem entre temporadas.
• 🏷️ Player Hub — Títulos: Títulos baseados em nível visíveis no perfil Moodle, fóruns e cursos.
• 🦊 Player Hub — Coleção de Avatares: Avatares emoji desbloqueados permanentemente pelo maior nível já alcançado pelo jogador, agrupados em 4 níveis configuráveis — ver Avatares.
• 🕐 Log Unificado de Atividade: Um único log cronológico de todo evento de XP, streak e freeze (XP de temporada, XP de aprendizado, freeze ganho/usado, streak quebrado), com um modal de ajuda compartilhado explicando XP de temporada, XP de aprendizado, avatares e rankings.
• 📦 Sistema de Cartuchos: Fonte de conteúdo para os minijogos. Múltiplos cartuchos ativos simultaneamente.
  • Todos os jogos: criação manual (editor inline), upload de JSON ou geração com IA (ver Cadeia de Provedores de IA).
  • PlayerQuiz: aceita também o Banco de Questões do Moodle (apenas questões de múltipla escolha).
• 🧠 PlayerQuiz: Minijogo diário de múltipla escolha usando conceitos do cartucho ativo — ver Como o PlayerQuiz Funciona.
• 🔡 PlayerGuess: Minijogo diário estilo Wordle — adivinhe o termo letra a letra — ver Como o PlayerGuess Funciona.
• 🧩 Bloco PlayerGames: Bloco sidebar companheiro (block_playergames) mostrando o avatar equipado, nível, XP, streak, jogos do dia e posição no ranking do usuário na página inicial do site e no Painel, com link para o Player Hub completo — ver Ecossistema PlayerGames.
• 📅 Gerenciamento de Temporadas: Criar, fechar e renovar automaticamente temporadas com snapshots de configuração. O histórico é preservado ao fechar uma temporada.
• 🔐 Privacidade (LGPD/GDPR): Privacy Provider completo — declaração de metadados, export e deleção de todos os dados pessoais armazenados; cartuchos compartilhados são preservados com o autor anonimizado.
• 🧪 Testes Automatizados: Suíte PHPUnit com 232 casos, verde na matriz completa do CI (ver a seção Testes Automatizados).

⏳ Em Desenvolvimento / Planejado

• 📝 PlayerFill: Minijogo de cruzadinha — posições numeradas; o mesmo número compartilha a mesma letra entre múltiplas palavras; resolver uma palavra revela letras nas demais (efeito cascata). Grid gerado em PHP sem bibliotecas externas.
• ⚔️ PlayerBattle: Minijogo match-3 RPG (grid 8×8) com combate por turnos contra um boss, movido pelo Phaser 3. Combinar peças de mana carrega uma pergunta do cartucho; acertar → dano triplo no boss; errar → o jogador leva dano.
• 📦 Phaser Centralizado: O local_playergames passará a servir o phaser.min.js para todos os plugins Player via local_playergames_get_phaser_url(), eliminando cópias duplicadas em cada plugin.
• 🛡️ Polimento para Publicação: Auditoria completa de acessibilidade e cobertura Behat mais ampla (a suíte PHPUnit e a conformidade PHPCS já estão prontas).

🤖 Cadeia de Provedores de IA

O armazenamento de chaves e o transporte com os provedores (Gemini, Groq, DeepSeek, compatível com OpenAI) vivem num plugin companheiro dedicado, o local_aihub. O PlayerGames em si só monta o prompt de geração do cartucho (tópico, idioma, quantidade de conceitos, dificuldade, categorias) e interpreta a resposta JSON da IA de volta em conceitos, então fica livre de gerenciamento de chaves e ainda oferece suporte à geração de cartuchos assistida por IA onde quer que o Hub esteja instalado.

Ordem de resolução

Uma falha real de provedor (ex.: uma chave inválida cadastrada no Hub) é preservada e exibida ao usuário — nunca é mascarada silenciosamente como “nenhuma fonte de IA disponível”.

Instalar o local_aihub é opcional. Sem ele, a geração de cartuchos via IA ainda funciona se o site tiver o core_ai configurado; o PlayerGames só perde a opção de chave pessoal (BYOK — cada professor trazendo sua própria chave Gemini/Groq/DeepSeek/OpenAI) que o Hub oferece.

API de integração para outros plugins

O cartridge\ai_generator expõe uma API pequena e estável que outros plugins do ecossistema podem chamar diretamente:

use local_playergames\cartridge\ai_generator;

$gen = new ai_generator();
if ($gen->has_key()) {
    // Prompt livre, roteado pela mesma cadeia usada na geração de cartuchos.
    $text = $gen->generate_text('Instrução de sistema opcional', 'Seu prompt aqui');
}

• has_key(): bool — true se o local_aihub tiver uma chave utilizável ou o core_ai tiver um provedor configurado.
• generate_text(string $system, string $user, bool $jsonmode = false): string — envia um prompt livre de sistema+usuário pela cadeia e retorna o texto bruto.
• send(string $prompt): array — variante de nível mais baixo que retorna o array completo do resultado (success, data, message, provider).
• generate(string $topic, string $language, int $count, int $difficulty, array $categorynames = [], string $context = ''): array — o gerador estruturado de conceitos do cartucho; use apenas quando precisar de arrays de conceitos no formato {term, definition, category, difficulty}.

Toda geração de IA disparada pelo PlayerGames é marcada no próprio log de uso do Hub com o componente (local_playergames) e uma descrição curta do que foi gerado (ex.: o tópico do cartucho), então administradores do site conseguem ver o uso de IA por plugin consumidor a partir do relatório de admin do Hub.

📦 Formato do Cartucho

Os cartuchos de conteúdo são arquivos JSON que alimentam todos os minijogos. O mesmo pacote serve ao PlayerQuiz, PlayerGuess, PlayerFill e PlayerBattle:

{
  "name": "Fundamentos de Gamificação",
  "version": "1.0",
  "language": "pt_BR",
  "concepts": [
    {
      "term": "gamificação",
      "definition": "Uso de elementos de jogos em contextos não-lúdicos",
      "category": "fundamentos",
      "difficulty": 2
    }
  ]
}

• Validado pelo importador antes de salvar
• Termos para o PlayerGuess: filtrados por comprimento configurável (padrão 4–8 letras) e devem ser uma única palavra alfabética (sem espaços, dígitos ou hífens) — ver Como o PlayerGuess Funciona
• Cartuchos do tipo quiz: cada questão aceita um generalfeedback opcional, exibido ao jogador após responder; o PlayerQuiz também pode sortear do Banco de Questões do Moodle, além dos cartuchos ou em conjunto com eles
• Admin pode ter múltiplos cartuchos ativos simultaneamente
• Multi-idioma: cada cartucho declara seu language

🧠 Como o PlayerQuiz Funciona

O PlayerQuiz é o primeiro mini-jogo diário. Ele sorteia questões de múltipla escolha dos cartuchos ativos (e, opcionalmente, do Banco de Questões do Moodle) e as exibe uma de cada vez.

O fluxo da jogada

• Uma questão é exibida por vez, com uma contagem regressiva por pergunta.
• Erro (ou o tempo esgotar) → a alternativa correta é revelada e a próxima questão carrega.
• Acerto → a jogada termina e o XP é concedido.
• Com um limite de tentativas definido, esgotar as tentativas encerra a jogada em falha (sem XP) e pode iniciar um cooldown.

Como a jogada termina no primeiro acerto, o jogador raramente responde o pool inteiro — a maioria das questões da sessão é só um colchão que dá variedade e margem para errar antes de repetir.

Dois limites independentes (é aqui que muita gente se confunde)

Exemplo — com XP por jogo = 25, jogos por dia = 3, questões por sessão = 20: o jogador pode concluir 3 jogadas hoje (teto de 75 XP), e cada jogada é montada a partir de um sorteio novo de 20 questões. Os dois números respondem perguntas diferentes: quantas partidas hoje vs qual o tamanho do baralho de cada partida.

Questões novas e repetições

• Cada carregamento da página monta uma sessão nova e embaralhada — não existe uma “sessão do dia” guardada.
• As questões só são lembradas como “vistas hoje” quando uma jogada é concluída com acerto. Elas então são excluídas das outras jogadas do mesmo dia, então jogadas concluídas nunca repetem questões.
• Sair no meio ou falhar não grava nada — reabrir a página gera um sorteio novo que pode incluir as mesmas questões.
• A memória de “vistas hoje” é por dia: o dia seguinte começa limpo e pode re-sortear questões de dias anteriores. Não há exclusão entre dias.
• Recarregar nunca dá XP extra — só muda quais questões aparecem; o XP continua limitado por jogos por dia e só conta no acerto.

Configurações do administrador

Administração do site → Plugins → Plugins locais → PlayerGames → Regras dos jogos

Como cronômetro, tentativas e cooldown se encaixam

• O tempo esgotar é tratado exatamente como um erro.
• Uma jogada só pode falhar quando há um limite de tentativas; com tentativas ilimitadas (0) o jogo entra em loop até o acerto, então o cooldown nunca dispara.
• Uma jogada falha não dá XP e não consome jogada do dia — o cooldown é o único freio, então com cooldown 0 o jogador pode tentar de novo na hora.

Por que o tamanho da sessão tem teto

Toda questão da sessão é renderizada no HTML da página de uma vez (o navegador apenas vai revelando uma a uma). Uma sessão muito grande formataria e enviaria centenas de questões que o jogador nunca verá — trabalho de servidor desperdiçado e página pesada. A lista com teto (máx. 50) mantém variedade de sobra sem esse custo. Sessões realmente grandes exigiriam outra arquitetura (carregar questões sob demanda), o que não é como o jogo funciona hoje.

🔡 Como o PlayerGuess Funciona

O PlayerGuess é um minijogo diário estilo Wordle: adivinhe um termo do cartucho ativo, letra por letra, dentro de um número limitado de tentativas.

O fluxo da jogada

• O tabuleiro mostra a definição do termo (como dica) e seu comprimento, mas não o termo em si.
• Cada tentativa deve ter exatamente o mesmo comprimento do termo alvo e conter apenas letras.
• Após cada tentativa, cada letra é marcada como correta (letra certa, posição certa), presente (letra certa, posição errada) ou ausente — o clássico feedback do Wordle, calculado no servidor para que o termo nunca seja exposto ao navegador antes do fim da rodada.
• Acerto → a rodada termina em vitória e o XP é concedido.
• Esgotar as tentativas → a rodada termina em derrota e o termo é revelado.
• A validação da tentativa sempre acontece no servidor contra o conceito atribuído do dia — o cliente nunca recebe nem confia em nada sobre o termo alvo antes do fim da rodada.

Um conceito por dia, pipeline de atribuição compartilhado

Toda noite, uma tarefa agendada atribui um conceito aleatório ao PlayerGuess (e, de forma independente, ao PlayerQuiz) a partir dos cartuchos ativos no momento — o mesmo pipeline usado entre os minijogos diários. Especificamente para o PlayerGuess, apenas conceitos cujo termo:

• tenha comprimento normalizado dentro da faixa configurada pelo admin (padrão 4–8 letras), e
• seja uma única palavra alfabética — sem espaços, dígitos ou hífens

são elegíveis. Esse filtro é aplicado de forma idêntica no momento da atribuição e novamente ao validar uma tentativa, então um termo que até se encaixa na faixa de comprimento mas contém, por exemplo, um hífen, nunca é atribuído a um dia de PlayerGuess.

Configurações do administrador

Administração do site → Plugins → Plugins locais → PlayerGames → Regras dos jogos

Administração do site → Plugins → Plugins locais → PlayerGames → XP e recompensas

Estado da rodada e seus limites

A rodada em andamento (tentativas feitas até agora, se está finalizada, se foi vencida) fica guardada na sessão do usuário, não numa tabela de banco de dados. Ela reseta automaticamente se a rodada guardada não corresponder mais ao conceito atribuído hoje (um novo dia, ou um conceito reatribuído). Isso significa:

• Sair da página e voltar dentro da mesma sessão retoma a rodada exatamente de onde parou, incluindo uma rodada finalizada — uma vitória ou derrota permanece final pelo resto do dia naquela sessão.
• Apenas uma vitória é registrada no servidor (pelo mesmo mecanismo de contagem diária usado pelos demais jogos); uma derrota não é gravada em lugar nenhum fora da sessão.
• Limitação conhecida: como uma derrota não deixa rastro no servidor, sair da conta ou continuar em uma sessão de navegador diferente dá um tabuleiro novo e vazio para o mesmo termo do dia — a nova sessão não tem memória da derrota anterior. Uma vitória não é afetada: ela já foi registrada, então a tela de “já jogou hoje” continua valendo. Isso espelha uma escolha que o mod_playerwords também faz para suas próprias rodadas baseadas em sessão, aceita em troca de não adicionar uma tabela de banco de dados dedicada para uma jogada de mesmo-dia e mesmo-dispositivo.

🦊 Avatares

O PlayerGames tem sua própria coleção de avatares emoji, desbloqueados permanentemente pelo maior nível que o jogador já alcançou — sem loja, sem upload de arquivo, apenas uma recompensa por faixa de nível.

Catálogo e faixas

O catálogo padrão tem 17 avatares emoji divididos em 4 faixas (5 na faixa 1, 4 em cada uma das faixas 2 a 4): 🤖 👾 🦊 🐱 🐶 (faixa 1), 🕵️ 🤺 🧚 🧜 (faixa 2), 🧝 🧙 🦸 🥷 (faixa 3), e 🧛 🦹 🐉 🦁 (faixa 4).

Regra de desbloqueio

Os desbloqueios são baseados no maior nível que o jogador já alcançou, para sempre — não no nível atual, e não restrito à temporada corrente. Toda vez que um jogador ganha XP suficiente para subir de nível, o PlayerGames registra o novo nível apenas se ele superar o melhor nível já guardado para aquele jogador; fechar uma temporada, que zera o XP de temporada, nunca tira um avatar já desbloqueado.

Limiares por faixa

Admins podem alterar o nível mínimo de cada faixa independentemente (Administração do site → Plugins → Plugins locais → PlayerGames → Avatares).

Equipar e exibir

Um jogador pode equipar qualquer avatar já desbloqueado (ou desequipar, voltando à foto de perfil padrão do Moodle) num seletor agrupado por faixa — avatares bloqueados aparecem em tons de cinza junto com o nível exigido. O avatar equipado substitui a foto de perfil padrão no cartão de perfil do Player Hub e no widget do Bloco PlayerGames, e permanece sincronizado entre os dois, já que ambos leem e escrevem através do mesmo gerenciador de avatares.

📘 XP de Aprendizado

O XP de Aprendizado é um pool de XP separado e opcional que espelha o XP por curso ganho no block_playerhud de um estudante para dentro do PlayerGames, puramente para visibilidade entre cursos — nunca é somado ao XP de temporada e nunca afeta níveis, desbloqueios de avatar ou o ranking de temporada.

De onde vem

Quando o block_playerhud está instalado e um estudante ganha ou perde XP de curso, o PlayerGames escuta essa mudança e espelha a diferença no seu próprio total com janela de XP de aprendizado. Nada precisa ser configurado do lado do block_playerhud além de tê-lo instalado — a ponte é opcional e fica inerte se o block_playerhud não estiver presente.

A janela

O XP de Aprendizado não é um total vitalício: só conta o XP ganho dentro de uma janela móvel (padrão de 12 meses, configurável em meses; 0 significa ilimitado/vitalício). Os dados ficam guardados em blocos mensais, então a janela envelhece corretamente mês a mês, e uma tarefa agendada noturna recalcula o total com janela de cada usuário para corrigir qualquer desvio e descartar blocos que já saíram da janela.

Visibilidade

O XP de Aprendizado só é exibido quando ambas as condições são verdadeiras:

• o admin ativou (Administração do site → Plugins → Plugins locais → PlayerGames → XP de Aprendizado), e
• a configuração de participantes do site permite estudantes (students ou both).

Diferente da maioria das outras funcionalidades voltadas ao estudante, a visibilidade não depende de o visualizador estar marcado como staff — um professor que também é um estudante genuíno ganhando XP do PlayerHUD em outro curso ainda vê o próprio XP de aprendizado.

Seu próprio ranking

O XP de Aprendizado tem seu próprio ranking opt-in separado — uma única lista top-50 (não dividida por staff/estudante como o ranking de temporada), controlada por seu próprio toggle de admin. Jogadores com XP com janela igual a zero são excluídos completamente em vez de ocupar uma posição, e cada jogador tem um toggle de opt-in independente do usado na visibilidade do ranking de temporada. A busca de posição para jogadores fora do top 50 segue a mesma regra de desempate do ranking de temporada (maior XP primeiro, depois quem chegou lá primeiro).

Onde aparece

Tanto a página do Player Hub quanto o widget de sidebar do Bloco PlayerGames leem do mesmo gerenciador e seguem as mesmas regras de visibilidade e ranking, então as duas telas estão sempre consistentes entre si.

🏆 Como o Ranking Funciona

O ranking de temporada é opt-in, dividido por grupo de participante, e mostra a um jogador sua própria posição mesmo fora do top 50 visível.

Opt-in e a lista top-50

Os jogadores escolhem se querem aparecer no ranking a partir do próprio perfil. A lista visível é o top 50 por XP de temporada, ordenada por XP decrescente → o momento em que atingiu esse XP crescente → id do usuário crescente — um desempate totalmente determinístico, então dois jogadores com o mesmo XP são ordenados por quem chegou lá primeiro.

Divisão staff / estudante

Os rankings são divididos em dois grupos: estudantes e staff (qualquer um com capacidade de edição de curso em pelo menos um curso, ou a flag de admin do site). Se um visualizador vê um grupo ou os dois depende do próprio papel e da configuração de participantes do site:

• Um estudante ou professor comum vê apenas o ranking do próprio grupo.
• Um admin, ou qualquer membro do staff quando o site está configurado para permitir ambos os grupos, vê ambas as abas — Estudantes e Staff.

Sua própria posição, mesmo fora do top 50

Um jogador que optou por entrar no ranking mas não está no top 50 visível ainda vê sua posição exata — calculada com uma única consulta de contagem indexada usando a mesma regra de ordenação da lista visível, em vez de varrer o ranking inteiro.

Escopo

Esta página descreve o ranking de temporada (ligado ao XP de temporada e reiniciado quando uma temporada fecha). O XP de Aprendizado tem seu próprio ranking separado, único (não dividido por staff/estudante) e com seu próprio opt-in — veja aquela seção para detalhes.

🎓 Finalidade Educacional

O PlayerGames foi projetado para:

• Reforçar aprendizado diário por repetição espaçada (loop estilo Duolingo)
• Motivar os estudantes a acessar a plataforma com mais frequência, desenvolvendo familiaridade com o ambiente educacional de forma natural e engajante
• Fomentar uma competição saudável entre estudantes e professores de diferentes cursos, independentemente de quantos cursos cada participante frequenta ou leciona
• Integrar estudantes e professores de diferentes cursos em torno de uma experiência gamificada comum
• Promover um processo de aprendizado ativo por meio de desafios diários e mecânicas de streak
• Explorar áreas de conhecimento diversas por meio de cartuchos de conceitos — de conteúdo disciplinar específico a temas transversais como o aprendizado de um novo idioma
• Dar visibilidade institucional ao impacto da gamificação (Engajômetro)

Indicado para:

• Instituições com múltiplos cursos gamificados usando o block_playerhud
• Administradores e gestores que queiram medir o impacto da gamificação
• Qualquer grupo de usuários do Moodle (estudantes, professores, managers, admins) que possa ser configurado para participar do Hub

🕹️ Ecossistema PlayerGames

O PlayerGames é o hub de um ecossistema mais amplo de gamificação. Juntos, esses plugins transformam o Moodle em uma experiência imersiva:

• Bloco PlayerGames: Widget companheiro de sidebar para a página inicial do site e o Painel — avatar equipado, nível, XP, streak, jogos do dia e posição no ranking, tudo delegado a este plugin. Requer o local_playergames. 👉 github.com/jeanlucio/moodle-block_playergames

• AI Hub: Broker compartilhado de BYOK (traga sua própria chave) — chaves pessoais e de site Gemini/Groq/DeepSeek/compatível-com-OpenAI, consumidas pelo PlayerGames para geração de cartuchos assistida por IA. Opcional: o PlayerGames continua funcionando pelo core_ai do próprio Moodle sem ele. 👉 github.com/jeanlucio/moodle-local_aihub

• Bloco PlayerHUD: XP, níveis, inventário, drops, missões, classes RPG, história, karma e ranking dentro de cada curso. Seu XP de curso pode opcionalmente espelhar para o pool de XP de Aprendizado do PlayerGames. 👉 github.com/jeanlucio/moodle-block_playerhud

• Filtro PlayerHUD: Permite inserir drops de itens por meio de shortcodes no conteúdo do curso. 👉 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. 👉 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. 👉 github.com/jeanlucio/moodle-mod_playergroup

📦 Requisitos

🛠️ Instalação e Configuração

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

1. Baixe o arquivo .zip ou clone este repositório.
2. Extraia na pasta local/ do seu Moodle.
3. Renomeie para playergames (se necessário). Caminho final: seu-moodle/local/playergames/
4. Acesse Administração do site → Notificações para concluir a instalação.
5. Vá em Administração do site → Plugins → Plugins locais → PlayerGames para configurar temporada, XP, avatares e regras dos jogos.
6. Crie a primeira temporada na página Gerenciar Temporadas.
7. Opcional: instale o local_aihub se quiser geração de cartuchos assistida por IA com chaves pessoais/de site — ver Cadeia de Provedores de IA.

📖 Como Usar

Para Administradores

1. Instale o plugin e conclua o upgrade do Moodle.
2. Opcionalmente instale o local_aihub se quiser geração de cartuchos assistida por IA com chaves pessoais/de site (ver Cadeia de Provedores de IA) — caso contrário, os cartuchos ainda podem ser criados manualmente ou gerados pelo core_ai do próprio Moodle.
3. Crie a primeira temporada na página Gerenciar Temporadas, definindo nome, datas e as recompensas de XP por jogo e jogadas por dia.
4. Opcionalmente ajuste a página Escada de Níveis — altere os limiares de XP e os títulos, restaure a escada padrão ou gere uma linear mais longa.
5. Faça upload ou gere um cartucho de conteúdo na página Cartuchos.
6. Acompanhe o impacto da gamificação no Engajômetro.

Para Professores

1. Se o local_aihub estiver instalado, acesse a página Minhas Chaves de IA dele para configurar uma chave pessoal (opcional — as chaves de site funcionam se o admin as configurou).
2. Use o hub PlayerGames ou qualquer plugin Player — os recursos de IA usarão automaticamente a cadeia de chaves configurada.

Para Estudantes

1. Acesse o Player Hub para ver seu XP, nível, posição no ranking, streak e missões do dia.
2. Jogue os minijogos diários para ganhar XP.
3. Marque ou desmarque “Aparecer no ranking” no seu perfil para controlar sua visibilidade.

🧪 Testes Automatizados

O PlayerGames acompanha uma suíte PHPUnit que cobre o motor de gamificação, o pipeline de cartuchos, as tarefas agendadas, a privacidade e os eventos. Cada push no CI roda a matriz completa (Moodle 4.5 → 5.2, PostgreSQL e MariaDB).

PHPUnit — Testes de Unidade e Integração

vendor/bin/phpunit --testsuite local_playergames

Behat — Testes de Aceitação

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

🔎 Divulgação de Serviço de Terceiros

O PlayerGames inclui geração de cartuchos assistida por IA, de forma opcional. Isso é totalmente opcional — todo o conteúdo pode ser criado manualmente.

Arquitetura

A geração via IA é roteada pelo plugin companheiro local_aihub quando instalado, que é o dono do armazenamento de chaves e do transporte com o provedor; se o Hub não estiver instalado, o PlayerGames recorre ao subsistema core_ai do próprio Moodle, usando os provedores que o administrador do site configurou lá.

Provedores suportados (via local_aihub)

• Google Gemini — https://ai.google.dev/
• Groq — https://console.groq.com/
• DeepSeek — https://platform.deepseek.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. A divulgação completa com os IDs exatos de modelo e destinos de dados está documentada na própria Divulgação de Serviço de Terceiros do local_aihub.

Transmissão de dados

Quando a geração via IA é usada, o prompt montado pelo PlayerGames (tópico, idioma, dificuldade, categorias e qualquer texto de referência opcional fornecido pelo professor) é passado para qualquer que seja a fonte que resolveu a requisição (o Hub ou o core_ai) para processamento. O PlayerGames:

• Não armazena prompts nem respostas da IA além dos conceitos do cartucho criados dentro do Moodle
• Nunca inclui dados de estudante em um prompt de IA

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

Custo

Nenhum é exigido pelo próprio PlayerGames. Se o local_aihub estiver instalado, qualquer custo é o que o provedor cobrar através das chaves BYOK desse plugin; sem ele, o PlayerGames recorre ao core_ai do Moodle, que pode ser gratuito se o administrador do site tiver configurado um provedor institucional sem custo.

Credenciais de Demonstração

Não aplicável — nenhuma credencial é exigida para instalar ou usar o PlayerGames; a geração de cartuchos assistida por IA é totalmente opcional.

📄 Licença

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

Copyright: 2026 Jean Lúcio

Suporte

Encontrou um bug ou tem alguma dúvida? Abra uma issue no rastreador de issues.

Mantenedor

Mantido por Jean Lúcio.