Customização Visual

Este guia explica como personalizar a aparência visual do HUD de diálogo.

🎨 Visão geral

O sistema de renderização standalone permite personalizar:

• Backgrounds: fundos de interface (diálogo, respostas, nome NPC)
• Avatares: imagens dos NPCs
• Layout: posições X/Y de cada elemento
• Scale: tamanho dos elementos visuais

📁 Estrutura das pastas

plugins/KGInfoServs-BQBetterHud/
├── avatars/          # Avatares dos NPCs (PNG)
├── backgrounds/      # Fundos de interface (PNG)
├── fonts/           # Fontes personalizadas (TTF)
└── resourcepack/    # Pack gerado (modo folder)

🖼️ Backgrounds (fundos de interface)

Arquivos disponíveis

Os backgrounds são globais (não vinculados a um NPC específico):

Arquivo	Uso	Dimensões recomendadas
dialogue.png	Fundo da caixa de diálogo	Variável
answer.png	Fundo da zona de respostas	Variável
hand.png	Indicador de seleção (mão)	8x8 pixels
name_start.png	Início do fundo do nome NPC	Variável
name_mid.png	Meio do fundo do nome NPC	Variável
name_end.png	Fim do fundo do nome NPC	Variável

Processo de customização

1. Criar seus PNG com as dimensões desejadas
2. Colocar os arquivos em plugins/KGInfoServs-BQBetterHud/backgrounds/
3. Recarregar com /bqhud reload
4. Testar no jogo

Dica

Os arquivos name_start.png, name_mid.png, name_end.png formam um sistema de "9-slice" para adaptar a largura do fundo ao nome do NPC.

Exemplo: Tema escuro

Para criar um tema escuro personalizado:

# Estrutura dos seus arquivos
backgrounds/
├── dialogue.png      # Fundo preto semi-transparente
├── answer.png        # Fundo cinza escuro
├── hand.png          # Mão branca para contraste
├── name_start.png    # Borda esquerda preta
├── name_mid.png      # Fundo preto repetível
└── name_end.png      # Borda direita preta

Após adicionar:

/bqhud reload

Modo folder vs self-host

• Modo folder: após /bqhud reload, você deve reconstruir e republicar seu resource pack de servidor
• Modo self-host: após /bqhud reload, o pack é automaticamente regenerado e reenviado aos jogadores

🎭 Avatares NPC

Veja a página Avatares e Backgrounds para o sistema de avatares.

📐 Layout: Posicionar os elementos

Sistema de coordenadas

O HUD usa um sistema de coordenadas em pixels:

• Origem (0, 0): ponto de referência da BossBar
• X positivo: para a direita
• X negativo: para a esquerda
• Y positivo: para cima
• Y negativo: para baixo

Offsets globais

Antes de posicionar os elementos individuais, você pode mover todo o HUD:

standalone:
  x-offset: 0      # Move tudo horizontalmente
  y-offset: -200   # Move tudo verticalmente

Exemplos:

• x-offset: 50 → HUD deslocado 50 pixels para a direita
• y-offset: -250 → HUD mais baixo na tela
• y-offset: -150 → HUD mais alto na tela

Elementos configuráveis

Fundos de interface

standalone:
  layout:
    dialogue-bg:
      x: 0
      y: 20
      scale: 1.0    # Tamanho (1.0 = 100%, 1.5 = 150%)

    answer-bg:
      x: 180
      y: -30
      scale: 1.0

    name-bg:
      x: 0
      y: 14

Texto e nome NPC

standalone:
  layout:
    # Nome NPC (com opções)
    npc-name:
      x: 10
      y: 19

    # Nome NPC (sem opções, "spoken")
    npc-name-spoken:
      x: 6
      y: 23

    # Texto diálogo (com opções)
    dialogue-text:
      x: 10
      y: 32
      split-width: 166  # Largura antes da quebra de linha

    # Texto diálogo (sem opções, "spoken")
    dialogue-text-spoken:
      x: 10
      y: 36

    # Altura do texto
    text-height: 8

Opções de resposta

Dois modos disponíveis: scroll e fixed

Modo scroll (lista rolável):

standalone:
  layout:
    options-scroll:
      x: 226
      y: -25
      line-height: 14  # Espaçamento entre as linhas

Modo fixed (lista fixa com indicador):

standalone:
  layout:
    options-fixed:
      x: 190
      y: -25
      line-height: 8
      split-width: 160  # Largura máxima antes da quebra de linha

    hand:  # Indicador de seleção
      x: 175
      y: -26
      spacing: 8  # Espaçamento vertical entre mãos

