API Développeurs

Ce guide explique comment intégrer BQBetterHUD dans vos propres plugins ou mods Minecraft.

📦 Dépendance Maven/Gradle

Gradle (Kotlin DSL)

build.gradle.kts
repositories {
    mavenLocal()  // BQBetterHUD doit être installé localement
}

dependencies {
    compileOnly(files("libs/KGInfoServs-BQBetterHud.jar"))
    // Ou si publié sur un repository
    compileOnly("com.bossbirdyman:betonquestbetterhud:1.0.11")
}

Gradle (Groovy)

build.gradle
repositories {
    mavenLocal()
}

dependencies {
    compileOnly files('libs/KGInfoServs-BQBetterHud.jar')
}

Maven

pom.xml
<dependencies>
    <dependency>
        <groupId>com.bossbirdyman</groupId>
        <artifactId>betonquestbetterhud</artifactId>
        <version>1.0.11</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

🔌 Déclaration de dépendance

Ajoutez BQBetterHUD comme dépendance dans votre plugin.yml :

plugin.yml
name: MonPlugin
version: 1.0.0
main: com.example.MonPlugin
depend: [KGInfoServs-BQBetterHud]  # Dépendance obligatoire

Ou comme dépendance optionnelle :

softdepend: [KGInfoServs-BQBetterHud]  # Optionnel

📚 API Principale

Obtenir l'instance du plugin

import com.bossbirdyman.betonquestbetterhud.BetonQuestBetterHud;

// Méthode 1 : Via l'instance statique
BetonQuestBetterHud plugin = BetonQuestBetterHud.getInstance();

// Méthode 2 : Via le PluginManager
BetonQuestBetterHud plugin = (BetonQuestBetterHud) Bukkit.getPluginManager()
    .getPlugin("KGInfoServs-BQBetterHud");

Vérifier si le plugin est activé

public class MonPlugin extends JavaPlugin {
    private BetonQuestBetterHud bqHud;

    @Override
    public void onEnable() {
        if (Bukkit.getPluginManager().isPluginEnabled("KGInfoServs-BQBetterHud")) {
            bqHud = BetonQuestBetterHud.getInstance();
            getLogger().info("BQBetterHUD détecté !");
        } else {
            getLogger().warning("BQBetterHUD non trouvé.");
        }
    }
}

🔧 Accès aux gestionnaires

ConfigProvider

Accédez à la configuration et aux informations de licence :

import com.bossbirdyman.betonquestbetterhud.internal.ConfigProvider;

ConfigProvider configProvider = plugin.getConfigProvider();

// Obtenir le HWID du serveur
String hwid = configProvider.getHWID();

// Obtenir la clé de licence
String licenseKey = configProvider.getLicenseKey();

// Obtenir les informations de l'instance
ConfigProvider.InstanceInfo instanceInfo = configProvider.getInstanceInfo();
System.out.println("Server name: " + instanceInfo.serverName());
System.out.println("Port: " + instanceInfo.port());
System.out.println("Max players: " + instanceInfo.maxPlayers());

Sécurité

Ne partagez jamais le HWID ou la clé de licence publiquement. Ces informations sont sensibles.

ServiceManager

Gérez la validation de licence :

import com.bossbirdyman.betonquestbetterhud.internal.ServiceManager;

ServiceManager serviceManager = plugin.getServiceManager();

// Vérifier si le service est actif
boolean isActive = serviceManager.isServiceActive();

// Effectuer une vérification rapide de licence
boolean isValid = serviceManager.quickCheck();

if (!isValid) {
    getLogger().warning("Licence BQBetterHUD invalide !");
}

VersionManager

Accédez aux informations de version et de mise à jour :

import com.bossbirdyman.betonquestbetterhud.internal.VersionManager;
import com.bossbirdyman.betonquestbetterhud.internal.ReleaseInfo;

VersionManager versionManager = plugin.getVersionManager();

// Obtenir les informations de release en cache
ReleaseInfo releaseInfo = versionManager.getCachedReleaseInfo();

if (releaseInfo != null) {
    System.out.println("Latest version: " + releaseInfo.version());
    System.out.println("Download URL: " + releaseInfo.downloadUrl());
    System.out.println("Changelog: " + releaseInfo.changelog());
}

