Solução de problemas

Guia completo para resolver os problemas comuns do plugin.

🚨 Problemas comuns

1. Nenhum HUD aparece em diálogo

Sintoma: O diálogo BetonQuest é exibido no chat clássico em vez do HUD.

Causas possíveis:

Causa	Verificação	Solução
ConversationIO não configurado	Veja plugins/BetonQuest/config.yml	Adicione kg_bqhud em conversation.default_io
Plugin não carregado	Console na inicialização	Verifique erros de carregamento
BetonQuest faltando	/plugins no jogo	Instale BetonQuest
Conflito com antigo KG_Hud	/plugins no jogo	Remova o plugin antigo kg_hud

Solução detalhada:

1. Abra plugins/BetonQuest/config.yml
2. Encontre a seção conversation:
3. Modifique:

conversation:
  default_io: kg_bqhud,menu,chest

4. Reinicie o servidor ou faça /betonquest reload
5. Teste com uma conversa

Alternativa para uma conversa específica:

# No seu arquivo de conversa BetonQuest
conversationIO: kg_bqhud

2. O resource pack não carrega

Sintoma: O HUD não exibe os fundos/avatares, ou erro "Failed to load resource pack".

Modo folder

Problema: O pack gerado não é aplicado aos jogadores.

Solução:

1. Verifique se a pasta existe:

   plugins/KGInfoServs-BQBetterHud/resourcepack/

2. Integre o conteúdo no seu pack de servidor:

   seu-pack-servidor/
   ├── assets/
   │   └── kgbq/          # Copie de resourcepack/assets/kgbq/
   └── pack.mcmeta

3. Rebuild e republique seu pack de servidor

4. Os jogadores devem baixar o novo pack

Modo self-host

Problema: O plugin hospeda o pack mas os jogadores não o recebem.

Verificações:

1. Porta acessível:

   standalone:
     resource-pack:
       self-host-port: 8164  # Deve estar aberta no seu firewall

2. URL pública configurada (recomendado):

   standalone:
     resource-pack:
       public-url: "https://seu-dominio.com"
       # ou
       public-url: "meu-servidor.exemplo.com:8164"

3. Teste o acesso ao pack:

   • URL: http://seu-ip:8164/pack.zip
   • O pack deve ser baixado

4. Verifique os logs:

   [PackServer] HTTP server started on port 8164
   [PackSender] Sending pack to player: PlayerName

Problema de firewall:

Se a porta estiver bloqueada:

1. Abra a porta 8164 (TCP) no seu firewall
2. Verifique as regras iptables (Linux)
3. Configure o port forwarding (host)

3. Os avatares não são exibidos

Sintoma: nameless.png é exibido para todos os NPCs, ou nenhum avatar.

Causas e soluções:

Causa 1: Nome de arquivo incorreto

❌ Incorreto:

plugins/KGInfoServs-BQBetterHud/avatars/
├── André.png          # Maiúscula + acento
├── mercador village.png  # Espaço
└── Jose.PNG           # Extensão em maiúsculas

✅ Correto:

plugins/KGInfoServs-BQBetterHud/avatars/
├── andre.png
├── mercador_village.png
└── jose.png

Causa 2: npc_id mal identificado

O plugin transforma o nome BetonQuest do NPC em npc_id seguindo regras específicas:

1. Mantém apenas o primeiro bloco antes de espaço, vírgula ou ponto e vírgula
2. Remove todos os acentos e caracteres não-ASCII
3. Converte em minúsculas

Lembrete do mapeamento:

Nome BetonQuest	npc_id	Arquivo
André, o Ferreiro	andre	andre.png
José María	jose	jose.png
Müller Schmidt	muller	muller.png

Solução:

Verifique que o nome do arquivo avatar corresponde exatamente ao npc_id gerado seguindo as regras acima.

Causa 3: Arquivo PNG corrompido

Teste:

Abra o arquivo PNG com um editor de imagem. Se não abrir, o arquivo está corrompido.

Solução:

Re-exporte a imagem em PNG com um software confiável (GIMP, Photoshop, Paint.NET).

Causa 4: Pack não recarregado

Solução:

/bqhud reload

No modo folder, rebuild e republique seu pack de servidor.

4. Os backgrounds não mudam

Sintoma: Os fundos personalizados não se aplicam.

Checklist:

• Arquivos colocados em plugins/KGInfoServs-BQBetterHud/backgrounds/
• Nomes exatos (respeitar a caixa):
  • dialogue.png
  • answer.png
  • hand.png
  • name_start.png
  • name_mid.png
  • name_end.png
• Formato PNG válido
• /bqhud reload executado
• Pack de servidor rebuild (modo folder)

Verificação rápida:

# Liste os arquivos backgrounds
ls plugins/KGInfoServs-BQBetterHud/backgrounds/

Verifique se os nomes correspondem exatamente.

5. As posições/scale não se aplicam

Sintoma: As modificações de config.yml não mudam nada visualmente.

Causas possíveis:

Causa 1: Erro de sintaxe YAML

Exemplo de erro:

# ❌ Incorreto (tabulações usadas)
standalone:
	layout:
		avatar:
			x: -20

