Dépannage

Guide complet pour résoudre les problèmes courants du plugin.

🚨 Problèmes courants

1. Aucun HUD n'apparaît en dialogue

Symptôme : Le dialogue BetonQuest s'affiche en chat classique au lieu du HUD.

Causes possibles :

Cause	Vérification	Solution
ConversationIO non configuré	Regardez plugins/BetonQuest/config.yml	Ajoutez kg_bqhud dans conversation.default_io
Plugin non chargé	Console au démarrage	Vérifiez les erreurs de chargement
BetonQuest manquant	/plugins en jeu	Installez BetonQuest
Conflit avec ancien KG_Hud	/plugins en jeu	Supprimez l'ancien plugin kg_hud

Solution détaillée :

1. Ouvrez plugins/BetonQuest/config.yml
2. Trouvez la section conversation:
3. Modifiez :

conversation:
  default_io: kg_bqhud,menu,chest

4. Redémarrez le serveur ou faites /betonquest reload
5. Testez avec une conversation

Alternative pour une conversation spécifique :

# Dans votre fichier de conversation BetonQuest
conversationIO: kg_bqhud

2. Le resource pack ne se charge pas

Symptôme : Le HUD n'affiche pas les fonds/avatars, ou erreur "Failed to load resource pack".

Mode folder

Problème : Le pack généré n'est pas appliqué aux joueurs.

Solution :

1. Vérifiez que le dossier existe :

   plugins/KGInfoServs-BQBetterHud/resourcepack/

2. Intégrez le contenu dans votre pack serveur :

   votre-pack-serveur/
   ├── assets/
   │   └── kgbq/          # Copiez depuis resourcepack/assets/kgbq/
   └── pack.mcmeta

3. Rebuild et republiez votre pack serveur

4. Les joueurs doivent télécharger le nouveau pack

Mode self-host

Problème : Le plugin héberge le pack mais les joueurs ne le reçoivent pas.

Vérifications :

1. Port accessible :

   standalone:
     resource-pack:
       self-host-port: 8164  # Doit être ouvert sur votre firewall

2. URL publique configurée (recommandé) :

   standalone:
     resource-pack:
       public-url: "https://votre-domaine.com"
       # ou
       public-url: "mon-serveur.exemple.com:8164"

3. Testez l'accès au pack :

   • URL : http://votre-ip:8164/pack.zip
   • Le pack doit se télécharger

4. Vérifiez les logs :

   [PackServer] HTTP server started on port 8164
   [PackSender] Sending pack to player: PlayerName

Problème de firewall :

Si le port est bloqué :

1. Ouvrez le port 8164 (TCP) sur votre firewall
2. Vérifiez les règles iptables (Linux)
3. Configurez le port forwarding (hébergeur)

3. Les avatars ne s'affichent pas

Symptôme : nameless.png s'affiche pour tous les NPC, ou pas d'avatar du tout.

Causes et solutions :

Cause 1 : Nom de fichier incorrect

❌ Incorrect :

plugins/KGInfoServs-BQBetterHud/avatars/
├── André.png          # Majuscule + accent
├── marchand village.png  # Espace
└── Jose.PNG           # Extension en majuscules

✅ Correct :

plugins/KGInfoServs-BQBetterHud/avatars/
├── andre.png
├── marchand_village.png
└── jose.png

Cause 2 : npc_id mal identifié

Vérifiez que le nom de votre fichier correspond au mapping automatique :

Rappel du mapping :

Nom BetonQuest	npc_id	Fichier
André, le Forgeron	andre	andre.png
José María	jose	jose.png
Müller Schmidt	muller	muller.png

Le plugin convertit automatiquement :

• En minuscules
• Supprime les accents
• Garde uniquement le premier mot

Cause 3 : Fichier PNG corrompu

Test :

Ouvrez le fichier PNG avec un éditeur d'image. S'il ne s'ouvre pas, le fichier est corrompu.

Solution :

Réexportez l'image en PNG avec un logiciel fiable (GIMP, Photoshop, Paint.NET).

Cause 4 : Pack non rechargé

Solution :

/bqhud reload

En mode folder, rebuild et republiez votre pack serveur.

4. Les backgrounds ne changent pas

Symptôme : Les fonds personnalisés ne s'appliquent pas.

Checklist :

• Fichiers placés dans plugins/KGInfoServs-BQBetterHud/backgrounds/
• Noms exacts (respecter la casse) :
  • dialogue.png
  • answer.png
  • hand.png
  • name_start.png
  • name_mid.png
  • name_end.png
• Format PNG valide
• /bqhud reload exécuté
• Pack serveur rebuild (mode folder)

Vérification rapide :

# Listez les fichiers backgrounds
ls plugins/KGInfoServs-BQBetterHud/backgrounds/

Vérifiez que les noms correspondent exactement.

5. Les positions/scale ne s'appliquent pas

Symptôme : Les modifications de config.yml ne changent rien visuellement.

Causes possibles :

Cause 1 : Erreur de syntaxe YAML

Exemple d'erreur :

# ❌ Incorrect (tabulations utilisées)
standalone:
	layout:
		avatar:
			x: -20

# ✅ Correct (espaces utilisés)
standalone:
  layout:
    avatar:
      x: -20

Solution :

