Avatares e backgrounds

Vinculação automática de avatar NPC

A vinculação é 100% automática se o nome do arquivo do avatar corresponder ao npc_id do NPC.

Algoritmo de mapeamento

O plugin transforma o nome BetonQuest do NPC em npc_id segundo estas regras:

1. Pega o nome completo do NPC definido no BetonQuest
2. Mantém apenas o primeiro bloco antes de espaço, vírgula ou ponto e vírgula
3. Remove todos os acentos e caracteres não-ASCII (normalização)
4. Converte em minúsculas
5. Procura o arquivo PNG correspondente em avatars/

Exemplos de mapeamento simples

Nome NPC BetonQuest	npc_id gerado	Arquivo esperado
Andre	andre	andre.png
Mercador	mercador	mercador.png
Guard_Captain	guard_captain	guard_captain.png

Exemplos de mapeamento complexo

Nome NPC BetonQuest	npc_id gerado	Arquivo esperado	Explicação
André, o Ferreiro	andre	andre.png	Remove acento, pega antes da vírgula
José María	jose	jose.png	Remove acentos, pega antes do espaço
François-Xavier	francois-xavier	francois-xavier.png	Mantém o hífen, remove o acento
Müller	muller	muller.png	Normaliza o ü em u
Señor Lopez	senor	senor.png	Normaliza ñ em n, pega antes do espaço
Étienne; Capitão	etienne	etienne.png	Remove acento, pega antes do ponto e vírgula
王小明	(vazio)	nameless.png	Caracteres não-ASCII → fallback
123_Guard	123_guard	123_guard.png	Números e underscore permitidos

Avatar padrão (fallback)

Se nenhum avatar corresponder ao npc_id, o plugin usa automaticamente:

• Arquivo: nameless.png
• Local: plugins/KGInfoServs-BQBetterHud/avatars/nameless.png
• Este arquivo é automaticamente copiado na primeira inicialização

Onde colocar os avatares

Pasta

plugins/KGInfoServs-BQBetterHud/avatars/

Regras para os arquivos

Regra	Detalhe
Formato	PNG apenas (com transparência alpha suportada)
Nome	Deve corresponder exatamente ao npc_id (minúsculas, sem acentos)
Extensão	.png (obrigatório)
Tamanho recomendado	64x64, 128x128 ou 256x256 pixels
Transparência	Suportada (canal alpha)

Exemplos de nomes válidos

avatars/
├── andre.png
├── mercador.png
├── guard_captain.png
├── francois-xavier.png
├── jose.png
├── nameless.png          # Fallback padrão
└── senor.png

Dimensões recomendadas

Tamanho	Uso	Qualidade
64x64	Estilo pixel art	Boa
128x128	Estilo semi-realista	Muito boa
256x256	Estilo alta definição	Excelente
512x512	Ultra HD (desaconselhado)	Sobrecarga inútil

Recomendação: Use 128x128 para um bom compromisso qualidade/performance.

Backgrounds (fundos UI)

Os backgrounds não estão vinculados automaticamente a cada NPC.

Eles são globais e substituem o estilo visual da interface.

Pasta:

• plugins/KGInfoServs-BQBetterHud/backgrounds/

Arquivos suportados:

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

Mover e escalar o avatar / os fundos

Você pode ajustar as posições e tamanhos em config.yml:

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

• x / y: deslocamento
• scale: tamanho (somente nos blocos que expõem esta chave)

Workflow completo: Adicionar um avatar

Passo 1: Identificar o npc_id

Veja o nome do seu NPC no BetonQuest e determine o npc_id:

Exemplo com BetonQuest:

# No seu arquivo conversations/village.yml
quests:
  mercador_village:
    NPC_name: "André, o Ferreiro"
    # npc_id será: andre

Passo 2: Criar o avatar

1. Crie ou encontre uma imagem PNG do seu NPC
2. Redimensione para 128x128 pixels (recomendado)
3. Nomeie o arquivo: andre.png

Passo 3: Colocar o arquivo

Copie o arquivo em:

plugins/KGInfoServs-BQBetterHud/avatars/andre.png

Passo 4: Recarregar o plugin

/bqhud reload

O plugin irá:

1. Escanear a pasta avatars/
2. Detectar seu novo arquivo
3. Regenerar o resource pack
4. Atribuir um caractere Unicode ao avatar

Passo 5: Aplicar segundo seu modo

Modo self-host:

• O pack é automaticamente regenerado
• Os jogadores recebem o novo pack ao reconectar

Modo folder:

1. A pasta resourcepack/ é regenerada
2. Integre os arquivos no seu pack de servidor
3. Rebuild e republique seu pack

Passo 6: Testar no jogo

Inicie uma conversa com o NPC "André, o Ferreiro" e verifique se o avatar é exibido.

Aplicar suas alterações

Avatares

1. Substituir/adicionar seus PNG em avatars/
2. Executar /bqhud reload
3. Verificar no jogo com uma conversa

Backgrounds

1. Substituir/adicionar seus PNG em backgrounds/
2. Executar /bqhud reload
3. Verificar no jogo com uma conversa

Segundo seu modo de resource pack

Modo self-host:

• Os jogadores recebem automaticamente o novo pack
• Reconexão recomendada para forçar o recarregamento

Modo folder:

• A pasta resourcepack/ contém os assets atualizados
• Você deve manualmente rebuild e republicar seu pack de servidor

Exemplos de biblioteca de avatares

Organização por tipo de NPC

avatars/
├── villageois/
│   ├── andre.png
│   ├── mercador.png
│   └── maria.png
├── guardas/
│   ├── captain.png
│   ├── guard1.png
│   └── guard2.png
└── boss/
    ├── dragon_rei.png
    └── feiticeiro_negro.png

⚠️ Nota: As subpastas não são suportadas. Coloque todos os PNG diretamente em avatars/.

Nomes de arquivos corretos

✅ Bons nomes:

andre.png
mercador_village.png
guard_captain.png
rei_elfo.png
jose.png
francois-xavier.png

❌ Nomes ruins:

André.png              # Acento
Mercador Village.png   # Espaço (use underscore)
guard captain.png      # Espaço (use underscore)
Rei Elfo.png          # Maiúscula + espaço
José.png              # Acento

Veja também

• Customização Visual
• Configuração
• Solução de problemas