Avatars et backgrounds

Liaison avatar NPC automatique

La liaison est 100% automatique si le nom du fichier avatar correspond au npc_id du NPC.

Algorithme de mapping

Le plugin transforme le nom BetonQuest du NPC en npc_id selon ces règles :

1. Prend le nom complet du NPC défini dans BetonQuest
2. Garde uniquement le premier bloc avant espace, virgule ou point-virgule
3. Retire tous les accents et caractères non-ASCII (normalisation)
4. Convertit en minuscules
5. Cherche le fichier PNG correspondant dans avatars/

Exemples de mapping simples

Nom NPC BetonQuest	npc_id généré	Fichier attendu
Andre	andre	andre.png
Marchand	marchand	marchand.png
Guard_Captain	guard_captain	guard_captain.png

Exemples de mapping complexes

Nom NPC BetonQuest	npc_id généré	Fichier attendu	Explication
André, le Forgeron	andre	andre.png	Retire accent, prend avant virgule
José María	jose	jose.png	Retire accents, prend avant espace
François-Xavier	francois-xavier	francois-xavier.png	Garde le tiret, retire l'accent
Müller	muller	muller.png	Normalise le ü en u
Señor Lopez	senor	senor.png	Normalise ñ en n, prend avant espace
Étienne; Capitaine	etienne	etienne.png	Retire accent, prend avant point-virgule
王小明	(vide)	nameless.png	Caractères non-ASCII → fallback
123_Guard	123_guard	123_guard.png	Chiffres et underscore autorisés

Avatar par défaut (fallback)

Si aucun avatar ne correspond au npc_id, le plugin utilise automatiquement :

• Fichier : nameless.png
• Emplacement : plugins/KGInfoServs-BQBetterHud/avatars/nameless.png
• Ce fichier est automatiquement copié au premier démarrage

Où placer les avatars

Dossier

plugins/KGInfoServs-BQBetterHud/avatars/

Règles pour les fichiers

Règle	Détail
Format	PNG uniquement (avec transparence alpha supportée)
Nom	Doit correspondre exactement au npc_id (minuscules, sans accents)
Extension	.png (obligatoire)
Taille recommandée	64x64, 128x128 ou 256x256 pixels
Transparence	Supportée (canal alpha)

Exemples de noms valides

avatars/
├── andre.png
├── marchand.png
├── guard_captain.png
├── francois-xavier.png
├── jose.png
├── nameless.png          # Fallback par défaut
└── senor.png

Dimensions recommandées

Taille	Usage	Qualité
64x64	Style pixel art	Bonne
128x128	Style semi-réaliste	Très bonne
256x256	Style haute définition	Excellente
512x512	Ultra HD (déconseillé)	Surcharge inutile

Recommandation : Utilisez 128x128 pour un bon compromis qualité/performance.

Backgrounds (fonds UI)

Les backgrounds ne sont pas lies automatiquement a chaque NPC.

Ils sont globaux et remplacent le style visuel de l interface.

Dossier:

• plugins/KGInfoServs-BQBetterHud/backgrounds/

Fichiers supportes:

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

Deplacer et scale l avatar / les fonds

Vous pouvez ajuster les positions et tailles dans 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: deplacement
• scale: taille (seulement sur les blocs qui exposent cette cle)

Workflow complet : Ajouter un avatar

Étape 1 : Identifier le npc_id

Regardez le nom de votre NPC dans BetonQuest et déterminez le npc_id :

Exemple avec BetonQuest :

# Dans votre fichier conversations/village.yml
quests:
  marchand_village:
    NPC_name: "André, le Forgeron"
    # npc_id sera : andre

Étape 2 : Créer l'avatar

1. Créez ou trouvez une image PNG de votre NPC
2. Redimensionnez-la à 128x128 pixels (recommandé)
3. Nommez le fichier : andre.png

Étape 3 : Placer le fichier

Copiez le fichier dans :

plugins/KGInfoServs-BQBetterHud/avatars/andre.png

Étape 4 : Recharger le plugin

/bqhud reload

Le plugin va :

1. Scanner le dossier avatars/
2. Détecter votre nouveau fichier
3. Régénérer le resource pack
4. Assigner un caractère Unicode à l'avatar

Étape 5 : Appliquer selon votre mode

Mode self-host :

• Le pack est automatiquement régénéré
• Les joueurs reçoivent le nouveau pack à la reconnexion

Mode folder :

1. Le dossier resourcepack/ est régénéré
2. Intégrez les fichiers dans votre pack serveur
3. Rebuild et republier votre pack

Étape 6 : Tester en jeu

Lancez une conversation avec le NPC "André, le Forgeron" et vérifiez que l'avatar s'affiche.

Appliquer vos changements

Avatars

1. Remplacer/ajouter vos PNG dans avatars/
2. Exécuter /bqhud reload
3. Vérifier en jeu avec une conversation

Backgrounds

1. Remplacer/ajouter vos PNG dans backgrounds/
2. Exécuter /bqhud reload
3. Vérifier en jeu avec une conversation

Selon votre mode de resource pack

Mode self-host :

• Les joueurs reçoivent automatiquement le nouveau pack
• Reconnexion recommandée pour forcer le rechargement

Mode folder :

• Le dossier resourcepack/ contient les assets mis à jour
• Vous devez manuellement rebuild et republier votre pack serveur

Troubleshooting avatars

L'avatar ne s'affiche pas

1. Vérifier le nom du fichier

Le nom doit être en minuscules et sans accents :

❌ Incorrect :

• André.png (majuscule + accent)
• andre.PNG (extension en majuscules)
• andré.png (accent)

✅ Correct :

• andre.png

2. Vérifier le format

Le fichier doit être un PNG valide. Testez :

# Windows (via PowerShell)
Get-ItemProperty plugins/KGInfoServs-BQBetterHud/avatars/andre.png

# Vérifiez que le type de fichier est bien PNG

Le fallback nameless.png s'affiche toujours

Causes possibles :

1. Le fichier avatar n'existe pas pour ce npc_id
2. Le nom du fichier ne correspond pas exactement au npc_id
3. Le fichier PNG est corrompu

Solution :

Regardez les logs pour voir le npc_id recherché, puis créez/renommez votre fichier en conséquence.

Exemples de bibliothèque d'avatars

Organisation par type de NPC

avatars/
├── villageois/
│   ├── andre.png
│   ├── marchand.png
│   └── marie.png
├── gardes/
│   ├── captain.png
│   ├── guard1.png
│   └── guard2.png
└── boss/
    ├── dragon_roi.png
    └── sorcier_noir.png

⚠️ Note : Les sous-dossiers ne sont pas supportés. Placez tous les PNG directement dans avatars/.

Noms de fichiers corrects

✅ Bons noms :

andre.png
marchand_village.png
guard_captain.png
roi_elfe.png
jose.png
francois-xavier.png

❌ Mauvais noms :

André.png              # Accent
Marchand Village.png   # Espace (utilisez underscore)
guard captain.png      # Espace (utilisez underscore)
Roi Elfe.png          # Majuscule + espace
José.png              # Accent

Voir aussi

• Customisation Visuelle
• Configuration
• Troubleshooting