PlaceholderAPI

BQBetterHUD s'intègre avec PlaceholderAPI pour fournir des placeholders dynamiques utilisables dans BetterHud et d'autres plugins.

📦 Prérequis

PlaceholderAPI 2.11+ doit être installé :

# Télécharger depuis SpigotMC
# Placer PlaceholderAPI.jar dans plugins/
# Redémarrer le serveur

Vérifiez l'installation :

/papi version

---

🏷️ Identifiant

Tous les placeholders BQBetterHUD utilisent l'identifiant kgbq :

%kgbq_<placeholder>%

---

📋 Liste des placeholders

%kgbq_selected_index%

Type : Integer (0-based)

Description : Index de l'option actuellement sélectionnée par le joueur (commence à 0)

Valeurs :

• 0 = Première option
• 1 = Deuxième option
• 2 = Troisième option
• etc.

Exemple d'utilisation :

BetterHud layout

images:
  hand_indicator:
    image: hand
    x: 10
    y: "[custom_variable:hand_y]"  # Position calculée avec selected_index

---

%kgbq_option_count%

Type : Integer

Description : Nombre total d'options disponibles dans la conversation

Valeurs :

• 0 = Aucune option (dialogue NPC uniquement)
• 1+ = Nombre d'options

Exemple d'utilisation :

Condition d'affichage

images:
  option_panel:
    condition: "papi:kgbq_option_count > 0"  # Affiche seulement s'il y a des options

---

%kgbq_in_dialogue%

Type : Boolean (true/false)

Description : Indique si le joueur est actuellement dans une conversation BetterHud

Valeurs :

• true = En conversation
• false = Pas en conversation

Exemple d'utilisation :

Affichage conditionnel

popups:
  dialogue_hud:
    condition: "papi:kgbq_in_dialogue == true"

---

%kgbq_npc_id%

Type : String

Description : ID du PNJ actuel (premier mot du nom, minuscules, sans accents)

Exemples :

• André, le Forgeron → andre
• Doran → doran
• Élise la Marchande → elise

Exemple d'utilisation :

Debugging

texts:
  debug:
    value: "NPC ID: [papi:kgbq_npc_id]"

---

%kgbq_npc_avatar%

Type : String

Description : Nom de l'image d'avatar du PNJ actuel (avec suffixe -background)

Format : <npc_id>-background

Exemples :

• André → andre-background
• Doran → doran-background

Exemple d'utilisation :

Avatar dynamique dans BetterHud

images:
  npc_avatar:
    type: single
    file: nameless.png
    setting:
      follow: "papi:kgbq_npc_avatar"  # Sélectionne l'avatar automatiquement

Utilisation principale

Ce placeholder est utilisé par BetterHud pour sélectionner dynamiquement l'image d'avatar du PNJ.

---

🎨 Utilisation dans BetterHud

1. Sélection d'avatar dynamique

images/dialogue-images.yml

npc_avatar:
  type: single
  file: nameless.png          # Fallback
  setting:
    follow: "papi:kgbq_npc_avatar"  # Utilise le placeholder
    children:
      - andre-background
      - doran-background
      - elise-background

Lorsque le joueur parle à "André", le placeholder retourne andre-background, et BetterHud affiche l'image correspondante.

---

2. Positionnement de l'indicateur de main

layouts/betonquest-layout.yml

images:
  hand:
    image: hand
    x: 10
    y: "[papi:kgbq_selected_index]"  # Position basée sur l'option sélectionnée

Le plugin calcule automatiquement la position Y via la variable hand_y, mais vous pouvez aussi utiliser directement kgbq_selected_index.

---

3. Affichage conditionnel d'éléments

layouts/betonquest-layout.yml

images:
  options_background:
    image: answer
    condition: "papi:kgbq_option_count > 0"  # Affiche seulement s'il y a des options

---

4. Compteur d'options

texts/dialogue.yml

texts:
  option_counter:
    text: dialogue
    value: "[papi:kgbq_option_count] options disponibles"

---

🧪 Tester les placeholders

Méthode 1 : Commande PAPI

/papi parse me %kgbq_in_dialogue%

Résultat :

• Hors conversation : false
• En conversation : true

---

Méthode 2 : Debugging dans BetterHud

Ajoutez un texte de debug dans votre layout :

layouts/betonquest-layout.yml

