Update particle API to match changes in 26.3

paper-api/src/main/java/com/destroystokyo/paper/ParticleBuilder.java

@@ -17,7 +17,7 @@
 /**
  * Helps prepare a particle to be sent to players.
  * <p>
- * Usage of the builder is preferred over the super long {@link World#spawnParticle(Particle, Location, int, double, double, double, double, Object)} API
+ * Usage of the builder is preferred over the super long {@link World#spawnParticle(Particle, List, Player, double, double, double, int, double, double, double, double, double, double, Object, boolean, Particle.RandomizationType)} API.
  */
 @NullMarked
 public class ParticleBuilder implements Cloneable {
@@ -28,9 +28,10 @@ public class ParticleBuilder implements Cloneable {
     private @Nullable Location location;
     private int count = 1;
     private double offsetX = 0, offsetY = 0, offsetZ = 0;
-    private double extra = 1;
+    private double speedX = 1, speedY = 1, speedZ = 1;
     private @Nullable Object data;
     private boolean force = true;
+    private Particle.RandomizationType randomizationType = Particle.RandomizationType.DEFAULT;
 
     public ParticleBuilder(final Particle particle) {
         this.particle = particle;
@@ -49,7 +50,8 @@ public ParticleBuilder spawn() {
         this.location.getWorld().spawnParticle(
             this.particle, this.receivers, this.source,
             this.location.getX(), this.location.getY(), this.location.getZ(),
-            this.count, this.offsetX, this.offsetY, this.offsetZ, this.extra, this.data, this.force
+            this.count, this.offsetX, this.offsetY, this.offsetZ, this.speedX, this.speedY, this.speedZ,
+            this.data, this.force, this.randomizationType
         );
         return this;
     }
@@ -131,7 +133,7 @@ public ParticleBuilder receivers(final @Nullable Collection<Player> receivers) {
      *                  world
      * @return a reference to this object.
      */
-    public ParticleBuilder receivers(final Player @Nullable... receivers) {
+    public ParticleBuilder receivers(final Player @Nullable ... receivers) {
         this.receivers = receivers != null ? Lists.newArrayList(receivers) : null;
         return this;
     }
@@ -357,22 +359,77 @@ public ParticleBuilder offset(final double offsetX, final double offsetY, final
     }
 
     /**
-     * Gets the Particle extra data. Varies by particle on how this is used
+     * Gets the Particle extra data (speedX). Varies by particle on how this is used
      *
      * @return the extra particle data
+     * @deprecated use one of the {@code speed} methods instead
      */
+    @Deprecated(since = "26.3", forRemoval = true)
     public double extra() {
-        return this.extra;
+        return this.speedX;
     }
 
     /**
      * Sets the particle extra data. Varies by particle on how this is used
      *
      * @param extra the extra particle data
      * @return a reference to this object.
+     * @deprecated use {@link #speed(double)} instead
      */
+    @Deprecated(since = "26.3", forRemoval = true)
     public ParticleBuilder extra(final double extra) {
-        this.extra = extra;
+        return this.speed(extra);
+    }
+
+    /**
+     * Particle speed X. Varies by particle on how this is used
+     *
+     * @return the particle speed X
+     */
+    public double speedX() {
+        return this.speedX;
+    }
+
+    /**
+     * Particle speed Y. Varies by particle on how this is used
+     *
+     * @return the particle speed Y
+     */
+    public double speedY() {
+        return this.speedY;
+    }
+
+    /**
+     * Particle speed Z. Varies by particle on how this is used
+     *
+     * @return the particle speed Z
+     */
+    public double speedZ() {
+        return this.speedZ;
+    }
+
+    /**
+     * Sets the particle speed. Varies by particle on how this is used
+     *
+     * @param speed Particle speed
+     * @return a reference to this object.
+     */
+    public ParticleBuilder speed(final double speed) {
+        return this.speed(speed, speed, speed);
+    }
+
+    /**
+     * Sets the particle speed. Varies by particle on how this is used
+     *
+     * @param speedX Particle speed X
+     * @param speedY Particle speed Y
+     * @param speedZ Particle speed Z
+     * @return a reference to this object.
+     */
+    public ParticleBuilder speed(final double speedX, final double speedY, final double speedZ) {
+        this.speedX = speedX;
+        this.speedY = speedY;
+        this.speedZ = speedZ;
         return this;
     }
 
@@ -419,6 +476,26 @@ public ParticleBuilder force(final boolean force) {
         return this;
     }
 
+    /**
+     * Gets the randomization type for the particle. This determines how the particle's position and velocity are randomized.
+     *
+     * @return the randomization type for the particle
+     */
+    public Particle.RandomizationType randomizationType() {
+        return this.randomizationType;
+    }
+
+    /**
+     * Sets the randomization type for the particle. This determines how the particle's position and velocity are randomized.
+     *
+     * @param randomizationType the new randomization type for the particle
+     * @return a reference to this object.
+     */
+    public ParticleBuilder randomizationType(final Particle.RandomizationType randomizationType) {
+        this.randomizationType = randomizationType;
+        return this;
+    }
+
     /**
      * Sets the particle Color.
      * Only valid for particles with a data type of {@link Color}, {@link Particle.DustOptions} or {@link Particle.Spell}.

paper-api/src/main/java/org/bukkit/Particle.java

@@ -246,7 +246,6 @@ public NamespacedKey getKey() {
         return key;
     }
 
-    // Paper start - Particle API expansion
     /**
      * Creates a {@link com.destroystokyo.paper.ParticleBuilder}
      *
@@ -256,7 +255,29 @@ public NamespacedKey getKey() {
     public com.destroystokyo.paper.ParticleBuilder builder() {
         return new com.destroystokyo.paper.ParticleBuilder(this);
     }
-    // Paper end
+
+    /**
+     * The randomization type for the particle, which controls how offset and speed are randomized.
+     */
+    public enum RandomizationType {
+        /**
+         * The default randomization type, which multiplies each offset axis and each speed axis independently by its
+         * own Gaussian random value (similar to {@link java.util.Random#nextGaussian()} (mean 0, standard deviation 1).
+         */
+        DEFAULT,
+
+        /**
+         * Multiplies each offset axis independently by its own uniform random value in the range [0, 1)
+         * similar to {@link java.util.Random#nextDouble()}. Speed is left unmodified.
+         */
+        ALTERNATIVE,
+
+        /**
+         * Multiplies each offset axis <b>and</b> each speed axis independently by its own uniform random
+         * value in the range [0, 1) similar to {@link java.util.Random#nextDouble()}.
+         */
+        ALTERNATIVE_WITH_SPEED
+    }
 
     /**
      * Options which can be applied to dust particles - a particle