betterMcGuis/docs/03_ITEM_BUILDER_AND_ITEMS.md

💎 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
• 2. Prise en Charge de MiniMessage et Kyori Adventure
• 3. Têtes Personnalisées, Couleurs et Flags
• 4. L'Objet Interactif GuiItem
• 5. Le Contexte de Clic (GuiClickContext)

---

1. Création d'ItemStacks avec ItemBuilder

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

// 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 :

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.