Dépannage

Ce guide vous aide à résoudre les problèmes courants rencontrés avec BQBetterHUD.

🚨 Problèmes de démarrage

Le plugin ne démarre pas

Symptômes :

[BQBetterHud] License validation failed!
[BQBetterHud] Plugin will be disabled.

Causes et solutions :

Cause	Solution
Licence invalide ou manquante	Vérifiez `plugins/KGInfoServs-BQBetterHud/license.key`
HWID non enregistré	Copiez le HWID depuis `license.key` et enregistrez-le sur votre espace client
Pas de connexion Internet	Vérifiez la connectivité du serveur
Firewall bloque les requêtes HTTPS	Autorisez les connexions HTTPS sortantes (port 443)

Étapes de vérification :

# 1. Vérifier que le fichier de licence existe
ls plugins/KGInfoServs-BQBetterHud/license.key

# 2. Afficher le contenu
cat plugins/KGInfoServs-BQBetterHud/license.key

# 3. Vérifier la connexion Internet
ping -c 4 1.1.1.1

Dépendances manquantes

Symptômes :

[BQBetterHud] BetonQuest not found!
[BQBetterHud] BetterHud not found!

Solution :

Vérifiez que les plugins requis sont installés :
```
/plugins
```
Téléchargez et installez :
- BetonQuest 3.0+ : Site officiel
- BetterHud : SpigotMC
Redémarrez le serveur

💬 Problèmes de conversation

Les conversations n'utilisent pas BetterHud

Symptômes :

Le texte s'affiche dans le chat au lieu du popup
Pas d'effet visuel

Causes et solutions :

Cause	Solution
`conversationIO` non défini	Ajoutez `conversationIO: betterhud` dans votre fichier de conversation
Faute de frappe	Vérifiez l'orthographe : `betterhud` (tout en minuscules)
Conversation non rechargée	Exécutez `/bq reload`

Configuration correcte :

conversations/mon_pnj.yml
conversations:
  mon_npc:
    conversationIO: betterhud  # ← Important !
    quester: "Mon PNJ"
    first: "greeting"
    # ... reste de la config

Symptômes :

Aucun popup visible
Message d'erreur : Popup 'bq_spoken' introuvable

Causes et solutions :

Cause	Solution
Fichiers BetterHud manquants	Copiez le dossier `delivery/BetterHud/` vers `plugins/BetterHud/`
BetterHud non rechargé	Exécutez `/betterhud reload`
ID de popup incorrect	Vérifiez `config.yml` : `spoken-popup: "bq_spoken"`
BetterHud mal configuré	Vérifiez `/betterhud list popups`

Vérification des popups :

/betterhud list popups

Résultat attendu :

Popups:
- bq_spoken
- bq_option
- bq_option_fixed

Effet typewriter ne fonctionne pas

Symptômes :

Le texte s'affiche instantanément
Pas d'animation lettre par lettre

Causes et solutions :

Cause	Solution
Typewriter désactivé	Vérifiez `config.yml` : `typewriter.enabled: true`
Vitesse trop élevée	Réduisez `typewriter.speed` (essayez 30)
Variable incorrecte dans BetterHud	Utilisez `[custom_variable:typewriter_text]` au lieu de `[custom_variable:text]`

Configuration recommandée :

config.yml
typewriter:
  enabled: true
  speed: 30  # Caractères par seconde

🎨 Problèmes d'affichage

Avatars ne s'affichent pas

Symptômes :

L'image par défaut (nameless.png) s'affiche toujours
Pas d'avatar personnalisé

Causes et solutions :

Cause	Solution
PlaceholderAPI non installé	Installez PlaceholderAPI 2.11+
Avatar non enregistré	Ajoutez `- <npc>-background` dans `dialogue-images.yml`
Nom de fichier incorrect	Vérifiez que le fichier PNG existe : `plugins/BetterHud/assets/andre.png`
BetterHud non rechargé	Exécutez `/betterhud reload`

Étapes de vérification :

# 1. Vérifier PlaceholderAPI
/papi version

# 2. Tester le placeholder (pendant une conversation)
/papi parse me %kgbq_npc_avatar%
# Résultat attendu : andre-background

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

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

Indicateur de main (hand) invisible

Symptômes :

En mode fixed, l'indicateur de sélection ne s'affiche pas

Causes et solutions :