# ✅ Correto (espaços usados)
standalone:
  layout:
    avatar:
      x: -20

Solução:

1. Verifique a sintaxe YAML com um validador online
2. Use espaços (sem tabulações)
3. Veja os logs após /bqhud reload para erros

Causa 2: Valores fora dos limites

Certos valores podem ser ignorados se fora dos limites razoáveis.

Valores recomendados:

Parâmetro	Min	Max	Padrão
x-offset	-500	500	0
y-offset	-400	0	-200
scale	0.1	3.0	1.0

Causa 3: Cache do cliente

Solução:

1. Faça /bqhud reload no servidor
2. O jogador reconecta
3. Ou force o reload do resource pack (F3 + T no jogo)

6. Fonte personalizada não é exibida

Sintoma: O texto usa a fonte padrão apesar da configuração de fonts.yml.

Verificações:

1. Arquivo TTF colocado corretamente:

   plugins/KGInfoServs-BQBetterHud/fonts/minhafonte.ttf

2. Configuração correta em fonts.yml:

   default:
     scale: 16
     file: "minhafonte.ttf"  # Nome exato do arquivo
     use-unifont: false

3. Logs após /bqhud reload:

   [FontManager] Loading font: minhafonte.ttf
   [FontManager] Font loaded successfully

Erros comuns:

Erro nos logs	Causa	Solução
Font file not found: minhafonte.ttf	Arquivo faltando	Verifique o caminho e o nome
Failed to load font: invalid format	TTF corrompido	Baixe um novo arquivo
Font rendering error	Incompatibilidade Java	Use uma fonte TTF padrão

7. Efeito typewriter não funciona

Sintoma: O texto é exibido instantaneamente em vez do efeito máquina de escrever.

Verificação:

typewriter:
  enabled: true   # Deve ser true
  speed: 30       # Caracteres por segundo (ajuste se necessário)

Velocidades recomendadas:

• 10: Muito lento (efeito dramático)
• 30: Normal (padrão)
• 60: Rápido
• 100: Muito rápido

Nota: Se enabled: false, o texto é exibido instantaneamente.

8. Modo de seleção fixed não funciona

Sintoma: O modo fixed não muda nada, sempre em modo scroll.

Configuração necessária:

selection-mode: "fixed"  # Não "Fixed" nem "FIXED"

Diferenças visuais:

Modo	Comportamento
scroll	Lista rolável, opção selecionada em cor
fixed	Lista fixa, indicador de mão (hand.png)

Se você não vê a mão no modo fixed, verifique se backgrounds/hand.png existe.

9. Comando /bqhud recusado

Sintoma: "You don't have permission to use this command"

Solução:

Adicione a permissão ao seu grupo ou jogador:

# No seu plugin de permissões (LuckPerms, etc.)
permissions:
  - bqhud.admin

Teste rápido (OP apenas):

/op SeuNome
/bqhud reload

10. Erro de licença ao iniciar

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

Mensagens de erro possíveis:

[BQBetterHud] License validation failed
[BQBetterHud] License key not found
[BQBetterHud] Unable to contact license server

Soluções:

1. Verificar o arquivo de licença:

   plugins/KGInfoServs-BQBetterHud/license.key

2. Conteúdo do arquivo:

   • Uma única linha
   • Sem espaços antes/depois
   • Formato UUID válido

3. Acesso à Internet: O servidor deve poder contatar o servidor de licenças. Verifique:

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

4. Contato suporte: Se o problema persistir, contate KGInfoServs no Discord.

🔧 Ferramentas de diagnóstico

Verificar o estado do plugin

/plugins
# Procure "KGInfoServs-BQBetterHud" em verde

Ver os logs em tempo real

Linux:

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

Windows (PowerShell):

Get-Content logs/latest.log -Wait | Select-String -Pattern "bqhud" -CaseSensitive:$false

Testar uma conversa BetonQuest

/q conversation <nome_conversa> <jogador>

Forçar o reload do resource pack (cliente)

No jogo, pressione F3 + T para recarregar os recursos.

📋 Checklist de solução de problemas rápida

Antes de pedir ajuda, verifique:

• plugins/BetonQuest/config.yml contém kg_bqhud em conversation.default_io
• /bqhud reload executado após cada modificação
• Modo de resource pack configurado corretamente (folder ou self-host)
• Avatares/backgrounds nos locais corretos com nomes corretos
• Logs do servidor consultados para erros
• Permissão bqhud.admin concedida
• BetonQuest instalado e funcional
• Versão Minecraft suportada (1.21+)

🆘 Pedir ajuda

Se o problema persistir após seguir este guia:

1. Reúna as informações:

   • Versão do Minecraft
   • Versão do Paper/Spigot
   • Versão do BetonQuest
   • Versão do KG_BQBetterHud
   • Logs do servidor (últimas 50 linhas com erros)
   • Seu config.yml

2. Contate o suporte:

   • Discord KGInfoServs: https://discord.gg/SZhD9AGUXW
   • Crie um ticket com todas as informações acima

📚 Veja também

• Configuração
• Avatares e Backgrounds
• Customização Visual
• Instalação