🎨 Intégration avec BetonQuest

Utiliser le ConversationIO BetterHud

BQBetterHUD enregistre automatiquement le ConversationIO nommé betterhud dans BetonQuest.

Utilisation dans vos conversations :

conversations/mon_pnj.yml
conversations:
  mon_npc:
    quester: "Mon PNJ"
    conversationIO: betterhud  # Utilise BQBetterHUD
    first: "greeting"
    NPC_options:
      greeting:
        text: "Bonjour, aventurier !"
        pointers: "option1,option2"
    player_options:
      option1:
        text: "Bonjour !"

Créer un ConversationIO personnalisé

Si vous voulez étendre ou personnaliser le comportement :

import org.betonquest.betonquest.conversation.ConversationIO;
import com.bossbirdyman.betonquestbetterhud.BetterHudConvIO;

public class CustomConvIO extends BetterHudConvIO {

    public CustomConvIO(Conversation conv, Player player) {
        super(conv, player);
    }

    @Override
    public void display() {
        // Logique personnalisée avant l'affichage
        super.display();
        // Logique personnalisée après l'affichage
    }
}

🔗 Intégration PlaceholderAPI

Enregistrer votre propre expansion

Si vous voulez ajouter vos propres placeholders liés aux conversations :

import me.clip.placeholderapi.expansion.PlaceholderExpansion;
import org.bukkit.entity.Player;

public class MonExpansion extends PlaceholderExpansion {

    @Override
    public String getIdentifier() {
        return "monplugin";
    }

    @Override
    public String getAuthor() {
        return "VotreNom";
    }

    @Override
    public String getVersion() {
        return "1.0.0";
    }

    @Override
    public String onPlaceholderRequest(Player player, String params) {
        if (player == null) return "";

        // Accéder aux données de BQBetterHUD
        BetonQuestBetterHud bqHud = BetonQuestBetterHud.getInstance();

        // Exemple : %monplugin_custom_data%
        if (params.equals("custom_data")) {
            return "Votre valeur personnalisée";
        }

        return null;
    }
}

📝 Utilisation des variables BetterHud

BQBetterHUD fournit des variables personnalisées à BetterHud pendant les conversations.

Variables disponibles

Variable	Type	Description
`speaker`	String	Nom du PNJ
`text`	String	Texte du dialogue NPC
`typewriter_text`	String	Texte avec effet typewriter
`typewriter_speaker`	String	Nom du PNJ (duplicate)
`show`	Boolean	Afficher le popup
`typewriter_show`	Boolean	Afficher le popup typewriter
`npc_image`	String	ID de l'image NPC
`npc_id`	String	ID du NPC (minuscules, sans accents)
`progress`	Integer	Progression typewriter (0-100)
`typewriter_progress`	Integer	Progression typewriter
`is_complete`	Boolean	Typewriter terminé
`selected_option`	String	Option actuellement sélectionnée (mode scroll)
`previous_option`	String	Option précédente
`next_option`	String	Option suivante
`all_options`	String	Toutes les options formatées
`option_1` à `option_10`	String	Options individuelles
`option_count`	Integer	Nombre d'options
`selected_index`	Integer	Index sélectionné (1-based)
`selected_index_0`	Integer	Index sélectionné (0-based)
`hand_y`	Integer	Position Y de l'indicateur

Accéder aux variables dans votre plugin

import net.luckyzz.betterhud.api.BetterHudAPI;

// Obtenir une variable pour un joueur
String npcId = BetterHudAPI.getVariable(player, "npc_id");
String selectedOption = BetterHudAPI.getVariable(player, "selected_option");

// Définir une variable personnalisée
BetterHudAPI.setVariable(player, "custom_variable", "ma_valeur");

🎭 Événements (Events)

BQBetterHUD ne fournit pas d'événements Bukkit personnalisés, mais vous pouvez écouter les événements BetonQuest :

Écouter le début d'une conversation

import org.betonquest.betonquest.api.event.ConversationStartEvent;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;

public class ConversationListener implements Listener {

