# 💎 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).