Avatar NPC

standalone:
  layout:
    avatar:
      x: -20
      y: 0
      scale: 0.75  # Tamanho do avatar (0.5 = 50%, 1.0 = 100%)

Exemplos de layouts personalizados

Layout centralizado

standalone:
  x-offset: 0
  y-offset: -180
  layout:
    dialogue-bg:
      x: 0
      y: 20
      scale: 1.2
    dialogue-text:
      x: 15
      y: 35
      split-width: 180
    avatar:
      x: -25
      y: 5
      scale: 1.0

Layout deslocado para a direita

standalone:
  x-offset: 100
  y-offset: -200
  layout:
    dialogue-bg:
      x: 0
      y: 20
      scale: 1.0
    answer-bg:
      x: 200
      y: -30
      scale: 1.0

Layout compacto (tela pequena)

standalone:
  x-offset: 0
  y-offset: -220
  layout:
    dialogue-bg:
      x: 0
      y: 15
      scale: 0.8
    dialogue-text:
      x: 8
      y: 25
      split-width: 140
    avatar:
      x: -15
      y: 0
      scale: 0.6

🎨 Alinhamento do texto

Você pode escolher o alinhamento para cada seção:

standalone:
  text-alignment:
    dialogue: center  # left, center, right
    speaker: left     # Nome do NPC
    options: left     # Opções de resposta

Exemplos de uso:

• dialogue: center → Texto centralizado para um estilo cinemático
• dialogue: left → Texto alinhado à esquerda para um estilo clássico
• options: right → Opções alinhadas à direita

🔧 Workflow de customização

Passo 1: Preparar seus assets

1. Crie seus PNG em um software de edição de imagem (GIMP, Photoshop, Paint.NET)
2. Use a transparência (canal alpha) para as zonas vazias
3. Respeite as dimensões recomendadas

Passo 2: Testar localmente

1. Coloque seus arquivos nas pastas apropriadas
2. Execute /bqhud reload
3. Teste com um diálogo BetonQuest no jogo
4. Ajuste as posições em config.yml

Passo 3: Iteração

Repita até obter o resultado desejado:

# 1. Modificar config.yml
# 2. Recarregar
/bqhud reload
# 3. Testar no jogo
# 4. Ajustar e recomeçar

Passo 4: Implantação

Modo folder:

1. A pasta plugins/KGInfoServs-BQBetterHud/resourcepack contém os assets gerados
2. Integre este conteúdo no seu resource pack de servidor
3. Rebuild e redistribua seu pack

Modo self-host:

1. O pack é automaticamente regenerado
2. Os jogadores recebem a atualização ao reconectar

📊 Tabela resumida dos scales

Elemento	Chave config	Scale padrão	Efeito do scale
Fundo diálogo	dialogue-bg.scale	1.0	Aumenta/reduz o fundo
Fundo respostas	answer-bg.scale	1.0	Aumenta/reduz o fundo
Avatar NPC	avatar.scale	0.75	Aumenta/reduz o avatar

Valores recomendados:

• 0.5: Muito pequeno (50%)
• 0.75: Pequeno (75%)
• 1.0: Normal (100%)
• 1.25: Grande (125%)
• 1.5: Muito grande (150%)

🚀 Dicas de performance

Otimização dos PNG

Para melhores performances:

1. Comprima seus PNG com ferramentas como TinyPNG ou pngquant
2. Use dimensões razoáveis (máx 512x512 para os backgrounds)
3. Evite imagens enormes que sobrecarregam o resource pack

Tamanho do resource pack

O plugin gera um pack otimizado:

• Compressão automática em ZIP
• Sem arquivos inúteis
• Cache SHA-1 para evitar re-downloads

❓ Perguntas frequentes

O layout não se aplica após /bqhud reload

Solução:

1. Verifique a sintaxe YAML em config.yml
2. Veja os logs do servidor para detectar erros
3. No modo folder, você deve rebuild seu pack de servidor

Os backgrounds não são exibidos

Causas possíveis:

1. Arquivos PNG mal nomeados (respeite a caixa exata)
2. Arquivos corrompidos ou formato inválido
3. Resource pack não carregado pelo cliente

Solução:

/bqhud reload
# Verifique os logs para ver se os backgrounds são detectados

Como voltar ao layout padrão?

Apague suas modificações em config.yml e restaure os valores padrão, depois:

/bqhud reload

📖 Veja também

• Configuração completa
• Avatares e Backgrounds
• Solução de problemas