Instalação

Guia passo a passo para instalar e configurar o KG_BQBetterHud no seu servidor Minecraft.

Pré-requisitos

Antes de instalar o plugin, certifique-se de ter:

Pré-requisito	Versão mínima	Recomendado
Servidor	Paper 1.21+	Paper última versão
BetonQuest	3.0+	BetonQuest 3.0+
Java	Java 17+	Java 21
Licença	Chave de licença válida KGInfoServs	-

Compatibilidade

O plugin funciona apenas no Paper ou seus forks (Purpur, Pufferfish). Spigot não é suportado devido às limitações da API.

Passo 1: Baixar o plugin

1. Baixe o arquivo JAR da sua área de cliente KGInfoServs
2. Verifique se o arquivo se chama: KGInfoServs-BQBetterHud-X.X.X.jar

Passo 2: Instalação no servidor

1. Pare seu servidor (se iniciado)

2. Copie o JAR para a pasta plugins/:

   seu-servidor/
   └── plugins/
       ├── BetonQuest.jar
       └── KGInfoServs-BQBetterHud-X.X.X.jar  # ← Novo arquivo

3. Inicie o servidor

O plugin irá gerar automaticamente sua pasta de configuração:

plugins/KGInfoServs-BQBetterHud/
├── config.yml           # Configuração principal
├── fonts.yml            # Configuração de fontes
├── messages_en.yml      # Mensagens em inglês
├── messages_fr.yml      # Mensagens em francês
├── license.key          # Arquivo de licença (a preencher)
├── avatars/            # Pasta para avatares NPC
│   └── nameless.png    # Avatar padrão
├── backgrounds/        # Pasta para fundos UI
└── resourcepack/       # Pack gerado (modo folder)

Passo 3: Configuração da licença

1. Abra o arquivo plugins/KGInfoServs-BQBetterHud/license.key

2. Substitua PASTE_YOUR_LICENSE_KEY_HERE pela sua chave de licença

   Exemplo:

   a1b2c3d4-e5f6-7890-abcd-ef1234567890

3. Salve o arquivo

4. Reinicie o servidor

5. Verifique nos logs:

   [BQBetterHud] License validated successfully
   [BQBetterHud] Standalone mode initialized

Problema de licença?

Se você vir um erro de licença, consulte a seção Solução de problemas - Erro de licença.

Passo 4: Configuração BetonQuest (OBRIGATÓRIO)

O plugin requer configuração no BetonQuest para funcionar.

Opção 1: Configuração global (recomendada)

Abra plugins/BetonQuest/config.yml e modifique:

conversation:
  default_io: kg_bqhud,menu,chest

Esta configuração se aplica a todas as conversas por padrão.

Migração desde kg_hud

Se você usava o plugin antigo kg_hud, substitua-o por kg_bqhud:

# ❌ Antigo (a substituir)
conversation:
  default_io: kg_hud,menu,chest

# ✅ Novo
conversation:
  default_io: kg_bqhud,menu,chest

Opção 2: Configuração por conversa

Se você preferir ativar o HUD apenas para certas conversas:

# No seu arquivo de conversa BetonQuest
conversations:
  guide_intro:
    quester: "Guia"
    conversationIO: kg_bqhud  # ← Ativa o HUD para esta conversa
    first: "start"
    NPC_options:
      start:
        text: "Olá aventureiro!"
        pointer: escolha
    player_options:
      escolha:
        text:
          - "Olá!"
          - "Quem é você?"

Recarregar BetonQuest

Após modificação:

/betonquest reload
# ou reinicie o servidor

Passo 5: Configuração do resource pack

O plugin gera automaticamente um resource pack contendo os assets visuais (avatares, fundos, fontes).

Escolha seu modo de distribuição:

Modo folder (recomendado para produção)

O plugin gera os arquivos em uma pasta, você os integra no seu pack de servidor.

Configuração:

standalone:
  resource-pack:
    output-mode: "folder"
    output-folder: "plugins/KGInfoServs-BQBetterHud/resourcepack"
    regenerate-on-startup: false

Workflow:

1. O plugin gera os assets em resourcepack/
2. Você copia o conteúdo para seu pack de servidor:

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

3. Rebuild e redistribua seu pack via seu host

Vantagens:

• Controle total sobre o pack
• Integração com seus outros assets
• Nenhuma porta a abrir

Integração com ItemsAdder

Se você usa ItemsAdder para gerenciar seu resource pack do servidor, você pode mesclar automaticamente os assets do KG_BQBetterHud.

Configuração do ItemsAdder:

Abra plugins/ItemsAdder/config.yml e adicione na seção merge_other_plugins_resourcepacks_folders:

resource-pack:
  merge_other_plugins_resourcepacks_folders:
    - KGInfoServs-BQBetterHud/resourcepack

Fluxo de trabalho:

