Installation

Guide étape par étape pour installer et configurer KG_BQBetterHud sur votre serveur Minecraft.

Prérequis

Avant d'installer le plugin, assurez-vous d'avoir :

Prérequis	Version minimale	Recommandé
Serveur	Paper 1.21+	Paper dernière version
BetonQuest	3.0+	BetonQuest 3.0+
Java	Java 17+	Java 21
Licence	Clé de licence valide KGInfoServs	-

Compatibilité

Le plugin ne fonctionne que sur Paper ou ses forks (Purpur, Pufferfish). Spigot n'est pas supporté en raison des limitations de l'API.

Étape 1 : Télécharger le plugin

1. Téléchargez le fichier JAR depuis votre espace client KGInfoServs
2. Vérifiez que le fichier s'appelle : KGInfoServs-BQBetterHud-X.X.X.jar

Étape 2 : Installation sur le serveur

1. Arrêtez votre serveur (si démarré)

2. Copiez le JAR dans le dossier plugins/ :

   votre-serveur/
   └── plugins/
       ├── BetonQuest.jar
       └── KGInfoServs-BQBetterHud-X.X.X.jar  # ← Nouveau fichier

3. Démarrez le serveur

Le plugin va générer automatiquement son dossier de configuration :

plugins/KGInfoServs-BQBetterHud/
├── config.yml           # Configuration principale
├── fonts.yml            # Configuration des polices
├── messages_en.yml      # Messages en anglais
├── messages_fr.yml      # Messages en français
├── license.key          # Fichier de licence (à remplir)
├── avatars/            # Dossier pour les avatars NPC
│   └── nameless.png    # Avatar par défaut
├── backgrounds/        # Dossier pour les fonds UI
└── resourcepack/       # Pack généré (mode folder)

Étape 3 : Configuration de la licence

1. Ouvrez le fichier plugins/KGInfoServs-BQBetterHud/license.key

2. Remplacez PASTE_YOUR_LICENSE_KEY_HERE par votre clé de licence

   Exemple :

   a1b2c3d4-e5f6-7890-abcd-ef1234567890

3. Enregistrez le fichier

4. Redémarrez le serveur

5. Vérifiez dans les logs :

   [BQBetterHud] License validated successfully
   [BQBetterHud] Standalone mode initialized

Problème de licence ?

Si vous voyez une erreur de licence, consultez la section Troubleshooting - Erreur de licence.

Étape 4 : Configuration BetonQuest (OBLIGATOIRE)

Le plugin nécessite une configuration dans BetonQuest pour fonctionner.

Option 1 : Configuration globale (recommandée)

Ouvrez plugins/BetonQuest/config.yml et modifiez :

conversation:
  default_io: kg_bqhud,menu,chest

Cette configuration s'applique à toutes les conversations par défaut.

Migration depuis kg_hud

Si vous utilisiez l'ancien plugin kg_hud, remplacez-le par kg_bqhud :

# ❌ Ancien (à remplacer)
conversation:
  default_io: kg_hud,menu,chest

# ✅ Nouveau
conversation:
  default_io: kg_bqhud,menu,chest

Option 2 : Configuration par conversation

Si vous préférez activer le HUD uniquement pour certaines conversations :

# Dans votre fichier de conversation BetonQuest
conversations:
  guide_intro:
    quester: "Guide"
    conversationIO: kg_bqhud  # ← Active le HUD pour cette conversation
    first: "start"
    NPC_options:
      start:
        text: "Bonjour aventurier !"
        pointer: choix
    player_options:
      choix:
        text:
          - "Bonjour !"
          - "Qui es-tu ?"

Recharger BetonQuest

Après modification :

/betonquest reload
# ou redémarrez le serveur

Étape 5 : Configuration du resource pack

Le plugin génère automatiquement un resource pack contenant les assets visuels (avatars, fonds, fonts).

Choisissez votre mode de distribution :

Mode folder (recommandé pour production)

Le plugin génère les fichiers dans un dossier, vous les intégrez dans votre pack serveur.

Configuration :

standalone:
  resource-pack:
    output-mode: "folder"
    output-folder: "plugins/KGInfoServs-BQBetterHud/resourcepack"
    regenerate-on-startup: false

Workflow :

1. Le plugin génère les assets dans resourcepack/
2. Vous copiez le contenu dans votre pack serveur :

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

3. Rebuild et redistribuez votre pack via votre hébergeur

Avantages :

• Contrôle total sur le pack
• Intégration avec vos autres assets
• Pas de port à ouvrir

Intégration avec ItemsAdder

Si vous utilisez ItemsAdder pour gérer votre resource pack serveur, vous pouvez fusionner automatiquement les assets de KG_BQBetterHud.

Configuration ItemsAdder :

Ouvrez plugins/ItemsAdder/config.yml et ajoutez dans la section merge_other_plugins_resourcepacks_folders :

