feat: initialisation complète de la bibliothèque betterMcGuis (Fluent DSL, ItemBuilder, PaginatedGui, TabbedGui, AnimatedGui, Patterns ASCII, Moteur d'événements, Sécurité anti-glitch et documentation)

2026-08-23 18:10:49 +02:00
parent b88eaad155
commit 806d1789a1
63 changed files with 6233 additions and 2 deletions
@@ -0,0 +1,91 @@
+# 🎯 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](#1-hooks-locaux-sur-linstance-de-menu)
+- [2. Bus d'Événements Global & Annotations `@GuiEventHandler`](#2-bus-dévénements-global--annotations-guieventhandler)
+- [3. Référence Exhaustive des Événements](#3-référence-exhaustive-des-événements)
+
+---
+
+## 1. Hooks Locaux sur l'Instance de Menu
+
+```java
+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 :
+
+```java
+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 :
+```java
+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](07_STORAGE_AND_EDITABLE_SLOTS.md).