Pular para o conteúdo principal

Configuração

Arquivo principal: plugins/KGInfoServs-BQBetterHud/config.yml

Objetivo desta página: explicar cada linha útil de configuração e o que você pode fazer com ela.

Configuração BetonQuest (obrigatório)​

Em plugins/BetonQuest/config.yml:

conversation:
  default_io: kg_bqhud,menu,chest

Em cada conversa, você também pode forçar:

conversationIO: kg_bqhud

Se você ainda vê kg_hud em default_io, substitua por kg_bqhud.

Estrutura global​

language: "en"
standalone:
  resource-pack:
    output-mode: "folder"
    self-host-port: 8164
    public-url: ""
    output-folder: "plugins/KGInfoServs-BQBetterHud/resourcepack"
    force-pack: false
    pack-prompt: "Resource pack required for dialogue display."
    regenerate-on-startup: false
  x-offset: 0
  layout: ...
  text-alignment: ...
  text-fonts: ...
  y-offset: -200
option-sound:
  key: "minecraft:ui.button.click"
  volume: 1.0
  pitch: 1.0
typewriter:
  enabled: true
  speed: 30
selection-mode: "scroll"
selection-indicator:
  prefix: ""
  selected-color: "<#97deaa>"
  unselected-color: "<gray>"
  hand-base-y: -25
  hand-line-height: 10
  max-option-length: 0
updater:
  auto-download: false

language​

ChavePadrãoEfeito
language"en"Idioma das mensagens do plugin (en ou fr)

Resource Pack (standalone.resource-pack)​

ChavePadrãoEfeito
output-mode"folder"Modo de exportação do pack: folder (geração de pasta) ou self-host (envio direto aos jogadores)
self-host-port8164Porta HTTP usada em self-host
public-url""URL pública do pack em self-host (recomendado em prod)
output-folder"plugins/KGInfoServs-BQBetterHud/resourcepack"Pasta de saída no modo folder
force-packfalseForça a aceitação do pack do lado do cliente
pack-prompt"Resource pack required for dialogue display."Mensagem exibida antes do download
regenerate-on-startupfalseRegenerar automaticamente o pack a cada inicialização

Posição Global (standalone)​

ChavePadrãoEfeito
x-offset0Move todo o HUD no eixo horizontal (direita/esquerda)
y-offset-200Move todo o HUD no eixo vertical

Layout (standalone.layout)​

Você pode mover os elementos com x e y.

Os elementos que suportam um scale:

  • dialogue-bg.scale
  • answer-bg.scale
  • avatar.scale

Referência completa:

ChavePadrãoEfeito
dialogue-bg.x0Posição X do fundo do diálogo
dialogue-bg.y20Posição Y do fundo do diálogo
dialogue-bg.scale1.0Tamanho do fundo do diálogo
answer-bg.x180Posição X do fundo das respostas
answer-bg.y-30Posição Y do fundo das respostas
answer-bg.scale1.0Tamanho do fundo das respostas
npc-name.x10Posição X do nome NPC (popup com opções)
npc-name.y19Posição Y do nome NPC (popup com opções)
npc-name-spoken.x6Posição X do nome NPC (popup sem opções)
npc-name-spoken.y23Posição Y do nome NPC (popup sem opções)
name-bg.x0Posição X do fundo do nome
name-bg.y14Posição Y do fundo do nome
dialogue-text.x10Posição X do texto do diálogo (com opções)
dialogue-text.y32Posição Y do texto do diálogo (com opções)
dialogue-text.split-width166Largura de corte (quebra de linha auto) do texto do diálogo
dialogue-text-spoken.x10Posição X do texto do diálogo (sem opções)
dialogue-text-spoken.y36Posição Y do texto do diálogo (sem opções)
options-scroll.x226Posição X das opções no modo scroll
options-scroll.y-25Posição Y das opções no modo scroll
options-scroll.line-height14Espaçamento vertical das linhas de opções em scroll
options-fixed.x190Posição X das opções no modo fixed
options-fixed.y-25Posição Y das opções no modo fixed
options-fixed.line-height8Espaçamento vertical das linhas de opções em fixed
options-fixed.split-width160Largura máxima do texto de opções em fixed
hand.x175Posição X da mão de seleção
hand.y-26Posição Y base da mão
hand.spacing8Espaçamento vertical entre mãos
avatar.x-20Posição X do avatar NPC
avatar.y0Posição Y do avatar NPC
avatar.scale0.75Tamanho do avatar NPC
text-height8Altura de renderização do texto

