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,94 @@
+# 🏗️ Fluent GUI Builder DSL - betterMcGuis
+
+La création de menus repose sur un pattern **Builder chainable, fluide et modulaire**.
+
+---
+
+## 📑 Sommaire
+- [1. Configuration des Dimensions et Types d'Inventaires](#1-configuration-des-dimensions-et-types-dinventaires)
+- [2. Placement des Items](#2-placement-des-items)
+- [3. Remplissage et Bordures](#3-remplissage-et-bordures)
+- [4. Propriétés Dynamiques](#4-propriétés-dynamiques)
+- [5. Contrôle du Cycle de Vie et Ouvertures](#5-contrôle-du-cycle-de-vie-et-ouvertures)
+
+---
+
+## 1. Configuration des Dimensions et Types d'Inventaires
+
+Vous pouvez configurer des coffres standards de 1 à 6 lignes, ou des types d'inventaires Bukkit spécifiques :
+
+```java
+// Coffre 3 lignes (27 slots)
+BetterMcGuis.builder("Titre", 3);
+
+// Types spécifiques via GuiType
+BetterMcGuis.builder()
+    .title("<yellow>Distributeur</yellow>")
+    .type(GuiType.DISPENSER); // DISPENSER, DROPPER, HOPPER, ANVIL, WORKBENCH, BREWING
+```
+
+---
+
+## 2. Placement des Items
+
+Vous pouvez positionner des items selon trois méthodes d'adressage :
+
+```java
+var builder = BetterMcGuis.builder("Exemple", 4);
+
+// Par slot absolu (0-indexé, 0 à 35)
+builder.item(13, monItem);
+
+// Par coordonnées ligne/colonne (0-indexé, ligne 1, col 4)
+builder.item(1, 4, monItem);
+
+// Par SlotPos
+builder.item(SlotPos.of(1, 4), monItem);
+```
+
+---
+
+## 3. Remplissage et Bordures
+
+Des méthodes utilitaires permettent de remplir instantanément l'inventaire ou ses contours :
+
+```java
+// Remplit toutes les bordures extérieures avec du vitrage teinté
+builder.fillBorder(Material.GRAY_STAINED_GLASS_PANE);
+
+// Remplit une plage continue de slots
+builder.fillRange(SlotRange.of(10, 16), monItem);
+
+// Remplit tout l'inventaire
+builder.fill(monItem);
+```
+
+---
+
+## 4. Propriétés Dynamiques
+
+Vous pouvez attacher des données arbitraires à l'instance de GUI pour les partager entre callbacks :
+
+```java
+Gui gui = BetterMcGuis.builder("Profil", 3)
+    .property("targetPlayerUuid", target.getUniqueId())
+    .property("openedAt", System.currentTimeMillis())
+    .build();
+
+// Récupération typée dans un callback
+UUID uuid = gui.getProperty("targetPlayerUuid", UUID.class);
+```
+
+---
+
+## 5. Contrôle du Cycle de Vie et Ouvertures
+
+* `gui.open(Player)` : Ouvre l'inventaire pour le joueur.
+* `gui.close(Player)` : Ferme l'inventaire.
+* `gui.refresh(Player)` : Met à jour visuellement les items sans réouverture.
+* `gui.refreshAll()` : Rafraîchit l'affichage pour tous les spectateurs actifs.
+* `gui.setTitle("<green>Nouveau Titre</green>")` : Modifie le titre du menu.
+
+---
+
+> 📖 **Étape suivante** : Découvrez la création d'items avec [03_ITEM_BUILDER_AND_ITEMS.md](03_ITEM_BUILDER_AND_ITEMS.md).