Cause	Solution
PlaceholderAPI manquant	Installez PlaceholderAPI
Image `hand.png` manquante	Vérifiez `plugins/BetterHud/assets/hand.png`
Position hors écran	Ajustez `hand-base-y` dans `config.yml`
Layout incorrect	Vérifiez que le layout utilise `bq_dialogue_option_fixed`

Options tronquées

Symptômes :

Le texte des options est coupé avec ...

Solution :

config.yml
selection-indicator:
  max-option-length: 30  # Augmentez cette valeur (ou 0 = illimité)

Couleurs ne fonctionnent pas

Symptômes :

Les options ont toutes la même couleur
Les codes couleur s'affichent littéralement

Causes et solutions :

Cause	Solution
Format MiniMessage incorrect	Utilisez `<#RRGGBB>` ou `<color>` (pas `&c`)
Version de BetterHud incompatible	Mettez à jour BetterHud

Formats valides :

selected-color: "<#97deaa>"           # Hex (recommandé)
selected-color: "<green>"             # Nom de couleur
selected-color: "<gradient:#FF0000:#00FF00>"  # Dégradé

🎮 Problèmes de contrôle

Les contrôles ne répondent pas

Symptômes :

La molette ne change pas les options
Clic droit ne confirme pas
Shift ne quitte pas

Causes et solutions :

Cause	Solution
Plugin de protection bloque les événements	Désactivez temporairement les plugins de protection
Conflit avec un autre plugin	Testez en mode vanille (sans autres plugins)
Cooldown actif	Attendez 500ms après avoir skip le typewriter

Le joueur peut bouger pendant la conversation

Symptômes :

Le blocage de mouvement ne fonctionne pas

Cause :

Conflit avec un plugin de mouvement (Citizens, MythicMobs, etc.)

Solution :

Ajoutez une exception dans votre plugin de mouvement
Ou désactivez temporairement le plugin conflictuel

🔊 Problèmes de son

Pas de son lors du changement d'option

Causes et solutions :

Cause	Solution
Volume à 0	Vérifiez `config.yml` : `option-sound.volume: 1.0`
Son incorrect	Utilisez un son valide : `minecraft:ui.button.click`
Version Minecraft incompatible	Vérifiez que le son existe dans votre version

Sons testés et fonctionnels :

option-sound:
  key: "minecraft:ui.button.click"      # Recommandé
  # key: "minecraft:block.note_block.hat"
  # key: "minecraft:entity.experience_orb.pickup"

🔄 Problèmes de mise à jour

Commande `/bqhud update` ne fonctionne pas

Symptômes :

[BQBetterHud] Accès refusé. Votre licence ne permet pas les mises à jour.

Causes et solutions :

Cause	Solution
Licence sans accès updates	Mettez à niveau votre licence sur l'espace client
Licence expirée	Renouvelez votre licence
Pas de mise à jour disponible	Vous avez déjà la dernière version

Mise à jour téléchargée mais pas installée

Symptômes :

Fichier dans plugins/update/ mais le plugin n'est pas mis à jour

Solution :

L'installation est manuelle pour des raisons de sécurité :

Arrêter le serveur
```
stop
```

Remplacer le JAR

mv plugins/update/KGInfoServs-BQBetterHud.jar plugins/

Redémarrer

# Le serveur démarre avec la nouvelle version

🛠️ Outils de diagnostic

Mode Debug

Activez le mode debug pour obtenir des logs détaillés :

config.yml
debug: true

Rechargez le plugin :

/bqhud reload

Logs debug inclus :

États de conversation (begin, display, end)
Variables BetterHud
Événements d'interaction (scroll, clic)
Validation de licence
Affichage des popups

Vérifier l'état du plugin

# Version du plugin
/version KGInfoServs-BQBetterHud

# Statut des dépendances
/plugins

# Popups BetterHud chargés
/betterhud list popups

# Conversations BetonQuest
/bq conversations list

# PlaceholderAPI
/papi version
/papi parse me %kgbq_in_dialogue%

Tester une conversation

Créez une conversation de test minimale :

test.yml
conversations:
  test:
    conversationIO: betterhud
    quester: "Test"
    first: "hello"
    NPC_options:
      hello:
        text: "Test 1, 2, 3"
        pointers: "opt1,opt2"
    player_options:
      opt1:
        text: "Option 1"
      opt2:
        text: "Option 2"

Lancez le test :

/bq reload
/bq conversation <joueur> test