Text Alignment (standalone.text-alignment)​

Valores possíveis: left, center, right

ChavePadrãoEfeito
dialogue"center"Alinhamento do texto do diálogo
speaker"left"Alinhamento do nome NPC
options"left"Alinhamento do texto das opções

Text Fonts (standalone.text-fonts)​

ChavePadrãoEfeito
dialogue""Reservado para seleção de fonte por zona
speaker""Reservado para seleção de fonte por zona
options""Reservado para seleção de fonte por zona

Nota importante: na build atual, a renderização usa principalmente a fonte padrão de fonts.yml.

Option Sound (option-sound)​

ChavePadrãoEfeito
key"minecraft:ui.button.click"Som tocado ao mudar de opção
volume1.0Volume do som
pitch1.0Tom do som

Typewriter (typewriter)​

ChavePadrãoEfeito
enabledtrueAtiva/desativa o efeito máquina de escrever
speed30Velocidade de exibição do texto (caracteres por segundo)

Notas de performance:

O plugin usa um sistema de otimização multi-níveis para o efeito typewriter:

  • Transições instantâneas entre etapas de diálogo (sem lag)
  • Renderização otimizada com 5 níveis de performance
  • Fast path para diálogos curtos

Essas otimizações são automáticas e não requerem nenhuma configuração.

Selection Mode (selection-mode)​

ChavePadrãoEfeito
selection-mode"scroll"Modo de seleção: scroll ou fixed

Diferenças entre os modos​

Modo scroll (padrão):

  • Lista rolável clássica
  • A opção selecionada permanece sempre visível
  • Rolagem automática se mais opções do que o espaço disponível
  • Posição configurada via standalone.layout.options-scroll

Modo fixed:

  • Lista fixa com indicador de mão
  • Todas as opções exibidas simultaneamente
  • Janela deslizante para scroll ilimitado
  • Quebra de linha automática segundo split-width
  • Posição configurada via standalone.layout.options-fixed

Recomendação:

  • scroll: ideal para 2-5 opções curtas
  • fixed: ideal para 3-10 opções com texto longo

Selection Indicator (selection-indicator)​

ChavePadrãoEfeito
prefix""Prefixo adicionado à opção selecionada
selected-color"<#97deaa>"Cor da opção selecionada
unselected-color"<gray>"Cor das outras opções
hand-base-y-25Base Y de cálculo da mão de seleção
hand-line-height10Diferença Y entre 2 linhas para a mão
max-option-length0Comprimento máximo da opção (0 = ilimitado)

Updater (updater)​

ChavePadrãoEfeito
auto-downloadfalseDownload automático de atualizações quando disponíveis

Como aplicar as mudanças​

  1. Modificar config.yml.
  2. Executar /bqhud reload.
  3. Verificar no jogo.

Para mudanças visuais (layout, x-offset, y-offset, avatares/backgrounds), sempre faça um teste em condição real.

Fontes avançadas (fonts.yml)

Arquivo: plugins/KGInfoServs-BQBetterHud/fonts.yml

O plugin usa Java AWT para renderização de fontes, o que permite máxima flexibilidade.

Sistema de renderização​

O plugin suporta dois modos de renderização de texto:

  1. Java AWT (padrão): renderização com fontes do sistema ou TTF personalizadas
  2. Minecraft fonts: usa as fontes bitmap do Minecraft (ascii.png, etc.)

Configuração padrão​

