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,82 @@
+# 🎨 Motifs & Masques ASCII - betterMcGuis
+
+La création de mises en page complexes est grandement facilitée par le système de **Motifs (Patterns)** et **Masques (Masks)** textuels.
+
+---
+
+## 📑 Sommaire
+- [1. Qu'est-ce qu'un Motif ASCII (`GuiPattern`) ?](#1-quest-ce-quun-motif-ascii-guipattern-)
+- [2. Déclaration et Utilisation](#2-déclaration-et-utilisation)
+- [3. Masques de Sélection de Slots (`GuiMask`)](#3-masques-de-sélection-de-slots-guimask)
+
+---
+
+## 1. Qu'est-ce qu'un Motif ASCII (`GuiPattern`) ?
+
+Un `GuiPattern` vous permet de dessiner littéralement la disposition visuelle de votre inventaire sous forme de lignes de texte, où chaque caractère représente un type d'item.
+
+---
+
+## 2. Déclaration et Utilisation
+
+```java
+GuiPattern pattern = BetterMcGuis.pattern(
+        "#########",
+        "# S K Q #",
+        "#       #",
+        "#   C   #",
+        "#########"
+    )
+    .bindFiller('#', Material.BLACK_STAINED_GLASS_PANE)
+    .bind('S', ItemBuilder.of(Material.EMERALD).name("<green>Boutique</green>").asGuiItem(this::ouvrirShop))
+    .bind('K', ItemBuilder.of(Material.CHEST).name("<gold>Kits</gold>").asGuiItem(this::ouvrirKits))
+    .bind('Q', ItemBuilder.of(Material.BOOK).name("<aqua>Quêtes</aqua>").asGuiItem(this::ouvrirQuetes))
+    .bind('C', ItemBuilder.of(Material.BARRIER).name("<red>Fermer</red>").asGuiItem(GuiClickContext::close))
+    .build();
+
+// Application directe sur le GUI
+BetterMcGuis.builder("Menu Principal", 5)
+    .pattern(pattern)
+    .build()
+    .open(player);
+```
+
+Vous pouvez aussi définir le motif directement dans le builder de manière fluide :
+
+```java
+BetterMcGuis.builder("Menu Compact", 3)
+    .pattern(p -> p
+        .lines(
+            "111111111",
+            "1  D  1",
+            "111111111"
+        )
+        .bindFiller('1', Material.GRAY_STAINED_GLASS_PANE)
+        .bind('D', ItemBuilder.of(Material.DIAMOND).name("<aqua>Trésor</aqua>").asGuiItem())
+    )
+    .build();
+```
+
+---
+
+## 3. Masques de Sélection de Slots (`GuiMask`)
+
+Un `GuiMask` permet de sélectionner des ensembles de slots spécifiques via une matrice binaire (`0` et `1`) pour définir par exemple des zones d'items paginés ou des slots éditables :
+
+```java
+GuiMask masqueZone = new GuiMask(
+    "000000000",
+    "011111110",
+    "011111110",
+    "000000000"
+);
+
+// Utilisation pour définir les slots d'un menu paginé
+BetterMcGuis.paginated("Boutique", 4)
+    .itemSlots(masqueZone)
+    .build();
+```
+
+---
+
+> 📖 **Étape suivante** : Découvrez les menus avancés dans [05_PAGINATED_AND_ADVANCED_GUIS.md](05_PAGINATED_AND_ADVANCED_GUIS.md).