📊 Erreurs fréquentes et codes

License validation failed

Code : Erreur de licence

Solutions :

Vérifiez license.key
Enregistrez le HWID sur l'espace client
Vérifiez la connexion Internet

Code : Popup manquant

Solutions :

Copiez les fichiers delivery/BetterHud/
Exécutez /betterhud reload
Vérifiez les IDs dans config.yml

ConversationIO 'betterhud' not registered

Code : ConversationIO non enregistré

Solutions :

Vérifiez que BQBetterHUD est bien chargé
Vérifiez l'ordre de chargement (doit charger après BetonQuest)
Redémarrez le serveur

🔍 Checklist complète

Avant de demander du support, vérifiez :

💬 Obtenir du support

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

1. Préparez les informations

# Collectez ces informations
- Version du serveur : /version
- Version BQBetterHUD : /version KGInfoServs-BQBetterHud
- Version BetonQuest : /version BetonQuest
- Version BetterHud : /version BetterHud
- Liste des plugins : /plugins
- Logs : latest.log (avec debug: true)

2. Contactez le support

💬 Discord : discord.gg/kginfos
📧 Email : Via votre espace client KGInfoServs
📝 Ticket : Ouvrez un ticket sur l'espace client

3. Informations à fournir

**Problème :**
[Description détaillée]

**Étapes pour reproduire :**
1. ...
2. ...
3. ...

**Résultat attendu :**
[Ce qui devrait se passer]

**Résultat actuel :**
[Ce qui se passe réellement]

**Environnement :**
- Serveur : Paper 1.21.3
- BQBetterHUD : 1.0.11
- BetonQuest : 2.1.0
- BetterHud : 1.5.0

**Logs :**
[Collez les logs pertinents]

🔗 Ressources utiles

Installation - Guide d'installation
Configuration - Options de configuration
Commandes - Liste des commandes
Avatars NPC - Guide des avatars
PlaceholderAPI - Placeholders disponibles
Documentation BetonQuest
Documentation BetterHud

🚨 Problèmes de démarrage​

Le plugin ne démarre pas​

Dépendances manquantes​

💬 Problèmes de conversation​

Les conversations n'utilisent pas BetterHud​

Popup ne s'affiche pas​

Effet typewriter ne fonctionne pas​

🎨 Problèmes d'affichage​

Avatars ne s'affichent pas​

Indicateur de main (hand) invisible​

Options tronquées​

Couleurs ne fonctionnent pas​

🎮 Problèmes de contrôle​

Les contrôles ne répondent pas​

Le joueur peut bouger pendant la conversation​

🔊 Problèmes de son​

Pas de son lors du changement d'option​

🔄 Problèmes de mise à jour​

Commande /bqhud update ne fonctionne pas​

Mise à jour téléchargée mais pas installée​

🛠️ Outils de diagnostic​

Mode Debug​

Vérifier l'état du plugin​

Tester une conversation​

📊 Erreurs fréquentes et codes​

License validation failed​

Popup '<id>' not found​

ConversationIO 'betterhud' not registered​

🔍 Checklist complète​

💬 Obtenir du support​

1. Préparez les informations​

2. Contactez le support​

3. Informations à fournir​

🔗 Ressources utiles​

🚨 Problèmes de démarrage

Le plugin ne démarre pas

Dépendances manquantes

💬 Problèmes de conversation

Les conversations n'utilisent pas BetterHud

Popup ne s'affiche pas

Effet typewriter ne fonctionne pas

🎨 Problèmes d'affichage

Avatars ne s'affichent pas

Indicateur de main (hand) invisible

Options tronquées

Couleurs ne fonctionnent pas

🎮 Problèmes de contrôle

Les contrôles ne répondent pas

Le joueur peut bouger pendant la conversation

🔊 Problèmes de son

Pas de son lors du changement d'option

🔄 Problèmes de mise à jour

Commande `/bqhud update` ne fonctionne pas

Mise à jour téléchargée mais pas installée

🛠️ Outils de diagnostic

Mode Debug

Vérifier l'état du plugin

Tester une conversation

📊 Erreurs fréquentes et codes

License validation failed

Popup '<id>' not found

ConversationIO 'betterhud' not registered

🔍 Checklist complète

💬 Obtenir du support

1. Préparez les informations

2. Contactez le support

3. Informations à fournir

🔗 Ressources utiles