default:
  # Tamanho da fonte em pixels (16 = tamanho normal Minecraft)
  scale: 16

  # Caminho para arquivo TTF (relativo a plugins/KGInfoServs-BQBetterHud/fonts/)
  # Exemplos: "font.ttf", "minecraft.ttf", "custom/myfont.ttf"
  # Deixe vazio para usar a fonte do sistema Java padrão
  file: ""

  # Usar as fontes Minecraft em vez da renderização Java AWT
  # true = usa minecraft:font/ascii.png (fontes bitmap)
  # false = renderização com Java AWT (TTF ou sistema)
  use-unifont: false

  # Mesclar com as fontes bitmap Minecraft (caracteres especiais)
  # Inclui: ascii.png, accented.png, nonlatin_european.png
  # Usado apenas quando use-unifont é true
  merge-default-bitmap: true

  # Filtros de idioma (não usados com Java AWT)
  include: []

Prioridade de carregamento das fontes​

O plugin carrega as fontes nesta ordem:

  1. Se file é especificado e existe → Carrega o arquivo TTF
  2. Se file está vazio ou ausente → Usa a fonte do sistema Java
  3. Se use-unifont é true → Usa apenas as fontes Minecraft

Fontes personalizadas​

Você pode definir várias fontes nomeadas:

fonts:
  # Fonte TTF personalizada
  custom_ttf:
    file: "font.ttf"        # Colocar em plugins/KGInfoServs-BQBetterHud/fonts/
    scale: 16
    use-unifont: false
    merge-default-bitmap: false
    include: []

  # Fonte pequena para legendas
  small_text:
    file: ""
    scale: 12
    use-unifont: false
    merge-default-bitmap: false
    include: []

  # Fonte grande para títulos
  large_title:
    file: ""
    scale: 24
    use-unifont: false
    merge-default-bitmap: false
    include: []

Referenciar uma fonte em config.yml​

Nota importante: Na versão atual, a renderização usa principalmente a fonte default definida em fonts.yml.

As chaves standalone.text-fonts em config.yml são reservadas para funcionalidades futuras:

# Reservado para seleção de fonte por zona (recurso futuro)
standalone:
  text-fonts:
    dialogue: ""   # Futuro: referência a fonts.custom_ttf
    speaker: ""
    options: ""

Exemplos de uso​

Usar uma fonte do sistema​

default:
  scale: 16
  file: ""              # Vazio = fonte do sistema
  use-unifont: false

Usar uma fonte TTF personalizada​

  1. Coloque seu arquivo minhafonte.ttf em plugins/KGInfoServs-BQBetterHud/fonts/
  2. Configure fonts.yml:
default:
  scale: 16
  file: "minhafonte.ttf"
  use-unifont: false
  1. Recarregue: /bqhud reload

Usar as fontes Minecraft​

default:
  scale: 16
  file: ""
  use-unifont: true
  merge-default-bitmap: true

Tamanhos recomendados​

ScaleTamanhoUso recomendado
8Muito pequenoTexto secundário, anotações
12PequenoLegendas
16NormalTexto de diálogo padrão (padrão Minecraft)
20GrandeTítulos
24Muito grandeTítulos importantes

Fontes compatíveis​

O sistema Java AWT suporta:

  • TTF (TrueType Font) ✅
  • OTF (OpenType Font) ✅
  • Fontes do sistema instaladas ✅

Troubleshooting fonts​

A fonte personalizada não é exibida​

Causas possíveis:

  1. Arquivo TTF mal colocado (verifique a pasta fonts/)
  2. Nome de arquivo incorreto em fonts.yml
  3. Arquivo TTF corrompido

Solução:

# Verificar os logs após reload
/bqhud reload
# Veja as mensagens "[FontManager]" no console

O texto está muito pequeno/grande​

Ajuste o scale em fonts.yml:

default:
  scale: 20  # Aumentar para ampliar

Depois recarregue: /bqhud reload

Caracteres especiais faltando​

Se você usa uma fonte TTF que não tem todos os caracteres, ative o merge:

default:
  file: "minhafonte.ttf"
  use-unifont: false
  merge-default-bitmap: true  # Adiciona os caracteres Minecraft

Performance​

A renderização Java AWT é otimizada:

  • Geração dos glifos na criação do resource pack (não em tempo real)
  • Cache das texturas no pack
  • Sem sobrecarga no servidor durante os diálogos

Veja também​

Última atualização em por Bossbirdyman