1. Vérifiez la syntaxe YAML avec un validateur en ligne
2. Utilisez espaces (pas de tabulations)
3. Regardez les logs après /bqhud reload pour les erreurs

Cause 2 : Valeurs hors limites

Certaines valeurs peuvent être ignorées si hors limites raisonnables.

Valeurs recommandées :

Paramètre	Min	Max	Défaut
x-offset	-500	500	0
y-offset	-400	0	-200
scale	0.1	3.0	1.0

Cause 3 : Cache du client

Solution :

1. Faites /bqhud reload sur le serveur
2. Le joueur se reconnecte
3. Ou force le reload du resource pack (F3 + T en jeu)

6. Police personnalisée ne s'affiche pas

Symptôme : Le texte utilise la police par défaut malgré la configuration de fonts.yml.

Vérifications :

1. Fichier TTF placé correctement :

   plugins/KGInfoServs-BQBetterHud/fonts/mafonte.ttf

2. Configuration correcte dans fonts.yml :

   default:
     scale: 16
     file: "mafonte.ttf"  # Nom exact du fichier
     use-unifont: false

3. Logs après /bqhud reload :

   [FontManager] Loading font: mafonte.ttf
   [FontManager] Font loaded successfully

Erreurs courantes :

Erreur dans logs	Cause	Solution
Font file not found: mafonte.ttf	Fichier manquant	Vérifiez le chemin et le nom
Failed to load font: invalid format	TTF corrompu	Téléchargez un nouveau fichier
Font rendering error	Incompatibilité Java	Utilisez une police TTF standard

7. Effet typewriter ne fonctionne pas

Symptôme : Le texte s'affiche instantanément au lieu de l'effet machine à écrire.

Vérification :

typewriter:
  enabled: true   # Doit être true
  speed: 30       # Caractères par seconde (ajustez si nécessaire)

Vitesses recommandées :

• 10 : Très lent (effet dramatique)
• 30 : Normal (défaut)
• 60 : Rapide
• 100 : Très rapide

Note : Si enabled: false, le texte s'affiche instantanément.

8. Mode de sélection fixed ne fonctionne pas

Symptôme : Le mode fixed ne change rien, toujours en mode scroll.

Configuration requise :

selection-mode: "fixed"  # Pas "Fixed" ni "FIXED"

Différences visuelles :

Mode	Comportement
scroll	Liste déroulante, option sélectionnée en couleur
fixed	Liste fixe, indicateur de main (hand.png)

Si vous ne voyez pas la main en mode fixed, vérifiez que backgrounds/hand.png existe.

9. Commande /bqhud refusée

Symptôme : "You don't have permission to use this command"

Solution :

Ajoutez la permission à votre groupe ou joueur :

# Dans votre plugin de permissions (LuckPerms, etc.)
permissions:
  - bqhud.admin

Test rapide (OP uniquement) :

/op VotreNom
/bqhud reload

10. Erreur de licence au démarrage

Symptôme : Le plugin ne se charge pas et affiche une erreur de licence.

Messages d'erreur possibles :

[BQBetterHud] License validation failed
[BQBetterHud] License key not found
[BQBetterHud] Unable to contact license server

Solutions :

1. Vérifier le fichier de licence :

   plugins/KGInfoServs-BQBetterHud/license.key

2. Contenu du fichier :

   • Une seule ligne
   • Pas d'espaces avant/après
   • Format UUID valide

3. Accès Internet : Le serveur doit pouvoir contacter le serveur de licences. Vérifiez :

   • Firewall sortant
   • Connexion Internet du serveur
   • Proxy si applicable

4. Contact support : Si le problème persiste, contactez KGInfoServs sur Discord.

🔧 Outils de diagnostic

Vérifier l'état du plugin

/plugins
# Cherchez "KGInfoServs-BQBetterHud" en vert

Voir les logs en temps réel

Linux :

tail -f logs/latest.log | grep -i bqhud

Windows (PowerShell) :

Get-Content logs/latest.log -Wait | Select-String -Pattern "bqhud" -CaseSensitive:$false

Tester une conversation BetonQuest

/q conversation <nom_conversation> <joueur>

Forcer le reload du resource pack (client)

En jeu, appuyez sur F3 + T pour recharger les ressources.

📋 Checklist de dépannage rapide

Avant de demander de l'aide, vérifiez :

• plugins/BetonQuest/config.yml contient kg_bqhud dans conversation.default_io
• /bqhud reload exécuté après chaque modification
• Resource pack mode configuré correctement (folder ou self-host)
• Avatars/backgrounds aux bons emplacements avec bons noms
• Logs serveur consultés pour erreurs
• Permission bqhud.admin accordée
• BetonQuest installé et fonctionnel
• Version Minecraft supportée (1.21+)

🆘 Demander de l'aide

Si le problème persiste après avoir suivi ce guide :

1. Rassemblez les informations :

   • Version de Minecraft
   • Version de Paper/Spigot
   • Version de BetonQuest
   • Version de KG_BQBetterHud
   • Logs serveur (derniers 50 lignes avec erreurs)
   • Votre config.yml

2. Contactez le support :

   • Discord KGInfoServs : https://discord.gg/SZhD9AGUXW
   • Créez un ticket avec toutes les infos ci-dessus

📚 Voir aussi

• Configuration
• Avatars et Backgrounds
• Customisation Visuelle
• Installation