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,111 @@
+# 💎 ItemBuilder & GuiItem - betterMcGuis
+
+La création et l'interaction avec les items Minecraft sont grandement simplifiées grâce à `ItemBuilder` et `GuiItem`.
+
+---
+
+## 📑 Sommaire
+- [1. Création d'ItemStacks avec `ItemBuilder`](#1-création-ditemstacks-avec-itembuilder)
+- [2. Prise en Charge de MiniMessage et Kyori Adventure](#2-prise-en-charge-de-minimessage-et-kyori-adventure)
+- [3. Têtes Personnalisées, Couleurs et Flags](#3-têtes-personnalisées-couleurs-et-flags)
+- [4. L'Objet Interactif `GuiItem`](#4-lobjet-interactif-guiitem)
+- [5. Le Contexte de Clic (`GuiClickContext`)](#5-le-contexte-de-clic-guiclickcontext)
+
+---
+
+## 1. Création d'ItemStacks avec `ItemBuilder`
+
+```java
+ItemStack epee = ItemBuilder.of(Material.DIAMOND_SWORD)
+    .name("<gradient:#ff0844:#ffb199><bold>Lame des Enfers</bold></gradient>")
+    .lore(
+        "<gray>Une épée forgée dans les profondeurs du Nether.</gray>",
+        "",
+        "<yellow>Dégâts : <red>+15</red></yellow>",
+        "<green>Effet : <gold>Enflamme les cibles</gold></green>"
+    )
+    .amount(1)
+    .enchant(Enchantment.DAMAGE_ALL, 5)
+    .enchant(Enchantment.FIRE_ASPECT, 2)
+    .unbreakable(true)
+    .flags(ItemFlag.HIDE_UNBREAKABLE)
+    .customModelData(1001)
+    .build();
+```
+
+---
+
+## 2. Prise en Charge de MiniMessage et Kyori Adventure
+
+Tous les noms et lores utilisent nativement les balises MiniMessage :
+* `<gradient:#color1:#color2>Texte</gradient>` : Dégradés de couleurs HEX.
+* `<bold>`, `<italic>`, `<underlined>`, `<strikethrough>` : Mises en forme.
+* `<rainbow>Texte Arc-en-ciel</rainbow>` : Animation multicolore.
+* `<green>`, `<red>`, `<gold>`, `<aqua>`, `<gray>`, etc.
+
+---
+
+## 3. Têtes Personnalisées, Couleurs et Flags
+
+```java
+// Tête de joueur par pseudo ou UUID
+GuiItem tete = ItemBuilder.skull()
+    .skullOwner("Luc")
+    .name("<yellow>Profil de Luc</yellow>")
+    .asGuiItem();
+
+// Armure en cuir teintée
+ItemStack armure = ItemBuilder.of(Material.LEATHER_CHESTPLATE)
+    .color(Color.fromRGB(41, 128, 185))
+    .build();
+
+// Item brillant sans texte d'enchantement
+GuiItem etoile = ItemBuilder.of(Material.NETHER_STAR)
+    .glowing(true)
+    .asGuiItem();
+```
+
+---
+
+## 4. L'Objet Interactif `GuiItem`
+
+Un `GuiItem` encapsule un `ItemStack` avec des comportements avancés :
+
+```java
+GuiItem bouton = ItemBuilder.of(Material.EMERALD)
+    .name("<green>Confirmer l'achat</green>")
+    .asGuiItem(ctx -> {
+        ctx.replySuccess("Achat confirmé !");
+    })
+    // Condition de visibilité : seuls les joueurs avec la permission voient cet item
+    .visibleIf(player -> player.hasPermission("monplugin.vip"))
+    // Cooldown de 2 secondes entre les clics
+    .cooldown(Duration.ofSeconds(2))
+    // Joue un son au joueur
+    .sound(Sound.ENTITY_PLAYER_LEVELUP, 1.0f, 1.2f)
+    // Ferme l'inventaire après le clic
+    .closeOnClick();
+```
+
+---
+
+## 5. Le Contexte de Clic (`GuiClickContext`)
+
+| Méthode | Description |
+|---|---|
+| `ctx.getPlayer()` | Récupère le joueur ayant cliqué. |
+| `ctx.getSlot()` | Récupère l'index du slot absolu cliqué. |
+| `ctx.getSlotPos()` | Récupère la position (ligne, colonne). |
+| `ctx.getClickType()` | Récupère le type de clic (`LEFT`, `RIGHT`, `SHIFT_LEFT`, etc.). |
+| `ctx.isLeftClick()` / `isRightClick()` | Raccourcis booléens pour tester le type de clic. |
+| `ctx.isShiftClick()` | Teste si la touche Shift était enfoncée. |
+| `ctx.close()` | Ferme l'inventaire actuel. |
+| `ctx.refresh()` | Rafraîchit les items du menu. |
+| `ctx.playSound(sound, vol, pitch)` | Joue un son de confirmation ou d'erreur. |
+| `ctx.reply("<yellow>Message</yellow>")`| Envoie un message formaté en MiniMessage. |
+| `ctx.replySuccess(msg)` | Envoie un message de succès préfixé en vert. |
+| `ctx.replyError(msg)` | Envoie un message d'erreur préfixé en rouge. |
+
+---
+
+> 📖 **Étape suivante** : Apprenez à concevoir des grilles avec [04_PATTERNS_AND_MASKS.md](04_PATTERNS_AND_MASKS.md).