Aller au contenu principal

Avatars NPC

Ce guide vous explique comment ajouter des images d'avatar personnalisées pour vos PNJ BetonQuest dans BQBetterHUD.

🎨 Comment fonctionnent les avatars​

Le plugin génère automatiquement un nom d'avatar basé sur le nom du PNJ dans BetonQuest. Cependant, vous devez enregistrer manuellement chaque avatar dans la configuration de BetterHud.

Processus automatique​

Nom du PNJ BetonQuest → Premier mot → Suppression accents → Minuscules → Suffixe "-background"

Exemple :
"André, le Forgeron" → "André" → "Andre" → "andre" → "andre-background"

📋 Configuration étape par étape​

Étape 1 : Créer l'image d'avatar​

  1. Créez une image PNG pour votre PNJ

    • Format : PNG (recommandé : transparent)
    • Dimensions : 128x128 px ou 256x256 px
    • Nom : Première lettre en minuscule, sans accents

  2. Placez l'image dans le dossier assets de BetterHud :

    plugins/BetterHud/assets/andre.png
Style d'image
  • Portrait : Visage ou buste du PNJ
  • Transparent : Fond transparent pour meilleure intégration
  • Formats supportés : PNG (recommandé), JPG

Étape 2 : Enregistrer l'avatar dans BetterHud​

Éditez le fichier plugins/BetterHud/images/dialogue-images.yml :

dialogue-images.yml
npc_avatar:
  type: single
  file: nameless.png          # Image par défaut (fallback)
  setting:
    follow: "papi:kgbq_npc_avatar"
    children:
      # Ajoutez vos NPC ici (un par ligne)
      - andre-background
      - doran-background
      - elise-background

Format d'entrée :

