Solucao de problemas

Guia completo para resolver os problemas comuns do plugin.

O menu de quests nao abre

Sintoma: O comando /quests nao faz nada ou exibe um erro.

Causa	Verificacao	Solucao
Plugin nao carregado	/plugins no jogo	Verifique os erros de carregamento nos logs
BetonQuest ausente	/plugins no jogo	Instale o BetonQuest 3.0+
BDD inacessivel	/kgquests health	Verifique se o BetonQuest tem o MySQL ativado
Erro de licenca	Logs do servidor	Verifique o arquivo license.key

Solucao:

1. Verifique se o plugin esta carregado (verde em /plugins)
2. Consulte os logs na inicializacao para erros
3. Verifique a conexao BDD: /kgquests health

As quests aparecem como bloqueadas

Sintoma: O menu abre, mas todas as quests tem o status "Bloqueado".

Causa	Solucao
Template trackedQuest ausente	Adicione templates: [trackedQuest] no pacote BQ
Event activeQuest nao acionado	Verifique se o event e chamado corretamente na logica BQ
Tag .questTrackable ausente	Teste manualmente: /bq tag add <jogador> ma_quete.questTrackable

Solucao:

1. Verifique o template no pacote BetonQuest:

   templates:
     - trackedQuest

2. Verifique se o event de ativacao existe:

   events:
     activer: "activeQuest ma_quete"

3. Teste manualmente adicionando a tag:

   /bq tag add <jogador> ma_quete.questTrackable

As quests nao aparecem na categoria correta

Sintoma: As quests aparecem na categoria errada ou na categoria padrao.

Causa principal: O questCategory no BetonQuest nao corresponde ao displayName da categoria no config.yml.

Verificacoes:

1. Compare os valores exatamente (maiusculas/minusculas e acentos inclusos):

   # config.yml
   menuItems:
     categories:
       dailyQuests:
         displayName: "Daily"  # ← E este valor que importa

   # BetonQuest package.yml
   questParameters:
     questCategory: "Daily"  # ← Deve ser identico

2. Se nenhum displayName for definido, o plugin utiliza a chave de configuracao (ex: dailyQuests).

3. Para subcategorias:

   questCategory: "Daily.Monsters"  # Formato: displayName.displayName_sub

Acentos e maiusculas/minusculas

"Diaria" ≠ "diaria" ≠ "DIARIA". A correspondencia e exata.

O scoreboard nao aparece

Sintoma: As quests acompanhadas nao mostram um scoreboard.

Causa	Solucao
Scoreboard desativado globalmente	Verifique scoreboard.enabled: true no config.yml
Nenhuma quest acompanhada	O jogador deve acompanhar pelo menos uma quest
Quest sem etapas	Defina as steps no quests_config.yml
Conflito com outro plugin	Verifique conflitos com TAB, Featherboard, etc.

Solucao:

1. Verifique a configuracao global do scoreboard:

   scoreboard:
     enabled: true

2. O jogador deve acompanhar uma quest:

   /quests track <quest_id>

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

4. Teste o scoreboard:

   /kgquests scoreboard on

O cache nao se atualiza

Sintoma: As mudancas nas quests nao se refletem imediatamente.

Solucoes:

1. Force uma atualizacao para um jogador:

   /kgquests refresh <jogador>

2. Recarregue a configuracao:

   /questsreload

3. Verifique as taxas de acerto:

   /kgquests stats

TTL do cache

O cache local (L1) expira apos 1-2 minutos, o cache Redis (L2) apos 2 minutos. Se voce precisar de uma atualizacao imediata, use /kgquests refresh.

Problemas multi-servidor (Redis)

Sintoma: Os dados nao se sincronizam entre servidores.

Verificacoes:

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

Veja Multi-servidor para o guia detalhado.

Erros de banco de dados

Sintoma: Erros SQLException ou HikariPool nos logs.

Causa	Solucao
MySQL desativado no BQ	Ative mysql.enabled: true no BetonQuest config.yml
Credenciais incorretas	Verifique a config MySQL do BetonQuest
Servidor MySQL parado	Reinicie o MySQL/MariaDB
Pool de conexoes esgotado	Reinicie o plugin
Timeout de rede	Verifique a conexao entre o servidor MC e o BDD

Solucao:

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

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

3. Teste a conexao manualmente:

   mysql -h localhost -u betonquest -p betonquest

Erro de licenca na inicializacao

Sintoma: O plugin nao carrega e exibe um erro de licenca.

Solucoes:

1. Verifique o arquivo de licenca:

   plugins/kginfoservs_queststrack/license.key

2. Conteudo do arquivo: uma unica linha, sem espacos antes/depois

3. Acesso a Internet: o servidor deve conseguir contatar o servidor de licencas. Verifique:

   • Firewall de saida
   • Conexao a Internet do servidor
   • Proxy, se aplicavel

4. Contate o suporte: se o problema persistir, entre em contato com KGInfoServs no Discord

Desempenho degradado

Sintoma: O menu e lento para abrir, o scoreboard trava.

Diagnosticos:

/kgquests stats      # Taxa de acerto do cache
/kgquests benchmark  # Latencias detalhadas
/kgquests memory     # Memoria JVM
/kgquests health     # Saude global

Indicadores:

Indicador	Problema	Solucao
Cache hit < 85%	Cache ineficaz	Verifique o numero de jogadores vs tamanho do cache
Latencia BDD > 50ms	BDD lento	Otimize o MySQL, aproxime o BDD do servidor MC
Latencia Redis > 10ms	Redis distante	Coloque o Redis na mesma rede
Memoria > 80%	Memoria insuficiente	Aumente o heap JVM (-Xmx)

Ferramentas de diagnostico

Comandos de diagnostico

/kgquests health      # Verificacao global de todos os componentes
/kgquests stats       # Estatisticas do cache (taxa de acerto, erros)
/kgquests redis       # Estado da conexao Redis
/kgquests redis <j>   # Cache Redis de um jogador especifico
/kgquests memory      # Memoria JVM e caches
/kgquests benchmark   # Testes de latencia (BDD, Redis, cache)
/kgquests analytics   # Estatisticas de conclusao das quests

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 solucao rapida

Antes de pedir ajuda, verifique:

• Plugin carregado (verde em /plugins)
• BetonQuest instalado e funcional
• MySQL ativado no BetonQuest (mysql.enabled: true)
• BDD acessivel (/kgquests health)
• Configuracao valida (/questsreload sem erro)
• Template trackedQuest nas quests
• questCategory corresponde ao displayName (maiusculas/minusculas e acentos)
• Events BetonQuest configurados (activeQuest, etc.)
• quests_config.yml preenchido (title, steps)
• Logs do servidor consultados para erros

Pedir ajuda

Se o problema persistir:

1. Reuna as informacoes:

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

2. Contate o suporte:

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

Veja tambem

• Configuracao — Referencia das chaves de configuracao
• Integracao BetonQuest — Events e templates
• Multi-servidor — Configuracao Redis
• Instalacao — Guia de instalacao