resource-pack:
  merge_other_plugins_resourcepacks_folders:
    - KGInfoServs-BQBetterHud/resourcepack

Workflow :

1. KG_BQBetterHud génère ses assets dans resourcepack/
2. ItemsAdder fusionne automatiquement ces assets dans son pack
3. ItemsAdder distribue le pack final aux joueurs

Avantages :

• Fusion automatique avec vos items custom
• Distribution simplifiée via ItemsAdder
• Pas de manipulation manuelle des fichiers

Rechargement

Après modification, exécutez /iazip pour régénérer le pack ItemsAdder avec les assets KG_BQBetterHud.

Mode self-host (développement/test)

Le plugin héberge et envoie automatiquement le pack aux joueurs.

Configuration :

standalone:
  resource-pack:
    output-mode: "self-host"
    self-host-port: 8164
    public-url: "https://votre-domaine.com"  # Recommandé
    force-pack: false
    pack-prompt: "Resource pack requis pour l'affichage des dialogues."

Prérequis :

• Port 8164 (TCP) ouvert sur votre firewall
• URL publique accessible (domaine ou IP publique)

Avantages :

• Mise à jour automatique après /bqhud reload
• Pas de manipulation manuelle
• Idéal pour les tests

Production

Le mode self-host n'est pas recommandé pour la production. Utilisez folder et un hébergeur de resource pack dédié (CDN, site web, etc.).

Étape 6 : Première configuration

Avant de tester en jeu, configurez les paramètres de base.

1. Langue des messages

language: "fr"  # ou "en"

2. Position globale du HUD

standalone:
  x-offset: 0      # Déplacement horizontal (0 = centré)
  y-offset: -200   # Déplacement vertical (-200 = position par défaut)

3. Mode de sélection

selection-mode: "scroll"  # ou "fixed"

• scroll : Liste déroulante classique
• fixed : Liste fixe avec indicateur de main

4. Effet typewriter

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

5. Recharger la configuration

/bqhud reload

Étape 7 : Test en jeu

1. Connectez-vous au serveur

2. Acceptez le resource pack (si demandé)

3. Lancez une conversation BetonQuest avec un NPC :

   /q conversation <nom_conversation> <votre_nom>

4. Vérifiez que le HUD s'affiche correctement

Checklist de vérification

• Le HUD s'affiche (BossBar avec fond de dialogue)
• Le nom du NPC est visible
• Le texte du dialogue s'affiche
• Les options de réponse s'affichent
• La sélection change avec les touches (par défaut : nombres)
• L'effet typewriter fonctionne (si activé)

Problème d'affichage ?

Si le HUD ne s'affiche pas, consultez Troubleshooting - Aucun HUD en dialogue.

Étape 8 : Personnalisation (optionnel)

Une fois le plugin fonctionnel, vous pouvez personnaliser :

Avatars NPC

Placez vos PNG dans plugins/KGInfoServs-BQBetterHud/avatars/

Exemple :

avatars/
├── andre.png       # Pour un NPC nommé "André"
├── marchand.png
└── garde.png

Voir Avatars et Backgrounds pour le mapping détaillé.

Backgrounds personnalisés

Placez vos PNG dans plugins/KGInfoServs-BQBetterHud/backgrounds/

Fichiers disponibles :

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

Positions et tailles

Ajustez dans config.yml :

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

Voir Customisation Visuelle pour le guide complet.

Polices personnalisées

Placez vos fichiers TTF dans plugins/KGInfoServs-BQBetterHud/fonts/

Configurez fonts.yml :

default:
  scale: 16
  file: "mafonte.ttf"
  use-unifont: false

Voir Configuration - Fonts avancés pour plus de détails.

Commandes administrateur

Commande	Description	Permission
/bqhud reload	Recharge la configuration et régénère le resource pack	bqhud.admin
/bqhud update	Télécharge une mise à jour disponible	bqhud.admin
/bqhud	Affiche l'aide	bqhud.admin

Mise à jour du plugin

Pour mettre à jour vers une nouvelle version :

1. Arrêtez le serveur
2. Remplacez le JAR dans plugins/
3. Démarrez le serveur
4. Vérifiez les logs pour la nouvelle version
5. Exécutez /bqhud reload

Sauvegarde

Avant toute mise à jour, sauvegardez votre dossier plugins/KGInfoServs-BQBetterHud/ pour conserver vos configurations et assets.

Résolution des problèmes

Si vous rencontrez des problèmes lors de l'installation, consultez :

• Troubleshooting - Guide complet de dépannage
• Discord KGInfoServs - Support communautaire

Prochaines étapes

Maintenant que le plugin est installé :

1. Personnalisez les avatars de vos NPC
2. Ajustez les positions et couleurs
3. Testez avec vos joueurs
4. Consultez la Configuration complète

Bienvenue dans l'écosystème KG_BQBetterHud ! 🎉