- <nom-du-fichier-png>-background
Important
  • Le nom doit correspondre exactement au fichier PNG (sans l'extension .png)
  • Ajoutez le suffixe -background à la fin
  • Un tiret par NPC, pas de virgule

Étape 3 : Convention de nommage​

Le nom de l'avatar est généré à partir du premier mot du nom du PNJ :

Nom du PNJ (BetonQuest)Fichier PNG requisEntrée children
André, le Forgeronandre.png- andre-background
Dorandoran.png- doran-background
Élise la Marchandeelise.png- elise-background
Jean-Pierre le Gardejean.png- jean-background
Maître Aldricmaitre.png- maitre-background
Suppression automatique des accents

Le plugin supprime automatiquement les accents :

  • André → andre
  • Élise → elise
  • Jérôme → jerome
  • Château → chateau

Étape 4 : Recharger BetterHud​

Après avoir ajouté de nouveaux avatars :

/betterhud reload

Étape 5 : Tester​

Lancez une conversation avec votre PNJ :

/bq conversation <joueur> <conversation>

L'avatar correspondant devrait apparaître automatiquement !

🖼️ Image par défaut (fallback)​

Si un PNJ n'a pas d'avatar enregistré, l'image par défaut est affichée :

file: nameless.png  # Image affichée par défaut

Pour personnaliser l'image par défaut :

  1. Remplacez plugins/BetterHud/assets/nameless.png par votre image
  2. Ou modifiez le fichier : 
    file: votre-image-par-defaut.png

📝 Exemples complets​

Exemple 1 : Serveur médiéval​

dialogue-images.yml
npc_avatar:
  type: single
  file: nameless.png
  setting:
    follow: "papi:kgbq_npc_avatar"
    children:
      - roi-background          # Roi Arthur
      - merlin-background       # Merlin l'Enchanteur
      - lancelot-background     # Lancelot le Chevalier
      - viviane-background      # Dame Viviane
      - perceval-background     # Perceval le Gallois

Fichiers PNG correspondants :

plugins/BetterHud/assets/
├── roi.png
├── merlin.png
├── lancelot.png
├── viviane.png
└── perceval.png

Exemple 2 : Serveur moderne​

dialogue-images.yml
npc_avatar:
  type: single
  file: nameless.png
  setting:
    follow: "papi:kgbq_npc_avatar"
    children:
      - alex-background         # Alex le Vendeur
      - sarah-background        # Sarah l'Infirmière
      - mike-background         # Mike le Mécanicien
      - emma-background         # Emma la Professeure

Exemple 3 : Serveur RP avec accents​

Configuration BetonQuest :

conversations/marchands.yml
conversations:
  marchand_general:
    quester: "André, le Forgeron"  # Nom avec accent
    conversationIO: betterhud
    # ...

Configuration BetterHud :

dialogue-images.yml
npc_avatar:
  type: single
  file: nameless.png
  setting:
    follow: "papi:kgbq_npc_avatar"
    children:
      - andre-background   # Sans accent, minuscules

Fichier PNG :

plugins/BetterHud/assets/andre.png

🎯 Accents supportés​

Le plugin gère automatiquement ces conversions :

CaractèreConverti en
À, Á, Â, Ã, Ä, ÅA
à, á, â, ã, ä, åa
È, É, Ê, ËE
è, é, ê, ëe
Ì, Í, Î, ÏI
ì, í, î, ïi
Ò, Ó, Ô, Õ, ÖO
ò, ó, ô, õ, öo
Ù, Ú, Û, ÜU
ù, ú, û, üu
ÇC
çc
ÑN
ñn

🛠️ Cas spéciaux​

Noms composés​

Exemple : Jean-Pierre le Marchand

Le plugin extrait uniquement le premier mot (avant le tiret ou l'espace) :

  • Résultat : jean
  • Fichier : jean.png
  • Entrée : - jean-background

Titres et préfixes​

Exemple : Maître Aldric

Le premier mot est Maître :

  • Résultat : maitre
  • Fichier : maitre.png
  • Entrée : - maitre-background

Solution : Si vous voulez utiliser Aldric au lieu de Maître, nommez votre PNJ :

quester: "Aldric, Maître des arcanes"

Plusieurs PNJ avec le même prénom​

Problème : Vous avez Jean le Forgeron et Jean le Marchand

Solution 1 : Donner des noms différents

quester: "Jean-Forgeron"  # jean-forgeron.png
quester: "Jean-Marchand"  # jean-marchand.png (ne fonctionne pas, extrait "jean")

Solution 2 : Utiliser des surnoms distincts

quester: "Jeannot le Forgeron"   # jeannot.png
quester: "Jean-Paul le Marchand" # jean.png

Solution 3 : Ajouter un qualificatif

quester: "Forgeron Jean"   # forgeron.png
quester: "Marchand Jean"   # marchand.png

📁 Structure des fichiers​

plugins/
└── BetterHud/
    ├── assets/
    │   ├── nameless.png           # Fallback par défaut
    │   ├── andre.png              # Avatar personnalisé
    │   ├── doran.png              # Avatar personnalisé
    │   ├── elise.png              # Avatar personnalisé
    │   └── ...
    └── images/
        └── dialogue-images.yml    # Enregistrement des avatars

🆘 Dépannage​

L'avatar ne s'affiche pas​

Causes possibles :

  1. PlaceholderAPI non installé

    • Solution : Installez PlaceholderAPI 2.11+
    • Vérifiez : /papi version

  2. Avatar non enregistré dans dialogue-images.yml

    • Solution : Ajoutez - nom-background à la liste children
    • Rechargez : /betterhud reload

  3. Nom de fichier incorrect

    • Solution : Vérifiez que le fichier PNG existe et correspond exactement
    • Exemple : andre.png → - andre-background

  4. BetterHud non rechargé

    • Solution : Exécutez /betterhud reload après modification

  5. Format d'image non supporté

    • Solution : Utilisez PNG ou JPG uniquement

L'image par défaut (nameless) s'affiche toujours​

Causes :

  1. Le premier mot du nom du PNJ ne correspond pas au fichier
  2. Le fichier PNG n'existe pas dans assets/
  3. L'avatar n'est pas enregistré dans children

Vérification :

# 1. Vérifier le nom généré
/papi parse me %kgbq_npc_avatar%
# (pendant une conversation)

# 2. Vérifier que le fichier existe
ls plugins/BetterHud/assets/andre.png

# 3. Vérifier l'enregistrement
cat plugins/BetterHud/images/dialogue-images.yml | grep andre

L'avatar est pixelisé​

Cause : Image trop petite

Solution : Utilisez une image d'au moins 128x128 px (recommandé : 256x256 px)

Plusieurs PNJ partagent le même avatar​

Cause : Ils ont le même premier mot dans leur nom

Solution : Renommez les PNJ pour avoir des premiers mots distincts

💡 Conseils et astuces​

1. Organisez vos fichiers​

Créez un sous-dossier pour mieux organiser :

plugins/BetterHud/assets/
├── npc/
│   ├── andre.png
│   ├── doran.png
│   └── elise.png
├── ui/
│   ├── dialogue.png
│   └── hand.png
└── nameless.png
Limitation BetterHud

BetterHud ne supporte pas les sous-dossiers dans assets/. Tous les fichiers doivent être à la racine.

2. Utilisez un style cohérent​

  • Même dimensions : 256x256 px pour tous les avatars
  • Même style artistique : pixel art, réaliste, cartoon...
  • Fond transparent : Meilleure intégration visuelle

3. Testez rapidement​

Créez une conversation de test avec tous vos PNJ :

test_avatars.yml
conversations:
  test_avatars:
    quester: "André"
    conversationIO: betterhud
    first: "test"
    NPC_options:
      test:
        text: "Test avatar André"

Changez quester pour tester chaque avatar.

4. Automatisez avec un script​

Si vous avez beaucoup de PNJ, générez automatiquement la liste :

#!/bin/bash
# Génère la liste children à partir des PNG
cd plugins/BetterHud/assets/
for file in *.png; do
  if [ "$file" != "nameless.png" ]; then
    name="${file%.png}"
    echo "      - ${name}-background"
  fi
done

🔗 Voir aussi​

Dernière mise à jour le par Bossbirdyman