Improve the dublicate message for menu module

broken1arrow · broken1arrow · commit 811d1c1a9e93 · 2026-05-07T19:06:47.000+02:00
Make it easier to set your own key for the placeholder.
diff --git a/Menu Library/build.gradle.kts b/Menu Library/build.gradle.kts
@@ -19,6 +19,7 @@ dependencies {
     api(project(":title-update"))
     api(project(":log-and-validate"))
     api(project(":version"))
+    api(project(":serialize-utility"))
 
     compileOnly(libs.org.spigotmc.spigotapi)
     compileOnly(libs.com.google.code.gson.gson)
diff --git a/Menu Library/src/main/java/org/broken/arrow/library/menu/CheckItemsInsideMenu.java b/Menu Library/src/main/java/org/broken/arrow/library/menu/CheckItemsInsideMenu.java
@@ -287,12 +287,13 @@ private void addItemsBackToPlayer(final Location location) {
 
 				itemStack.setAmount(amount);
 				final OfflinePlayer offlinePlayer = Bukkit.getOfflinePlayer(mapEntry.getKey());
-				if (offlinePlayer.getPlayer() != null) {
-					final HashMap<Integer, ItemStack> ifInventorFull = offlinePlayer.getPlayer().getInventory().addItem(itemStack);
-					if (!ifInventorFull.isEmpty() && offlinePlayer.getPlayer().getLocation().getWorld() != null)
-						offlinePlayer.getPlayer().getLocation().getWorld().dropItemNaturally(offlinePlayer.getPlayer().getLocation(), ifInventorFull.get(0));
+				final Player player = offlinePlayer.getPlayer();
+				if (player != null) {
+					final HashMap<Integer, ItemStack> ifInventorFull = player.getInventory().addItem(itemStack);
+					if (!ifInventorFull.isEmpty() && player.getLocation().getWorld() != null)
+						player.getLocation().getWorld().dropItemNaturally(player.getLocation(), ifInventorFull.get(0));
 
-					this.registerMenuAPI.getMessages().sendDuplicatedMessage(offlinePlayer.getPlayer(), new SendMsgDuplicatedItems.DuplicatedItemWrapper(itemStack, mapEntry.getValue().size(), amount));
+					this.registerMenuAPI.getMessages().sendDuplicatedMessage(player, new SendMsgDuplicatedItems.DuplicatedItemWrapper(itemStack, mapEntry.getValue().size(), amount));
 				} else if (location != null && location.getWorld() != null)
 					location.getWorld().dropItemNaturally(location, itemStack);
 			}
diff --git a/Menu Library/src/main/java/org/broken/arrow/library/menu/messages/SendMsgDuplicatedItems.java b/Menu Library/src/main/java/org/broken/arrow/library/menu/messages/SendMsgDuplicatedItems.java
@@ -4,6 +4,7 @@
 import net.md_5.bungee.api.ChatColor;
 import org.broken.arrow.library.color.TextTranslator;
 import org.broken.arrow.library.menu.utility.DuplicateMessage;
+import org.broken.arrow.library.serialize.utility.converters.PlaceholderTranslator;
 import org.bukkit.entity.Player;
 import org.bukkit.inventory.ItemStack;
 
@@ -89,64 +90,71 @@ public void setBlacklistMessage(final Function<ItemStack, String> blacklistMessa
     }
 
     /**
-     * Set message for when player have added item some are duplicated.
-     * Support both hex and &amp; color codes.
+     * Sets a static message format for duplicated item handling.
      *
-     * <p><b>Supported color formats:</b></p>
+     * <p>This is a convenience method equivalent to:</p>
+     * <pre>
+     * setDuplicatedMessage(wrapper -> "your message");
+     * </pre>
+     *
+     * <p>The message supports placeholders and color codes and will be processed automatically.</p>
+     *
+     * <p><b>Formatting support:</b></p>
      * <ul>
-     *   <li>Hex colors: {@code <#8000ff>} or gradients like {@code <#8000ff:#ff0080>} (requires color conversion module).</li>
-     *   <li>Fallback to Spigot's legacy format: {@code &x&6&6&6&6&6&6}, or for white: {@code &x&F&F&F&F&F&F}, if color conversion is not enabled.</li>
+     *   <li>Legacy color codes: {@code &a}, {@code &f}, etc.</li>
+     *   <li>Legacy hex format (Spigot-compatible): {@code &x&R&R&G&G&B&B}</li>
+     *   <li>Hex colors: {@code <#RRGGBB>} and gradients like {@code <#RRGGBB:#RRGGBB>}
+     *       (supported when the internal formatter is available)</li>
      * </ul>
      *
-     *  <p><b>Available placeholders:</b></p>
+     * <p>Formatting is handled automatically using the best available implementation
+     * (Spigot-compatible or internal formatter).</p>
+     *
+     * <p><b>Available indexed placeholders:</b></p>
      * <ul>
-     *   <li>{@code {0}} – The item type (e.g., {@code DIAMOND_SWORD})</li>
-     *   <li>{@code {1}} – Total number of duplicated stacks</li>
-     *   <li>{@code {2}} – Total number of duplicated items</li>
+     *   <li>{@code {0}} – Item type (e.g. {@code DIAMOND_SWORD})</li>
+     *   <li>{@code {1}} – Total duplicated stacks</li>
+     *   <li>{@code {2}} – Total duplicated item amount</li>
      * </ul>
      *
-     * @param duplicatedMessage set a message.
+     * <p><b>Note:</b> If {@link DuplicatedItemWrapper#getPlaceholderWrapper()} is used, those take priority over indexed placeholders.</p>
+     *
+     * @param duplicatedMessage message format string
      */
     public void setDuplicatedMessage(String duplicatedMessage) {
-        this.duplicatedMessage = (itemStack, size, itemAmount) -> duplicatedMessage;
+        this.duplicatedMessage = (wrapper) -> duplicatedMessage;
     }
 
     /**
-     * Sets the message format to display when a player attempts to add items and some are duplicates.
+     * Sets a custom message generator for duplicated item handling.
      *
-     * <p>
-     * Supports both hex color codes and legacy {@code &} codes. This function allows you to handle placeholder
-     * replacement yourself instead of using a predefined message format, giving you more dynamic control, particularly useful
-     * if you're using a localization file or want the text to be updated externally with minimal code changes.
-     * </p>
+     * <p>This allows full control over the final message, including placeholders and formatting.
+     * The provided function receives a {@link DuplicatedItemWrapper}, and the returned string
+     * is processed automatically.</p>
      *
-     * <p><b>Supported color formats:</b></p>
+     * <p>If not set, a default message format is used.</p>
+     *
+     * <p><b>Formatting support:</b></p>
      * <ul>
-     *   <li>Hex colors: {@code <#8000ff>} or gradients like {@code <#8000ff:#ff0080>} (requires the color conversion module).</li>
-     *   <li>Fallback to Spigot's legacy format: {@code &x&6&6&6&6&6&6}, or for white: {@code &x&F&F&F&F&F&F}, if color conversion is not enabled.</li>
+     *   <li>Legacy color codes: {@code &a}, {@code &f}, etc.</li>
+     *   <li>Legacy hex format (Spigot-compatible): {@code &x&R&R&G&G&B&B}</li>
+     *   <li>Hex colors: {@code <#RRGGBB>} and gradients like {@code <#RRGGBB:#RRGGBB>}
+     *       (supported when the internal formatter is available)</li>
      * </ul>
      *
-     * <p><b>Available placeholders:</b></p>
+     * <p>Formatting is handled automatically using the best available implementation
+     * (Spigot-compatible or internal formatter).</p>
+     *
+     * <p><b>Available indexed placeholders:</b></p>
      * <ul>
-     *   <li>{@code {0}} – The item type (e.g., {@code DIAMOND_SWORD})</li>
-     *   <li>{@code {1}} – Total number of duplicated stacks</li>
-     *   <li>{@code {2}} – Total number of duplicated items</li>
+     *   <li>{@code {0}} – Item type (e.g. {@code DIAMOND_SWORD})</li>
+     *   <li>{@code {1}} – Total duplicated stacks</li>
+     *   <li>{@code {2}} – Total duplicated item amount</li>
      * </ul>
      *
-     * <p>
-     * The returned string will be further processed after this function is called — including color conversion
-     * and placeholder replacement (e.g., {@code {0}}, {@code {1}}, {@code {2}}). You only need to provide the
-     * base message with the desired format and placeholders.
-     * </p>
-     *
-     * <p>
-     * You may also choose to handle placeholder translation yourself by including resolved values directly
-     * in the lambda. If you want full control over the output, including color formatting, simply return
-     * an empty string or {@code null} to skip the default message generation and formatting.
-     * </p>
+     * <p><b>Note:</b> If {@link DuplicatedItemWrapper#getPlaceholderWrapper()} is used, those take priority over indexed placeholders.</p>
      *
-     * @param duplicatedMessage a function that takes the item type, duplicated {@link ItemStack}, and finally duplicated item count,
-     *                          and returns the base message string to be processed.
+     * @param duplicatedMessage function that generates the base message from duplicated item data.
      */
     public void setDuplicatedMessage(final DuplicateMessage duplicatedMessage) {
         this.duplicatedMessage = duplicatedMessage;
@@ -156,7 +164,7 @@ public void setDuplicatedMessage(final DuplicateMessage duplicatedMessage) {
      * Sends a raw message to the specified player.
      *
      * @param player the player to send the message to
-     * @param msg the message string to send
+     * @param msg    the message string to send
      */
     public void sendMessage(Player player, String msg) {
         player.sendMessage(msg);
@@ -166,13 +174,17 @@ public void sendMessage(Player player, String msg) {
      * Sends the blacklist message to the player regarding the specified blacklisted item.
      * The message supports color codes and placeholder replacement.
      *
-     * @param player the player to send the message to
+     * @param player    the player to send the message to
      * @param itemStack the blacklisted item stack triggering the message
      */
     public void sendBlacklistMessage(Player player, ItemStack itemStack) {
         String message;
-        if (blacklistMessage == null) message = "&fThis item&6 {0}&f are blacklisted and you get the items back.";
-        else message = blacklistMessage.apply(itemStack.clone());
+        if (blacklistMessage == null) {
+            message = "&fThis item&6 {0}&f are blacklisted and you get the items back.";
+        } else {
+            message = blacklistMessage.apply(itemStack.clone());
+        }
+
         if (message == null || message.isEmpty())
             return;
 
@@ -186,31 +198,38 @@ public void sendBlacklistMessage(Player player, ItemStack itemStack) {
      * Sends the duplicated item message to the player, using data from the provided placeholder wrapper.
      * The message supports color codes and placeholder replacement.
      *
-     * @param player the player to send the message to
+     * @param player          the player to send the message to
      * @param placeholderData wrapper containing duplicated item data for placeholders
      */
     public void sendDuplicatedMessage(@Nonnull final Player player, @Nonnull final DuplicatedItemWrapper placeholderData) {
         String message;
         if (duplicatedMessage == null) {
             message = "&fYou can't add more if this &6 {0} &ftype, you get back &6 {2}&f items.You have added totally &4{1}&f extra itemstacks";
         } else {
-            message = duplicatedMessage.apply(placeholderData.getItemStack().clone(), placeholderData.getSize(), placeholderData.getItemAmount());
+            message = duplicatedMessage.apply(placeholderData);
         }
 
         if (message == null || message.isEmpty())
             return;
 
+        final PlaceholderTranslator.PlaceholderWrapper wrapper = placeholderData.getPlaceholderWrapper();
+        if (!wrapper.getPlaceholders().isEmpty())
+            message = PlaceholderTranslator.translateText(message, wrapper);
+        else {
+            message = PlaceholderTranslator.translateText(message, placeholderData.retrieveAsPlaceholderData());
+        }
+
         if (notFoundTextTranslator)
-            player.sendMessage(ChatColor.translateAlternateColorCodes('&', (translatePlaceholders(message, placeholderData.retrieveAsPlaceholderData()))));
+            player.sendMessage(ChatColor.translateAlternateColorCodes('&', message));
         else
-            player.sendMessage(TextTranslator.toSpigotFormat(translatePlaceholders(message, placeholderData.retrieveAsPlaceholderData())));
+            player.sendMessage(TextTranslator.toSpigotFormat(message));
     }
 
     /**
      * Replaces placeholders of the form {@code {0}, {1}, ...} in the given text with
      * the string representation of the provided placeholder objects.
      *
-     * @param rawText the text containing placeholders to replace
+     * @param rawText      the text containing placeholders to replace
      * @param placeholders the objects to insert into the placeholders
      * @return the text with placeholders replaced by their corresponding values
      */
@@ -225,19 +244,20 @@ public String translatePlaceholders(String rawText, Object... placeholders) {
      * Wrapper class holding information about duplicated items for placeholder substitution.
      */
     public static class DuplicatedItemWrapper {
-
+        private final PlaceholderTranslator.PlaceholderWrapper placeholderWrapper;
         private final ItemStack itemStack;
         private final int size;
         private final int itemAmount;
 
         /**
          * Constructs a new wrapper containing duplicated item data.
          *
-         * @param itemStack the duplicated item stack
-         * @param size the total number of duplicated stacks
+         * @param itemStack  the duplicated item stack
+         * @param size       the total number of duplicated stacks
          * @param itemAmount the total number of duplicated items
          */
         public DuplicatedItemWrapper(final ItemStack itemStack, final int size, final int itemAmount) {
+            this.placeholderWrapper = new PlaceholderTranslator.PlaceholderWrapper();
             this.itemStack = itemStack;
             this.size = size;
             this.itemAmount = itemAmount;
@@ -249,7 +269,7 @@ public DuplicatedItemWrapper(final ItemStack itemStack, final int size, final in
          * @return the item stack
          */
         public ItemStack getItemStack() {
-            return itemStack;
+            return itemStack.clone();
         }
 
         /**
@@ -270,6 +290,39 @@ public int getItemAmount() {
             return itemAmount;
         }
 
+        /**
+         * Returns a {@link PlaceholderTranslator.PlaceholderWrapper} for defining custom
+         * key-based placeholders instead of using the default indexed placeholder system.
+         *
+         * <p>If no custom placeholders are provided, the system falls back to
+         * {@link #retrieveAsPlaceholderData()}, which uses ordered placeholders such as
+         * {@code {0}}, {@code {1}}, {@code {2}}.</p>
+         *
+         * <p>When this wrapper contains entries, it is used instead and allows named
+         * placeholders.</p>
+         *
+         * <p><b>Example (default indexed placeholders):</b></p>
+         * <pre>
+         * "&fYou can't add more if this &6 {0} &ftype, you get back &6 {2} &fitems.
+         *  You have added totally &4 {1} &fextra itemstacks"
+         * </pre>
+         *
+         * <p><b>Example (custom named placeholders):</b></p>
+         * <pre>
+         * wrapper.put("{type}", itemStack.getType())
+         *        .put("{addedStacks}", size)
+         *        .put("{returnedItems}", itemAmount);
+         *
+         * "&fYou can't add more if this &6 {type} &ftype, you get back &6 {returnedItems} &fitems.
+         *  You have added totally &4 {addedStacks} &fextra itemstacks"
+         * </pre>
+         *
+         * @return the {@link PlaceholderTranslator.PlaceholderWrapper} for custom placeholders
+         */
+        public PlaceholderTranslator.PlaceholderWrapper getPlaceholderWrapper() {
+            return placeholderWrapper;
+        }
+
         /**
          * Returns an array of objects to be used as placeholders in messages:
          * item type, duplicated stacks count, and duplicated items count.
diff --git a/Menu Library/src/main/java/org/broken/arrow/library/menu/utility/DuplicateMessage.java b/Menu Library/src/main/java/org/broken/arrow/library/menu/utility/DuplicateMessage.java
@@ -1,21 +1,22 @@
 package org.broken.arrow.library.menu.utility;
 
+import org.broken.arrow.library.menu.messages.SendMsgDuplicatedItems;
 import org.bukkit.inventory.ItemStack;
 
+import javax.annotation.Nonnull;
+
 /**
  * Represents a duplicate message that takes three arguments and produces a result.
  *
  */
 public interface DuplicateMessage {
 
     /**
-     * Applies this message to the given arguments.
+     * Applies this message to the given argument.
      *
-     * @param item the itemStack that is duplicate
-     * @param amount the amount of items that is duplicated.
-     * @param itemAmount the amount of items you get back.
-     * @return the function result
+     * @param duplicatedWrapper The instance of the wrapper to retrieve the data on the item that is a duplicate.
+     * @return the text set that placeholders will be translated and color codes.
      */
-    String apply(final ItemStack item, final int amount, final int itemAmount );
+    String apply(@Nonnull final SendMsgDuplicatedItems.DuplicatedItemWrapper duplicatedWrapper);
 
 }
diff --git a/Serialize Utility/src/main/java/org/broken/arrow/library/serialize/utility/converters/PlaceholderTranslator.java b/Serialize Utility/src/main/java/org/broken/arrow/library/serialize/utility/converters/PlaceholderTranslator.java
@@ -3,6 +3,7 @@
 import org.broken.arrow.library.logging.Logging;
 import org.broken.arrow.library.serialize.utility.Pair;
 
+import javax.annotation.Nonnull;
 import java.util.*;
 import java.util.function.Consumer;
 import java.util.logging.Level;
@@ -37,6 +38,19 @@ public static String translateText(final String text, final Consumer<Placeholder
         return applyPlaceholderMap(text, placeholderMap);
     }
 
+    /**
+     * Translates placeholders in a raw text by replacing them with corresponding values.
+     * The placeholders are replaced in the order specified by the placeholders array.
+     *
+     * @param text               The raw text to translate.
+     * @param placeholderWrapper The placeholders where you provide the placeholder data.
+     * @return The translated text.
+     */
+    public static String translateText(final String text, @Nonnull final PlaceholderWrapper placeholderWrapper) {
+        final Map<String, Object> placeholderMap = placeholderWrapper.getPlaceholders();
+        return applyPlaceholderMap(text, placeholderMap);
+    }
+
     /**
      * Translates placeholders in a raw text by replacing them with corresponding values.
      * The placeholders are replaced in the order specified by the placeholders array.
