From abf6b6c2285097bed21c5db98e5f993c54a64a35 Mon Sep 17 00:00:00 2001
From: Pedro <3602279+Doc94@users.noreply.github.com>
Date: Fri, 8 Aug 2025 12:17:34 -0400
Subject: [PATCH] Allow replace effects in Consumable Component Builder
 (#12938)

---
 .../paper/datacomponent/item/Consumable.java  | 47 +++++++++++++++++++
 .../datacomponent/item/PaperConsumable.java   |  6 +++
 2 files changed, 53 insertions(+)

diff --git a/paper-api/src/main/java/io/papermc/paper/datacomponent/item/Consumable.java b/paper-api/src/main/java/io/papermc/paper/datacomponent/item/Consumable.java
index 8c88bbbee..2188fc4e1 100644
--- a/paper-api/src/main/java/io/papermc/paper/datacomponent/item/Consumable.java
+++ b/paper-api/src/main/java/io/papermc/paper/datacomponent/item/Consumable.java
@@ -48,21 +48,68 @@ public interface Consumable extends BuildableDataComponent<Consumable, Consumabl
     @ApiStatus.NonExtendable
     interface Builder extends DataComponentBuilder<Consumable> {
 
+        /**
+         * Sets the amount of time (in seconds) it takes to consume the item.
+         *
+         * @param consumeSeconds the consumption duration in seconds
+         * @return the builder for chaining
+         */
         @Contract(value = "_ -> this", mutates = "this")
         Builder consumeSeconds(@NonNegative float consumeSeconds);
 
+        /**
+         * Sets the hand animation used when a player consumes the item.
+         *
+         * @param animation the {@link ItemUseAnimation} representing the hand animation to be used
+         * @return the builder for chaining
+         */
         @Contract(value = "_ -> this", mutates = "this")
         Builder animation(ItemUseAnimation animation);
 
+        /**
+         * Sets the sound played when consuming the item.
+         *
+         * @param sound the {@link Key} representing the sound to be used
+         * @return the builder for chaining
+         */
         @Contract(value = "_ -> this", mutates = "this")
         Builder sound(Key sound);
 
+        /**
+         * Sets whether consuming the item results in particle effects.
+         *
+         * @param hasConsumeParticles true to enable particle effects upon consumption, false to disable
+         * @return the builder for chaining
+         */
         @Contract(value = "_ -> this", mutates = "this")
         Builder hasConsumeParticles(boolean hasConsumeParticles);
 
+        /**
+         * Sets the effects that occur when an item is consumed.
+         * <br>
+         * <b>Note:</b> this clears any previous effects set.
+         *
+         * @param effects a list of {@link ConsumeEffect} instances representing the effects to apply upon consumption
+         * @return the builder for chaining
+         */
+        @Contract(value = "_ -> this", mutates = "this")
+        Builder effects(List<ConsumeEffect> effects);
+
+        /**
+         * Adds a single {@link ConsumeEffect} to the consumable item being built.
+         *
+         * @param effect the {@link ConsumeEffect} instance to add
+         * @return the builder for chaining
+         */
         @Contract(value = "_ -> this", mutates = "this")
         Builder addEffect(ConsumeEffect effect);
 
+        /**
+         * Adds multiple {@link ConsumeEffect} instances to the consumable item being built.
+         *
+         * @param effects a list of {@link ConsumeEffect} instances to add
+         * @return the builder for chaining
+         */
         @Contract(value = "_ -> this", mutates = "this")
         Builder addEffects(List<ConsumeEffect> effects);
     }
diff --git a/paper-server/src/main/java/io/papermc/paper/datacomponent/item/PaperConsumable.java b/paper-server/src/main/java/io/papermc/paper/datacomponent/item/PaperConsumable.java
index a73d9117f..8116fe311 100644
--- a/paper-server/src/main/java/io/papermc/paper/datacomponent/item/PaperConsumable.java
+++ b/paper-server/src/main/java/io/papermc/paper/datacomponent/item/PaperConsumable.java
@@ -96,6 +96,12 @@ public record PaperConsumable(
             return this;
         }
 
+        @Override
+        public Builder effects(final List<ConsumeEffect> effects) {
+            this.effects.clear();
+            return this.addEffects(effects);
+        }
+
         @Override
         public Builder addEffect(final ConsumeEffect effect) {
             this.effects.add(PaperConsumableEffect.toNms(effect));