Update particle API to match changes in 26.3

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

@@ -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,70 @@ 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 This method is deprecated and will be removed in a future version. Use one of the <code>speed</code> methods instead.
      */
+    @Deprecated(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 This method is deprecated and will be removed in a future version. Use {@link #speed(double, double, double)} instead.
      */
+    @Deprecated(forRemoval = true)
     public ParticleBuilder extra(final double extra) {
-        this.extra = extra;
+        this.speedX = extra;
+        this.speedY = extra;
+        this.speedZ = extra;
+        return this;
+    }
+
+    /**
+     * 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 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 +469,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

@@ -258,6 +258,31 @@ public com.destroystokyo.paper.ParticleBuilder builder() {
     }
     // Paper end
 
+    // Paper start - RandomizationType support
+    /**
+     * 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
+    }
+    // Paper end
+
     /**
      * Options which can be applied to dust particles - a particle
      * color and size.

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

@@ -4139,7 +4139,39 @@ default <T> void spawnParticle(@NotNull Particle particle, double x, double y, d
      * @param force allows the particle to be seen further away from the player
      *              and shows to players using any vanilla client particle settings
      */
-    public <T> void spawnParticle(@NotNull Particle particle, @Nullable List<Player> receivers, @Nullable Player source, double x, double y, double z, int count, double offsetX, double offsetY, double offsetZ, double extra, @Nullable T data, boolean force);
+    public default <T> void spawnParticle(@NotNull Particle particle, @Nullable List<Player> receivers, @Nullable Player source, double x, double y, double z, int count, double offsetX, double offsetY, double offsetZ, double extra, @Nullable T data, boolean force) {
+        this.spawnParticle(particle, receivers, source, x, y, z, count, offsetX, offsetY, offsetZ, extra, extra, extra, data, force, Particle.RandomizationType.DEFAULT);
+    }
+    // Paper end
+
+    // Paper start - Update Particle API to match 26.3 changes
+    /**
+     * Spawns the particle (the number of times specified by count)
+     * at the target location. The position of each particle will be
+     * randomized according to {@link org.bukkit.Particle.RandomizationType} by the offset parameters
+     * on each axis.
+     *
+     * @param particle the particle to spawn
+     * @param receivers List of players to receive the particles, or null for all in world
+     * @param source Source of the particles to be used in visibility checks, or null if no player source
+     * @param x the position on the x axis to spawn at
+     * @param y the position on the y axis to spawn at
+     * @param z the position on the z axis to spawn at
+     * @param count the number of particles
+     * @param offsetX the maximum random offset on the X axis
+     * @param offsetY the maximum random offset on the Y axis
+     * @param offsetZ the maximum random offset on the Z axis
+     * @param speedX the speed of the particle on the X axis
+     * @param speedY the speed of the particle on the Y axis
+     * @param speedZ the speed of the particle on the Z axis
+     * @param data the data to use for the particle or null,
+     *             the type of this depends on {@link Particle#getDataType()}
+     * @param <T> Type
+     * @param force allows the particle to be seen further away from the player
+     *              and shows to players using any vanilla client particle settings
+     * @param randomizationType the type of randomization to use for the particle offsets
+     */
+    public <T> void spawnParticle(@NotNull Particle particle, @Nullable List<Player> receivers, @Nullable Player source, double x, double y, double z, int count, double offsetX, double offsetY, double offsetZ, double speedX, double speedY, double speedZ, @Nullable T data, boolean force, Particle.RandomizationType randomizationType);
     // Paper end
 
     /**

paper-server/src/main/java/org/bukkit/craftbukkit/CraftWorld.java

@@ -1751,7 +1751,7 @@ public <T> void spawnParticle(Particle particle, double x, double y, double z, i
     }
 
     @Override
-    public <T> void spawnParticle(Particle particle, List<Player> receivers, Player sender, double x, double y, double z, int count, double offsetX, double offsetY, double offsetZ, double extra, T data, boolean force) {
+    public <T> void spawnParticle(Particle particle, List<Player> receivers, Player sender, double x, double y, double z, int count, double offsetX, double offsetY, double offsetZ, double speedX, double speedY, double speedZ, T data, boolean force, Particle.RandomizationType randomizationType) {
         data = CraftParticle.convertLegacy(data);
         if (data != null) {
             Preconditions.checkArgument(particle.getDataType().isInstance(data), "data (%s) should be %s", data.getClass(), particle.getDataType());
@@ -1765,8 +1765,8 @@ public <T> void spawnParticle(Particle particle, List<Player> receivers, Player
             x, y, z, // Position
             count, // Count
             offsetX, offsetY, offsetZ, // Random offset
-            extra, // Speed?
-            ClientboundLevelParticlesPacket.RandomizationType.DEFAULT
+            speedX, speedY, speedZ, // Speed
+            ClientboundLevelParticlesPacket.RandomizationType.valueOf(randomizationType.name())
         );
 
     }