Solução de problemas

Guia completo para resolver os problemas comuns do plugin.

O menu de quests não abre

Sintoma: O comando /quests não faz nada ou exibe um erro.

Causa	Verificação	Solução
Plugin não carregado	/plugins no jogo	Verifique os erros de carregamento nos logs
BetonQuest ausente	/plugins no jogo	Instale o BetonQuest 3.0+
BD inacessível	/kgquests health	Verifique se o BetonQuest tem o MySQL ativado
Erro de licença	Logs do servidor	Verifique o arquivo license.key

Solução:

1. Verifique se o plugin está carregado (verde em /plugins)
2. Consulte os logs na inicialização em busca de erros
3. Verifique a conexão com o BD: /kgquests health

As quests aparecem como bloqueadas

Sintoma: O menu abre, mas todas as quests têm o status "Bloqueado".

Causa	Solução
Template trackedQuest ausente	Adicione templates: [trackedQuest] no package BQ
Event activeQuest não disparado	Verifique se o event é realmente chamado na lógica do BQ
Tag .questTrackable ausente	Teste manualmente: /bq tag add <jogador> ma_quete.questTrackable

Solução:

1. Verifique o template no package do BetonQuest:

   templates:
     - trackedQuest

2. Verifique se o event de ativação existe:

   events:
     activer: "activeQuest ma_quete"

3. Teste manualmente adicionando a tag:

   /bq tag add <jogador> ma_quete.questTrackable

As quests não aparecem na categoria correta

Sintoma: As quests aparecem na categoria errada ou na categoria padrão (other).

Causa principal: O questCategory no BetonQuest não corresponde ao configKey da categoria em config.yml.

Verificações:

1. Compare os valores exatamente (o valor diferencia maiúsculas de minúsculas):

   # config.yml
   menuItems:
     categories:
       dailyQuests:        # ← É essa chave (configKey) que conta
         displayName: "Daily"

   # BetonQuest package.yml
   questParameters:
     questCategory: dailyQuests  # ← Deve ser identico a chave YAML

2. Para as subcategorias, combine os configKey pai e filho com um ponto:

   questCategory: dailyQuests.monsters  # Formato: configKey.subConfigKey

3. Se nenhum questCategory for definido, a quest cai na categoria definida por defaultCategory de config.yml.

Migração a partir de uma versão antiga

Antes de uma atualização recente, questCategory usava o displayName (ex: "Story"). Agora é necessário o configKey (ex: story). Se todas as suas quests foram bruscamente parar na categoria other, essa é provavelmente a causa.

Modifique seus package.yml do BetonQuest:

• questCategory: "Story" → questCategory: story
• questCategory: "Daily" → questCategory: dailyQuests
• questCategory: "Daily.Monsters" → questCategory: dailyQuests.monsters

O scoreboard ou o menu permanece no idioma antigo após /questlang

Sintoma: Um jogador executa /questlang fr-FR (ou /ql en-US), mas o scoreboard / o diário de quests não muda de idioma imediatamente.

Causa: Você está usando uma versão anterior do plugin que não detecta a mudança de idioma.

Solução:

1. Atualize o plugin para a versão mais recente
2. Após a atualização, o plugin intercepta automaticamente /questlang e /ql:
   • O scoreboard é reconstruído no novo idioma
   • O menu de quests aberto (se houver um) é atualizado
3. Nenhum comando adicional é necessário

Teste rápido

1. Configure suas quests em multi-idioma (fr-FR + en-US) em quests_config.yml
2. Conecte-se, execute /questlang en-US
3. O scoreboard deve mudar para o inglês imediatamente
4. Execute novamente /questlang fr-FR para voltar ao francês

O scoreboard não é exibido

Sintoma: As quests acompanhadas não mostram um scoreboard.

Causa	Solução
Scoreboard desativado globalmente	Verifique scoreboard.enabled: true em config.yml
Nenhuma quest sendo acompanhada	O jogador deve acompanhar pelo menos uma quest
Quest sem etapas	Defina os steps em quests_config.yml
Conflito com outro plugin	Verifique conflitos com TAB, Featherboard, etc.

Solução:

1. Verifique a configuração global do scoreboard:

   scoreboard:
     enabled: true

2. O jogador deve acompanhar uma quest:

   /quests track <quest_id>

3. Verifique se a quest tem etapas em quests_config.yml

4. Teste o scoreboard:

   /kgquests scoreboard on

O cache não é atualizado

Sintoma: As mudanças de quest não são refletidas imediatamente.

Soluções:

1. Force um refresh para um jogador:

   /kgquests refresh <jogador>

