Add color transition and clone functions to ParticleBuilder (#10342)

patches/api/Expand-World.spawnParticle-API-and-add-Builder.patch

@@ -16,7 +16,9 @@ index 0000000000000000000000000000000000000000..00000000000000000000000000000000
 @@ -0,0 +0,0 @@
 +package com.destroystokyo.paper;
 +
++import com.google.common.base.Preconditions;
 +import com.google.common.collect.Lists;
++import it.unimi.dsi.fastutil.objects.ObjectArrayList;
 +import org.bukkit.Color;
 +import org.bukkit.Location;
 +import org.bukkit.Particle;
@@ -26,6 +28,7 @@ index 0000000000000000000000000000000000000000..00000000000000000000000000000000
 +
 +import java.util.Collection;
 +import java.util.List;
++import org.jetbrains.annotations.Contract;
 +import org.jetbrains.annotations.NotNull;
 +import org.jetbrains.annotations.Nullable;
 +
@@ -34,7 +37,7 @@ index 0000000000000000000000000000000000000000..00000000000000000000000000000000
 + *
 + * Usage of the builder is preferred over the super long {@link World#spawnParticle(Particle, Location, int, double, double, double, double, Object)} API
 + */
-+public class ParticleBuilder {
++public class ParticleBuilder implements Cloneable {
 +
 +    private Particle particle;
 +    private List<Player> receivers;
@@ -498,6 +501,97 @@ index 0000000000000000000000000000000000000000..00000000000000000000000000000000
 +    public ParticleBuilder color(int r, int g, int b) {
 +        return color(Color.fromRGB(r, g, b));
 +    }
++
++    /**
++     * Sets the particle Color.
++     * Only valid for REDSTONE.
++     *
++     * @param rgb an integer representing the red, green, and blue color components
++     * @return a reference to this object.
++     * @throws IllegalArgumentException if called on a particle builder that does not have
++     */
++    @NotNull
++    public ParticleBuilder color(final int rgb) {
++        return color(Color.fromRGB(rgb));
++    }
++
++    /**
++     * Sets the particle Color Transition. Only valid for DUST_COLOR_TRANSITION.
++     *
++     * @param fromColor the new particle from color
++     * @param toColor the new particle to color
++     * @return a reference to this object.
++     * @throws IllegalArgumentException if the particle builder's {@link #particle()} isn't {@link Particle#DUST_COLOR_TRANSITION}.
++     */
++    @NotNull
++    public ParticleBuilder colorTransition(@NotNull final Color fromColor, @NotNull final Color toColor) {
++        return colorTransition(fromColor, toColor, 1);
++    }
++
++    /**
++     * Sets the particle Color Transition.
++     * Only valid for DUST_COLOR_TRANSITION.
++     *
++     * @param fromRed red color component for the from color
++     * @param fromGreen green color component for the from color
++     * @param fromBlue blue color component for the from color
++     * @param toRed red color component for the to color
++     * @param toGreen green color component for the to color
++     * @param toBlue blue color component for the to color
++     * @return a reference to this object.
++     * @throws IllegalArgumentException if the particle builder's {@link #particle()} isn't {@link Particle#DUST_COLOR_TRANSITION}.
++     */
++    @NotNull
++    public ParticleBuilder colorTransition(final int fromRed, final int fromGreen, final int fromBlue,
++                                           final int toRed, final int toGreen, final int toBlue) {
++        return colorTransition(Color.fromRGB(fromRed, fromGreen, fromBlue), Color.fromRGB(toRed, toGreen, toBlue));
++    }
++
++    /**
++     * Sets the particle Color Transition.
++     * Only valid for DUST_COLOR_TRANSITION.
++     *
++     * @param fromRgb an integer representing the red, green, and blue color components for the from color
++     * @param toRgb   an integer representing the red, green, and blue color components for the to color
++     * @return a reference to this object.
++     * @throws IllegalArgumentException if the particle builder's {@link #particle()} isn't {@link Particle#DUST_COLOR_TRANSITION}.
++     */
++    @NotNull
++    public ParticleBuilder colorTransition(final int fromRgb, final int toRgb) {
++        return colorTransition(Color.fromRGB(fromRgb), Color.fromRGB(toRgb));
++    }
++
++    /**
++     * Sets the particle Color Transition and size. Only valid for DUST_COLOR_TRANSITION.
++     *
++     * @param fromColor the new particle color for the from color.
++     * @param toColor the new particle color for the to color.
++     * @param size the size of the particle
++     * @return a reference to this object.
++     * @throws IllegalArgumentException if the particle builder's {@link #particle()} isn't {@link Particle#DUST_COLOR_TRANSITION}.
++     */
++    @NotNull
++    public ParticleBuilder colorTransition(@NotNull final Color fromColor,
++                                           @NotNull final Color toColor,
++                                           final float size) {
++        Preconditions.checkArgument(fromColor != null, "Cannot define color transition with null fromColor.");
++        Preconditions.checkArgument(toColor != null, "Cannot define color transition with null toColor.");
++        Preconditions.checkArgument(this.particle() == Particle.DUST_COLOR_TRANSITION, "Can only define a color transition on particle DUST_COLOR_TRANSITION.");
++        return data(new Particle.DustTransition(fromColor, toColor, size));
++    }
++
++    @NotNull
++    @Override
++    public ParticleBuilder clone() {
++        try {
++            final ParticleBuilder builder = (ParticleBuilder) super.clone();
++            if (this.location != null) builder.location = this.location.clone();
++            if (this.receivers != null) builder.receivers = new ObjectArrayList<>(this.receivers);
++            return builder;
++        } catch (final CloneNotSupportedException e) {
++            throw new AssertionError();
++        }
++    }
 +}
 diff --git a/src/main/java/org/bukkit/Particle.java b/src/main/java/org/bukkit/Particle.java
 index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 100644