Allow replace effects in Consumable Component Builder (#12938)

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);
     }

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));