1. KG_BQBetterHud gera seus assets em resourcepack/
2. ItemsAdder mescla automaticamente esses assets em seu pack
3. ItemsAdder distribui o pack final aos jogadores

Vantagens:

• Mesclagem automática com seus itens customizados
• Distribuição simplificada via ItemsAdder
• Sem manipulação manual de arquivos

Recarregamento

Após modificação, execute /iazip para regenerar o pack do ItemsAdder com os assets do KG_BQBetterHud.

Modo self-host (desenvolvimento/teste)

O plugin hospeda e envia automaticamente o pack aos jogadores.

Configuração:

standalone:
  resource-pack:
    output-mode: "self-host"
    self-host-port: 8164
    public-url: "https://seu-dominio.com"  # Recomendado
    force-pack: false
    pack-prompt: "Resource pack necessário para exibição dos diálogos."

Pré-requisitos:

• Porta 8164 (TCP) aberta no seu firewall
• URL pública acessível (domínio ou IP público)

Vantagens:

• Atualização automática após /bqhud reload
• Sem manipulação manual
• Ideal para testes

Produção

O modo self-host não é recomendado para produção. Use folder e um host de resource pack dedicado (CDN, site, etc.).

Passo 6: Primeira configuração

Antes de testar no jogo, configure os parâmetros básicos.

1. Idioma das mensagens

language: "fr"  # ou "en"

2. Posição global do HUD

standalone:
  x-offset: 0      # Deslocamento horizontal (0 = centralizado)
  y-offset: -200   # Deslocamento vertical (-200 = posição padrão)

3. Modo de seleção

selection-mode: "scroll"  # ou "fixed"

• scroll: Lista rolável clássica
• fixed: Lista fixa com indicador de mão

4. Efeito typewriter

typewriter:
  enabled: true
  speed: 30  # Caracteres por segundo

5. Recarregar a configuração

/bqhud reload

Passo 7: Teste no jogo

1. Conecte-se ao servidor

2. Aceite o resource pack (se solicitado)

3. Inicie uma conversa BetonQuest com um NPC:

   /q conversation <nome_conversa> <seu_nome>

4. Verifique se o HUD é exibido corretamente

Checklist de verificação

• O HUD é exibido (BossBar com fundo de diálogo)
• O nome do NPC está visível
• O texto do diálogo é exibido
• As opções de resposta são exibidas
• A seleção muda com as teclas (padrão: números)
• O efeito typewriter funciona (se ativado)

Problema de exibição?

Se o HUD não for exibido, consulte Solução de problemas - Nenhum HUD em diálogo.

Passo 8: Personalização (opcional)

Uma vez que o plugin esteja funcional, você pode personalizar:

Avatares NPC

Coloque seus PNG em plugins/KGInfoServs-BQBetterHud/avatars/

Exemplo:

avatars/
├── andre.png       # Para um NPC chamado "André"
├── mercador.png
└── guarda.png

Veja Avatares e Backgrounds para o mapeamento detalhado.

Backgrounds personalizados

Coloque seus PNG em plugins/KGInfoServs-BQBetterHud/backgrounds/

Arquivos disponíveis:

• dialogue.png
• answer.png
• hand.png
• name_start.png, name_mid.png, name_end.png

Posições e tamanhos

Ajuste em config.yml:

standalone:
  layout:
    avatar:
      x: -20
      y: 0
      scale: 0.75
    dialogue-bg:
      x: 0
      y: 20
      scale: 1.0

Veja Customização Visual para o guia completo.

Fontes personalizadas

Coloque seus arquivos TTF em plugins/KGInfoServs-BQBetterHud/fonts/

Configure fonts.yml:

default:
  scale: 16
  file: "minhafonte.ttf"
  use-unifont: false

Veja Configuração - Fontes avançadas para mais detalhes.

Comandos de administrador

Comando	Descrição	Permissão
/bqhud reload	Recarrega a configuração e regenera o resource pack	bqhud.admin
/bqhud update	Baixa uma atualização disponível	bqhud.admin
/bqhud	Exibe a ajuda	bqhud.admin

Atualização do plugin

Para atualizar para uma nova versão:

1. Pare o servidor
2. Substitua o JAR em plugins/
3. Inicie o servidor
4. Verifique os logs para a nova versão
5. Execute /bqhud reload

Backup

Antes de qualquer atualização, faça backup da sua pasta plugins/KGInfoServs-BQBetterHud/ para manter suas configurações e assets.

Solução de problemas

Se você encontrar problemas durante a instalação, consulte:

• Solução de problemas - Guia completo de solução de problemas
• Discord KGInfoServs - Suporte da comunidade

Próximos passos

Agora que o plugin está instalado:

1. Personalize os avatares dos seus NPCs
2. Ajuste as posições e cores
3. Teste com seus jogadores
4. Consulte a Configuração completa

Bem-vindo ao ecossistema KG_BQBetterHud! 🎉