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,59 @@
+# 📦 Zones de Stockage & Slots Éditables - betterMcGuis
+
+Par défaut, tous les menus créés avec `betterMcGuis` interdisent le vol, le déplacement et le shift-clic d'items pour garantir une sécurité totale contre les duplications de bugs d'inventaires.
+
+Cependant, pour les fonctionnalités nécessitant que les joueurs déposent ou retirent des objets (comme une poubelle, un coffre de recyclage, une enclume ou un hôtel des ventes), `betterMcGuis` propose **les slots éditables** et le **`StorageGui`**.
+
+---
+
+## 📑 Sommaire
+- [1. Slots Éditables dans un GUI Standard](#1-slots-éditables-dans-un-gui-standard)
+- [2. Menu de Stockage Dédié (`StorageGui`)](#2-menu-de-stockage-dédié-storagegui)
+- [3. Sécurité contre les Duplications et Glitches](#3-sécurité-contre-les-duplications-et-glitches)
+
+---
+
+## 1. Slots Éditables dans un GUI Standard
+
+Vous pouvez autoriser les interactions de placement et retrait d'items sur des slots ciblés avec `.editable(...)` :
+
+```java
+BetterMcGuis.builder("Boîte de Dépôt", 3)
+    .fillBorder(Material.BLACK_STAINED_GLASS_PANE)
+    // Rend le slot 13 (centre) modifiable librement par le joueur
+    .editable(13)
+    .build()
+    .open(player);
+```
+
+---
+
+## 2. Menu de Stockage Dédié (`StorageGui`)
+
+`StorageGui` simplifie la gestion d'une zone centrale de dépôt avec restitution automatique des items laissés à la fermeture :
+
+```java
+StorageGui trash = new StorageGui("<red>Poubelle</red>", GuiType.CHEST_4_ROWS);
+
+// Remplissage des bordures avec du vitrage
+trash.fillBorder(ItemBuilder.filler(Material.RED_STAINED_GLASS_PANE).asGuiItem());
+
+// Définit les slots intérieurs comme zone de dépôt
+trash.setStorageSlots(SlotRange.interior(4, 9));
+
+// true = restitue les items au joueur à la fermeture
+// false = détruit définitivement les items à la fermeture (idéal poubelle)
+trash.returnItemsOnClose(false);
+
+trash.open(player);
+```
+
+---
+
+## 3. Sécurité contre les Duplications et Glitches
+
+Le gestionnaire `BukkitGuiEventListener` applique des sécurités strictes :
+* **Shift-Clic Protection** : Empêche un joueur de shift-cliquer un item depuis son inventaire vers un slot protégé du menu.
+* **Number Key Protection** : Empêche l'échange d'items via les touches numériques (1 à 9 de la hotbar) vers des slots non éditables.
+* **Drag-and-Drop Protection** : Bloque le glisser-déposer de curseur sur tous les slots non autorisés.
+* **Nettoyage automatique** : En cas de déconnexion ou de fermeture inopinée, les items des zones avec `returnItemsOnClose(true)` sont automatiquement réinsérés dans l'inventaire du joueur ou déposés au sol s'il est plein.