    @EventHandler
    public void onConversationStart(ConversationStartEvent event) {
        if (event.getConversation().getIO() instanceof BetterHudConvIO) {
            getLogger().info("Conversation BetterHud démarrée pour " +
                event.getPlayer().getName());
        }
    }
}

🛠️ Exemples d'intégration

Exemple 1 : Bloquer les conversations si le joueur est en combat

import org.betonquest.betonquest.api.event.ConversationStartEvent;
import org.bukkit.event.EventHandler;
import org.bukkit.event.EventPriority;

public class CombatBlocker implements Listener {

    @EventHandler(priority = EventPriority.HIGHEST)
    public void onConversationStart(ConversationStartEvent event) {
        Player player = event.getPlayer();

        // Vérifier si le joueur est en combat
        if (isInCombat(player)) {
            event.setCancelled(true);
            player.sendMessage("§cVous ne pouvez pas parler en combat !");
        }
    }

    private boolean isInCombat(Player player) {
        // Votre logique de détection de combat
        return false;
    }
}

Exemple 2 : Logger les options sélectionnées

import org.betonquest.betonquest.api.event.PlayerChooseOptionEvent;

public class OptionLogger implements Listener {

    @EventHandler
    public void onOptionChosen(PlayerChooseOptionEvent event) {
        Player player = event.getPlayer();
        String option = event.getOption().getText();

        getLogger().info(player.getName() + " a choisi : " + option);

        // Sauvegarder dans une base de données, etc.
    }
}

Exemple 3 : Changer la musique selon le NPC

import me.clip.placeholderapi.PlaceholderAPI;

public class MusicChanger implements Listener {

    @EventHandler
    public void onConversationStart(ConversationStartEvent event) {
        Player player = event.getPlayer();

        // Obtenir l'ID du NPC via PlaceholderAPI
        String npcId = PlaceholderAPI.setPlaceholders(player, "%kgbq_npc_id%");

        // Changer la musique en fonction du NPC
        switch (npcId) {
            case "andre":
                playMusic(player, "blacksmith_theme");
                break;
            case "doran":
                playMusic(player, "merchant_theme");
                break;
            default:
                playMusic(player, "default_dialogue");
                break;
        }
    }

    private void playMusic(Player player, String track) {
        // Votre logique de musique
    }
}

📖 Javadoc

Malheureusement, BQBetterHUD étant un plugin obfusqué (ProGuard), la Javadoc n'est pas disponible publiquement.

Classes principales accessibles :

com.bossbirdyman.betonquestbetterhud.BetonQuestBetterHud
com.bossbirdyman.betonquestbetterhud.BetterHudConvIO
com.bossbirdyman.betonquestbetterhud.internal.ConfigProvider
com.bossbirdyman.betonquestbetterhud.internal.ServiceManager
com.bossbirdyman.betonquestbetterhud.internal.VersionManager

🆘 Support

Pour toute question sur l'API ou l'intégration :

💬 Discord KGInfoServs
📧 Support via votre espace client

🔗 Voir aussi

PlaceholderAPI - Liste des placeholders
Configuration - Options du plugin
Troubleshooting - Résolution de problèmes
BetonQuest API
BetterHud API

📦 Dépendance Maven/Gradle​

Gradle (Kotlin DSL)​

Gradle (Groovy)​

Maven​

🔌 Déclaration de dépendance​

📚 API Principale​

Obtenir l'instance du plugin​

Vérifier si le plugin est activé​

🔧 Accès aux gestionnaires​

ConfigProvider​

ServiceManager​

VersionManager​

🎨 Intégration avec BetonQuest​

Utiliser le ConversationIO BetterHud​

Créer un ConversationIO personnalisé​

🔗 Intégration PlaceholderAPI​

Enregistrer votre propre expansion​

📝 Utilisation des variables BetterHud​

Variables disponibles​

Accéder aux variables dans votre plugin​

🎭 Événements (Events)​

Écouter le début d'une conversation​

🛠️ Exemples d'intégration​

Exemple 1 : Bloquer les conversations si le joueur est en combat​

Exemple 2 : Logger les options sélectionnées​

Exemple 3 : Changer la musique selon le NPC​

📖 Javadoc​

🆘 Support​

🔗 Voir aussi​