2. Recarregue a configuração:

   /questsreload

3. Verifique as taxas de acerto:

   /kgquests stats

TTL do cache

O cache local (L1) expira após 1-2 minutos, o cache Redis (L2) após 2 minutos. Se você precisar de um refresh imediato, use /kgquests refresh.

Problemas multi-servidor (Redis)

Sintoma: Os dados não se sincronizam entre servidores.

Verificações:

1. Conexão Redis: /kgquests redis
2. Mesmo Redis para todos os servidores (verifique host:port em cada config.yml)
3. Mesmo banco de dados do BetonQuest para todos os servidores
4. Firewall: porta Redis (6379) aberta entre os servidores
5. Force um refresh: /kgquests refresh <jogador>

Veja Multi-servidor para o guia detalhado.

Erros de banco de dados

Sintoma: Erros SQLException ou HikariPool nos logs.

Causa	Solução
MySQL desativado no BQ	Ative mysql.enabled: true no config.yml do BetonQuest
Credenciais incorretas	Verifique a configuração MySQL do BetonQuest
Servidor MySQL parado	Reinicie o MySQL/MariaDB
Pool de conexões esgotado	Reinicie o plugin
Timeout de rede	Verifique a conexão entre o servidor MC e o BD

Solução:

1. Verifique a conexão: /kgquests health
2. Verifique se o BetonQuest tem o MySQL ativado:

   # plugins/BetonQuest/config.yml
   mysql:
     enabled: true

3. Teste a conexão manualmente:

   mysql -h localhost -u betonquest -p betonquest

Erro de licença na inicialização

Sintoma: O plugin não carrega e exibe um erro de licença.

Soluções:

1. Verifique o arquivo de licença:

   plugins/KGInfoServs-QuestsTrack/license.key

2. Conteúdo do arquivo: uma única linha, sem espaços antes/depois

3. Acesso à Internet: o servidor precisa conseguir contatar o servidor de licenças. Verifique:

   • Firewall de saída
   • Conexão à Internet do servidor
   • Proxy, se aplicável

4. Contate o suporte: se o problema persistir, contate a KGInfoServs no Discord

Desempenho degradado

Sintoma: O menu demora para abrir, o scoreboard trava.

Diagnósticos:

/kgquests stats      # Taxa de acerto do cache
/kgquests memory     # Memória JVM
/kgquests health     # Saúde geral

Indicadores:

Indicador	Problema	Solução
Cache hit < 85%	Cache ineficiente	Verifique o número de jogadores em relação ao tamanho do cache
Latência do BD > 50ms	BD lento	Otimize o MySQL, aproxime o BD do servidor MC
Latência Redis > 10ms	Redis remoto	Coloque o Redis na mesma rede
Memória > 80%	Memória insuficiente	Aumente o heap da JVM (-Xmx)

Ferramentas de diagnóstico

Comandos de diagnóstico

/kgquests health      # Verificação geral de todos os componentes
/kgquests stats       # Estatísticas do cache (taxa de acerto, miss)
/kgquests redis       # Estado da conexão Redis
/kgquests redis <j>   # Cache Redis de um jogador específico
/kgquests memory      # Memória JVM e caches

Ver os logs em tempo real

Linux:

tail -f logs/latest.log | grep -i queststrack

Windows (PowerShell):

Get-Content logs/latest.log -Wait | Select-String -Pattern "queststrack"

Checklist de solução de problemas rápida

Antes de pedir ajuda, verifique:

• Plugin carregado (verde em /plugins)
• BetonQuest instalado e funcional
• MySQL ativado no BetonQuest (mysql.enabled: true)
• BD acessível (/kgquests health)
• Configuração válida (/questsreload sem erro)
• Template trackedQuest nas quests
• questCategory corresponde ao configKey (chave YAML) de uma categoria de config.yml
• Events do BetonQuest configurados (activeQuest, etc.)
• quests_config.yml preenchido (title, steps)
• Logs do servidor consultados em busca de erros

Pedir ajuda

Se o problema persistir:

1. Reúna as informações:

   • Versão do Minecraft, Paper, Java
   • Versão do BetonQuest e do QuestsTracker
   • Resultado de /kgquests health
   • Logs do servidor (linhas com erros)
   • Seu config.yml (sem as senhas)

2. Contate o suporte:

   • Discord da KGInfoServs: https://discord.gg/SZhD9AGUXW

Veja também

• Configuração — Referência das chaves de configuração
• Integração com o BetonQuest — Events e templates
• Multi-servidor — Configuração Redis
• Instalação — Guia de instalação