texts:
  debug_info:
    text: dialogue
    x: 10
    y: 200
    value: |
      In dialogue: [papi:kgbq_in_dialogue]
      NPC ID: [papi:kgbq_npc_id]
      Avatar: [papi:kgbq_npc_avatar]
      Selected: [papi:kgbq_selected_index]
      Options: [papi:kgbq_option_count]

---

🔧 Utilisation dans d'autres plugins

Les placeholders BQBetterHUD peuvent être utilisés dans n'importe quel plugin supportant PlaceholderAPI.

DeluxeMenus

menus/dialogue_status.yml

items:
  dialogue_indicator:
    material: "LIME_STAINED_GLASS_PANE"
    data: 0
    slot: 0
    display_name: "&aEn conversation"
    lore:
      - "NPC: %kgbq_npc_id%"
      - "Options: %kgbq_option_count%"
    view_requirement: "%kgbq_in_dialogue% == true"

---

ScoreboardObjective

scoreboard.yml

lines:
  - "&6&lDialogue"
  - "&7NPC: &f%kgbq_npc_id%"
  - "&7Option: &f%kgbq_selected_index%/%kgbq_option_count%"
  - ""
  - "Condition: %kgbq_in_dialogue% == true"

---

ConditionalEvents

events.yml

dialogue_start:
  type: player_command
  conditions:
    placeholder:
      - "%kgbq_in_dialogue% == true"
  actions:
    - "message: &aVous êtes en conversation avec %kgbq_npc_id%"

---

💡 Cas d'usage avancés

1. Changer la musique selon le PNJ

Music plugin

tracks:
  blacksmith_theme:
    condition: "%kgbq_npc_id% == andre"
    file: "blacksmith.ogg"

  merchant_theme:
    condition: "%kgbq_npc_id% == doran"
    file: "merchant.ogg"

---

2. Afficher un titre pendant les conversations

ConditionalEvents

dialogue_title:
  type: repetitive
  repetitions: 1
  delay: 20
  conditions:
    placeholder:
      - "%kgbq_in_dialogue% == true"
  actions:
    - "title: &6Dialogue avec %kgbq_npc_id%;subtitle: &7%kgbq_option_count% options"

---

3. Statistiques de conversations

Utilisez les placeholders pour tracker les conversations :

MySQL tracking

query: "INSERT INTO conversations (player, npc, option_count) VALUES ('%player%', '%kgbq_npc_id%', %kgbq_option_count%)"
condition: "%kgbq_in_dialogue% == true"

---

🆘 Dépannage

Placeholder retourne la chaîne brute

Symptôme : Affiche %kgbq_in_dialogue% au lieu de true

Causes :

1. PlaceholderAPI non installé

   • Solution : Installez PlaceholderAPI 2.11+

2. Expansion non chargée

   • Solution : Redémarrez le serveur ou /papi reload

3. Mauvais format

   • Solution : Utilisez %kgbq_<nom>% (pas {kgbq_<nom>})

---

Placeholder retourne une valeur vide

Symptôme : Le placeholder ne retourne rien

Causes :

1. Joueur pas en conversation

   • Solution : Les placeholders retournent des valeurs par défaut hors conversation :
     • kgbq_in_dialogue → false
     • kgbq_npc_id → (vide)
     • kgbq_selected_index → -1
     • kgbq_option_count → 0

2. Typo dans le nom

   • Solution : Vérifiez l'orthographe (kgbq_npc_avatar, pas kgbq_npc_image)

---

Avatar ne change pas dynamiquement

Symptôme : L'avatar reste sur nameless.png

Causes :

1. Avatar non enregistré dans BetterHud

   • Solution : Ajoutez - <npc>-background dans dialogue-images.yml

2. PlaceholderAPI non installé

   • Solution : Installez PlaceholderAPI

3. BetterHud non rechargé

   • Solution : /betterhud reload

---

📊 Tableau récapitulatif

Placeholder	Type	Exemple	Utilisation
%kgbq_selected_index%	Integer	0, 1, 2	Positionnement indicateur
%kgbq_option_count%	Integer	0, 3, 5	Affichage conditionnel
%kgbq_in_dialogue%	Boolean	true, false	Conditions d'affichage
%kgbq_npc_id%	String	andre, doran	Identification NPC
%kgbq_npc_avatar%	String	andre-background	Sélection d'image

---

🔗 Voir aussi

• Avatars NPC - Guide de configuration des avatars
• Configuration - Options de personnalisation
• API Développeurs - Intégration dans vos plugins
• Documentation PlaceholderAPI