betterMcGuis/docs/06_LIFECYCLE_AND_EVENTS.md

🎯 Cycle de Vie & Système d'Événements - betterMcGuis

La bibliothèque intègre un moteur d'événements à deux niveaux : Hooks Locaux (sur l'instance du menu) et Bus d'Événements Global (avec annotations @GuiEventHandler).

---

📑 Sommaire

• 1. Hooks Locaux sur l'Instance de Menu
• 2. Bus d'Événements Global & Annotations @GuiEventHandler
• 3. Référence Exhaustive des Événements

---

1. Hooks Locaux sur l'Instance de Menu

BetterMcGuis.builder("Banque", 3)
    .onOpen(ctx -> {
        ctx.getPlayer().sendMessage("§aBienvenue dans votre coffre sécurisé.");
    })
    .onClose(ctx -> {
        sauvegarderDonnees(ctx.getPlayer());
    })
    .onOutsideClick(ctx -> {
        // Ferme si le joueur clique en dehors du menu
        ctx.close();
    })
    .onBottomClick(ctx -> {
        // Clic dans son propre inventaire
        ctx.getPlayer().sendMessage("§7Action détectée dans votre inventaire.");
    })
    .build();

---

2. Bus d'Événements Global & Annotations @GuiEventHandler

Vous pouvez créer des classes dédiées pour auditer, logger ou sécuriser l'ensemble des GUIs de votre serveur :

package fr.luc.monplugin.listener;

import fr.luc.bettermcguis.event.*;
import fr.luc.bettermcguis.event.annotation.GuiEventHandler;

public class MonEcouteurGlobalGui {

    // Écoute TOUS les clics de GUIs avec priorité élevée
    @GuiEventHandler(priority = 100)
    public void onGlobalClick(GuiClickEvent event) {
        var ctx = event.getContext();
        System.out.println("[Audit GUI] Joueur : " + ctx.getPlayer().getName() +
                " | Slot : #" + ctx.getSlot() +
                " | Clic : " + ctx.getClickType());
    }

    // Écoute UNIQUEMENT les ouvertures de la boutique
    @GuiEventHandler(guiTitle = "<gradient:#00c6ff:#0072ff><bold>Boutique Paginée</bold></gradient>")
    public void onShopOpen(GuiOpenEvent event) {
        event.getPlayer().sendMessage("§eProfitez des promotions du week-end !");
    }

    // Écoute les fermetures de menus
    @GuiEventHandler
    public void onClose(GuiCloseEvent event) {
        // Traitement global
    }
}

Pour enregistrer l'écouteur :

guiManager.registerListeners(new MonEcouteurGlobalGui());

---

3. Référence Exhaustive des Événements

Classe d'Événement	Description	Annulable ?
GuiOpenEvent	Déclenché avant l'ouverture du menu pour un joueur.	✅ Oui
GuiCloseEvent	Déclenché lorsque le joueur ferme le menu.	❌ Non
GuiClickEvent	Déclenché lors de chaque clic (item, slot vide ou extérieur).	✅ Oui
GuiPageChangeEvent	Déclenché lors d'un changement de page dans un PaginatedGui.	❌ Non
GuiRefreshEvent	Déclenché lors du rafraîchissement d'un inventaire.	❌ Non

---

📖 Étape suivante : Découvrez les zones de stockage dans 07_STORAGE_AND_EDITABLE_SLOTS.md.